Change, JSONata, or Function: Choosing a Node-RED Message Transformation Node

State the decision and constraints

When a Node-RED flow receives a message, the message travels as a JavaScript object conventionally called msg. The payload property usually holds the data you want to change, while properties such as topic carry metadata. You must choose among three built-in nodes to reshape that data: Change, JSONata, and Function.

Use this decision:

• Change node: move, copy, set, or delete a property, or apply a simple regular expression.
• JSONata expression: read-only mapping, filtering, or computation across fields.
• Function node: arbitrary JavaScript, loops, external modules, or side effects such as writing to context.

Constraints to keep in mind:

• Maintainability: flows should remain auditable without reading custom code.
• Security: avoid untrusted JavaScript in Function nodes.
• Resources: Node-RED runs on a single event loop, so poorly written JavaScript can freeze all flows on embedded hosts.

Compare the supported options

Node	Best for	Limitations
Change	Set, move, copy, or delete msg properties; simple regex	Cannot compute values across multiple fields or branch on conditions
JSONata	Transform, map, filter, or compute values from an existing payload	Read-only expression language; cannot modify msg outside the assigned property or call Node-RED runtime APIs
Function	Loops, custom JavaScript, npm modules, or side effects	Harder to audit and visually debug; can block the Node-RED event loop if poorly written

Trade-offs

The Change node is fastest to configure and easiest to review, but it cannot combine two fields into a new value. JSONata keeps logic declarative and side-effect free, yet debugging a long expression is harder than stepping through JavaScript. The Function node offers full JavaScript power, but it breaks visual debugging, requires careful error handling, and can block Node-RED's single-threaded event loop if it contains long-running or synchronous work.

Concrete implementation: reshape an IoT payload

Suppose a device sends this message:

{ "deviceId": "sensor-01", "status": "ok" }

Goal: set msg.topic from deviceId, convert status to uppercase, and inspect the result.

1. Drag an Inject node onto the canvas. Set its output type to JSON and paste the sample object above.
2. Drag a Change node. Add a rule: Set msg.topic to msg.payload.deviceId.
3. Drag a second Change node. Set its rule type to JSONata expression. Set msg.payload to $uppercase(payload.status).
4. Drag a Debug node. Configure it to output the complete msg object.
5. Wire the nodes in order: Inject to the first Change node, to the second Change node, to Debug.
6. Deploy the flow.

Expected result after clicking the Inject button: msg.topic is sensor-01 and msg.payload is OK. The original deviceId is preserved in topic even though payload was overwritten.

Limitations and how to check the result

JSONata expressions cannot modify msg outside the property you assign, and they have no access to Node-RED runtime APIs. Function node code is not sandboxed by default, so review third-party code before deploying. Never store secrets or credentials in msg properties; use Node-RED credentials configuration and environment variables instead.

Rollback after deployment

Deploying changes the running runtime. If the new flow misbehaves, use the editor's undo or re-import the previously exported flow JSON and redeploy.

Version assumptions

Behavior described here applies to Node-RED 3.x LTS and current 4.x releases. JSONata is built-in. Access to external npm modules from a Function node depends on the functionExternalModules setting in settings.js; editing that file requires file-system access to the Node-RED installation directory and a restart of Node-RED.

Practical verification

1. Open the Node-RED editor, select the menu, and choose About to confirm the version.
2. Deploy the flow.
3. Click the Inject node button.
4. Open the Debug sidebar and inspect the message.
5. Confirm msg.topic is sensor-01 and msg.payload is OK.
6. Export the flow to JSON and store it in version control for peer review.