node-red-contrib-file-nunjucks 1.2.0
A secure Node-RED node for template processing with sandboxing, file watching and multiple engines support
node-red-contrib-file-nunjucks
A powerful Node-RED node for rendering Nunjucks (Jinja2-style) templates from files or inline, with support for inheritance, blocks, filters and Markdown.
✨ Features
- 📁 File-based Templates: Load Nunjucks/Markdown templates from the filesystem
- 🔄 Auto-reload: Watches template files and reloads on changes
- 🧩 Template Inheritance: Full support for
{% extends %}
and{% block %}
- 🧮 Logic Support: If statements, loops, macros, async tags
- 🎯 Multiple Engines: Choose between Mustache, Handlebars or Nunjucks
- 📊 Status Indicators: Visual feedback on file load status and errors
- 🛡️ Error Handling: Fallback to inline templates when files are unavailable
- ⚙️ Editor Integration: Snippets & autocomplete in Node-RED editor
- 📝 Markdown Ready: Output remains as Markdown if needed
- ⚡ Performance: Efficient caching and change detection
🔧 Installation
Via Node-RED Palette Manager
- Go to Node-RED settings → Manage Palette → Install
- Search for
node-red-contrib-file-nunjucks
- Click Install
Via npm
cd ~/.node-red
npm install node-red-contrib-file-nunjucks
Manual Installation
git clone https://github.com/untitledds/node-red-contrib-file-nunjucks.git
cd node-red-contrib-file-nunjucks
npm install
npm link
cd ~/.node-red
npm link node-red-contrib-file-nunjucks
⚠️ Make sure you have installed
nunjucks
:
npm install nunjucks
💡 Usage
Basic Usage
Drag the File Nunjucks node into your flow (under the
template
category)Double-click to configure:
- Template File: Path to your
.md
or.njk
file (e.g.,templates/incident.njk
) - Engine: Choose:
mustache
,handlebars
, ornunjucks
- Data Source: Message property containing data (default:
payload
) - Output Format: Set
msg.template
asstring
orparsed JSON
(if applicable)
- Template File: Path to your
Connect your data source to the input
Use output in Dashboard, Email, Debug, etc.
📄 Example Flow
[
{
"id": "nunjucks-node",
"type": "file-nunjucks",
"name": "Incident Report",
"filename": "templates/incident.njk",
"engine": "nunjucks",
"field": "payload",
"fieldType": "msg",
"output": "str"
}
]
📄 Template Syntax Examples
Base Template (base.njk
)
# {{ title }}
{% block content %}
Default content
{% endblock %}
Child Template (incident.njk
)
{% extends "base.njk" %}
{% block content %}
## Incident Details
- **Event**: {{ alert.event }}
- **Severity**: {{ alert.severity }}
- **Tags**:
{% for tag in alert.tags %}
- {{ tag }}
{% endfor %}
{% endblock %}
Input Message
{
"payload": {
"alert": {
"event": "High CPU Load",
"severity": "critical",
"tags": ["production", "server"]
},
"title": "System Alert"
}
}
Output (Markdown)
# System Alert
## Incident Details
- **Event**: High CPU Load
- **Severity**: critical
- **Tags**:
- production
- server
🧩 Configuration Options
Option | Description | Default |
---|---|---|
Name | Node display name | (auto-generated) |
Template File | Path to template file (optional) | none |
Engine | Template engine: mustache / handlebars / nunjucks | nunjucks |
Inline Template | Inline template content (fallback) | empty |
Data Source | Message property with template data (payload by default) |
payload |
Source Type | Where to get data from: msg , flow , global |
msg |
Output | Output format: str or parsed |
str |
🖥️ Editor Snippets
✅ Built-in snippets for Jinja2/Nunjucks syntax:
Shortcut | Inserts |
---|---|
block |
{% block %}...{% endblock %} |
extends |
{% extends "..." %} |
include |
{% include "..." %} |
if |
{% if %}...{% endif %} |
for |
{% for %}...{% endfor %} |
var |
{{ variable }} |
filter |
` |
comment |
{# comment #} |
📁 File Watching
The node automatically watches your template files for changes:
- ✅ File Modified: Automatically reloads content when saved
- ⚠️ File Deleted: Shows warning, falls back to inline template
- 🔄 File Restored: Detects and reloads automatically
- 📊 Status Updates: Visual indicators show current file status
🌈 Status Indicators
Color | Meaning |
---|---|
🟢 Green | Template file loaded successfully |
🟡 Yellow | Using fallback inline template |
🔴 Red | Error loading file or processing template |
⚪ Grey | No file specified or node inactive |
📤 Output Format
The processed template is added to msg.template
and includes metadata:
{
"template": "# System Alert\n...",
"_fileTemplate": {
"filename": "templates/incident.njk",
"lastModified": 1718000000,
"length": 256,
"engine": "nunjucks"
}
}
🧰 Use Cases
📋 Markdown Reports
Generate dynamic reports in Markdown:
[data] → [file-nunjucks] → [debug/email/http]
📬 Email Templates
Render HTML or plain text emails dynamically:
[trigger] → [data] → [file-nunjucks] → [email sender]
📊 Dashboard UI
Use Nunjucks templates inside Node-RED Dashboard:
[file-nunjucks] → [ui_template]
📄 Document Generation
Create templates for PDF, DOCX, etc.:
[data query] → [file-nunjucks] → [pdf converter]
🛠 Advanced Features
Multiple Data Sources
Pull template data from:
msg
- From incoming message (default)flow
- From flow contextglobal
- From global context
Filters & Macros
Register custom filters/macros in context:
context.nj.addFilter('uppercase', str => str.toUpperCase());
Async Support
Support for asynchronous tags like {% asyncEach %}
Partials
Use {% include %}
and {% import %}
for reusable components
🔍 Troubleshooting
Common Issues
Template file not found
- Check path is relative to Node-RED working directory
- Ensure file exists and has proper permissions
Variables not substituting
- Verify data structure matches your template keys
- Ensure correct engine selected (
nunjucks
vsmustache
)
File watching not working
- Some systems (like Docker or network drives) may have issues
- Restart Node-RED if it stops detecting changes
🔄 Fork Notice
This project is a maintained fork of the original node-red-contrib-file-template created by @DanEdens.
The original repository has been extended to support:
- Nunjucks (Jinja2-style) templates with inheritance and blocks
- Markdown-ready output
- Enhanced editor snippets and autocomplete
- Full support for modern template workflows
All credits for the initial implementation go to Dan Edens.
🛡️ License
MIT License — see LICENSE for details
🤝 Contributing
- Fork the repo
- Create a feature branch
- Make changes
- Add tests where applicable
- Submit a PR
📣 Support
- 🐛 Issues: GitHub Issues
- 💬 Discussions: GitHub Discussions
🔄 Related Nodes
- node-red-dashboard – For UI rendering
- node-red-node-email – Send templated emails
- node-red-contrib-ui-template – Custom dashboard widgets
- node-red-contrib-file-template -