node-red-contrib-template-njk

A Node-RED node that renders Nunjucks templates (Jinja2-inspired, by Mozilla).

This node provides a subset of Nunjucks functionality. It renders templates from a string and does not support file-based features such as include, extends, or import.

Table of Contents

• Install
• Node: template.njk
• Template variables
• Limitations
  • Not supported
  • No template modules
  • No file system access
  • No async features
  • Controlled context
• Automatic JSON stringification
• Output format
• Nunjucks quick reference

Install

cd ~/.node-red
npm install @inteli.city/node-red-contrib-template-njk

Node: template.njk

Renders a Nunjucks template using values from the incoming message, flow context, global context, and environment variables, then writes the result to a message property.

Template variables

Message properties are exposed at the root of the template context. Reference them directly without any msg. prefix.

| Variable | Value | |---|---| | {{ payload }} | msg.payload | | {{ topic }} | msg.topic | | {{ flow.get("key") }} | Flow context variable | | {{ global.get("key") }} | Global context variable | | {{ env.MY_VAR }} | OS environment variable |

{{ msg.payload }} is not supported. Using msg. in a template triggers a node error. Use {{ payload }} style instead.

Limitations

This node renders templates from a single string, not from files. This is a deliberate design choice that keeps templates self-contained and behavior predictable. Some Nunjucks features depend on a file system loader and are therefore not available.

Not supported

• {% include "file.njk" %}
• {% extends "base.njk" %}
• {% import "macros.njk" %}

These features require a template loader (file system or external source), which this node intentionally does not provide.

No template modules

Templates are self-contained per node. There is no shared template system between nodes.

• You cannot reuse templates across nodes
• You cannot define global macros or libraries

You can still define and use macros within a single template:

{% macro greet(name) %}
Hello {{ name }}
{% endmacro %}

{{ greet("world") }}

No file system access

Templates are not loaded from disk. Everything must be defined inline in the node editor, or passed dynamically via msg.template.

No async features

Rendering is synchronous. Async filters and async loaders are not supported.

Controlled context

Only the following are available inside templates:

• Message properties at the root (e.g. {{ payload }})
• Flow context via flow.get("key")
• Global context via global.get("key")
• Environment variables via env.MY_VAR

Direct msg.* access is intentionally blocked.

Automatic JSON stringification

If msg.payload is an object or array, it is automatically converted to a JSON string before the template renders. This means you never need to manually stringify objects to use them in a template.

msg.payload = { city: "São Paulo", pop: 12300000 }

template:
  City: {{ payload }}

output:
  City: {"city":"São Paulo","pop":12300000}

The original msg.payload is never mutated — the stringification only applies inside the template context.

Output format

The rendered string can optionally be parsed before being written to the output property:

| Setting | Behaviour | |---|---| | Plain text | Result is written as a string (default) | | Parsed JSON | Result is passed through JSON.parse() | | Parsed YAML | Result is parsed with js-yaml | | Parsed XML | Result is parsed with xml-js (compact mode) |

The output property defaults to msg.payload. The property field in the editor lets you write to any msg, flow, or global property instead.

Nunjucks quick reference

{# output a variable #}
{{ payload }}

{# apply a filter #}
{{ payload | upper }}
{{ payload | replace("foo", "bar") }}

{# conditional #}
{% if payload %}
  has value
{% else %}
  empty
{% endif %}

{# loop #}
{% for item in items %}
  - {{ item }}
{% endfor %}

{# set a variable #}
{% set label = "hello" %}

{# define a macro (reusable within this template) #}
{% macro greet(name) %}Hello {{ name }}{% endmacro %}
{{ greet("world") }}

{# access flow / global context #}
{{ flow.get("myKey") }}
{{ global.get("config") }}

{# access environment variables #}
{{ env.HOME }}
{{ env.MY_CUSTOM_VAR }}

Full Nunjucks documentation (note: not all features are supported): https://mozilla.github.io/nunjucks/templating.html