Skip to content
GitHub

Bring your Node-RED flows

Flow reads Node-RED’s v1 flows.json format, the flat JSON array that every Node-RED export and flow library entry is written in. Point it at your file and it runs.

It loads and saves byte for byte. Load a file, save it without editing anything, and you get identical bytes back: same key order, same spacing, no helpfully rewritten escapes. Edit one property and the diff is one line rather than the entire node.

That is harder in Go than it sounds. A JavaScript object preserves key insertion order, so a JavaScript runtime gets this for free from JSON.parse and JSON.stringify without anybody thinking about it. A Go map has no order at all and encoding/json deliberately sorts keys. Rather than force an order-preserving map through every read path in the codebase, each entry’s original bytes are kept and re-emitted when the parsed form is unchanged, then re-encoded against the original key order when it is not. json.Compact and json.Indent are byte-level transforms, so they re-indent without reordering anything.

It matters for two reasons, both boring and both real. Your flow file lives on a volume and in git, and it should not churn just because a pod restarted. And when an operator reviews a deploy diff before pushing it to a line, they should see what changed and absolutely nothing else. That rule stays, even as tests and types land in the file: new data goes in keys other tools ignore, and the round-trip test covers files that carry them.

A node type this build has never heard of survives a load-and-save with every property intact, so it’s safe to run a flow here and hand it back afterwards. Node-RED’s flows_cred.json, which is AES-256-CTR, imports read-only, and anything read that way is re-encrypted under GCM on the next save.

Before you deploy anything, ask it what is going to happen:

Terminal window
hotloop-flow import flows.json

It reports every node type in the file, including the ones inside subflows, split into supported, partially supported with the gap spelled out, and not supported at all. Subflow internals are counted against the expanded graph rather than the file, so an instance never gets reported as “supported” while staying silent about what is inside it. That is the difference between finding out at your desk and finding out when a line stops.

A node can also point at a config node that is not in the file. Delete a flow and its own MQTT broker goes with it, while a subflow that used that broker keeps pointing at an id that names nothing. A hand edit or a half-copied export does the same thing. We used to find that out when the first message hit the node, and the nodes that only look their server up then said nothing at all. Now the import report has a section for it that names every node and the id it can’t find, the editor puts the same lines in the log when it loads, and a deploy answers with them and marks those nodes as failed to start, with the property that holds the bad id. The rest of the flow keeps running. A node you disabled, and a TLS setting that is blank or says true or false, are not reported, because those are not mistakes.

An id that exists is not the same as an id that works. We missed that the first time. If the setting points at a tab, a subflow, a group or a plain node, or at a config node of the wrong kind, like a TLS setting aimed at an MQTT broker, it gets the same report and the same failed start, and the line says what the id actually is and which kind the setting wants. The editor only offers you the right kind, so this only comes from a hand edit or a pasted id, which is exactly where it bites.

By compatibility level the 108 message node types are 12 full, 50 partial, 14 deliberately divergent, and 32 of Flow’s own. Every node declares how it relates to Node-RED’s node of the same name, and a test fails the build if a node claims partial compatibility without stating in writing what is missing. A node that is 90% compatible and silent about the other 10% is more dangerous than one that is obviously absent, because the first one lets a flow appear to work. The full matrix is Node-RED compatibility, generated from the registry rather than maintained by hand, because a hand-maintained compatibility document is a lie with a timestamp.

The divergences are deliberate and each one is written down there: every recipient on a fan-out gets its own copy, the exec node has an allowlist and no shell, the file nodes are scoped, and everything listed under Back-pressure, visibly has a ceiling.

Most Node-RED community nodes do not run here. They are npm packages that need Node.js, and there is no future version of this where a package that needs Node suddenly does. That is the trade you make for the footprint and the sandbox, stated plainly so you can decide against it. Signed WASM plugins are Flow’s answer for what you write yourself: see Plugins without npm.

The community nodes a plant leans on are another matter. Flow runs the Node-RED Modbus, dashboard, PostgreSQL and e-mail types natively, in Go, under their own type names, so a flow that uses them loads and runs unchanged, and so do the Buffer and setInterval that the function nodes around them call. What runs, what differs and what was proven is docs/node-red-types.md. Any other community node in a flow fails by itself with its type named, and the rest of the flow starts.

JSONata used to top the list of what an imported flow trips over. The 13 that don’t are pinned in a test with the reason for each, and ten of those still raise an error, just with a different code. $moment is the one Node-RED function you’ll miss, and it tells you what to use instead of failing quietly.

Cron-scheduled Inject nodes were next on that list. They fire now, and on the same minute Node-RED’s would: the crontab is read by a port of cronosjs 1.7.1, the scheduler inside Node-RED’s own Inject node, and checked against 22,620 firings cronosjs itself produced across six time zones, either side of real clock changes. That matters at 2 AM. A shift start that lands in the hour that goes missing in spring runs the moment the clocks jump, and the hour that repeats in autumn runs once, not twice. The schedule also rereads the wall clock every minute, so a box that boots with the wrong time and gets fixed by NTP later starts firing on the right one instead of hours late.

Link Call was the last of the three. It works now, Link Out’s return mode with it: one piece of logic, “look up this batch”, “check this interlock”, written once on its own tab and called from every line, with the way back kept on the message as a stack, so a called flow can make calls of its own. A call that never comes back raises an error after its timeout instead of hanging. A return that turns up late still goes out, as it does in Node-RED. And a return with nothing to return to is an error a Catch node sees, instead of the warning Node-RED logs and nobody reads.