Node-RED Subflows: Encapsulate Reusable Logic Without Copy-Paste

The Problem: Repeating Logic Across Flows

You've built a flow that converts sensor readings from Celsius to Fahrenheit. Three other flows need the same conversion. Copying the function node works until you discover a rounding bug — now you have four places to fix. Node-RED subflows solve this by letting you package nodes into a single, reusable component that lives in your palette.

What a Subflow Actually Is

A subflow is a collection of nodes grouped together and exposed as a single node in the palette. When you edit the subflow definition, every instance updates automatically. Think of it like a function in code: define once, call many times, change in one place.

Subflows live in the same .flows.json file as your main flows. They're scoped to the Node-RED instance — moving them to another project requires exporting the subflow to the library or copying the JSON.

Building a Temperature Conversion Subflow

Step 1: Create the Subflow

1. Open the Node-RED editor (typically http://localhost:1880).
2. Click the menu (☰) → Subflows → Create Subflow.
3. Name it "Celsius to Fahrenheit" and add a description.
4. In the subflow editor, drag a function node onto the canvas.
5. Double-click the function node and paste:

msg.payload = (msg.payload * 9/5) + 32;
return msg;

1. Click Done.
2. Notice the gray "input" and "output" ports on the subflow tab — these represent the subflow's interface. Connect the function node between them.
3. Click Done on the subflow tab to save.

Step 2: Expose a Configurable Property (Optional)

If you want the conversion formula to be configurable (e.g., support Kelvin later), you can expose properties:

1. Reopen the subflow for editing.
2. Click the Properties tab in the subflow edit dialog.
3. Click +add → choose "Input" → name it "offset" with type "number" and default "32".
4. Update the function node to use msg.offset || 32 instead of hardcoded 32.
5. Save. Now each instance can override the offset via msg.offset.

Step 3: Use the Subflow in a Main Flow

1. Return to your main flow tab.
2. Find "Celsius to Fahrenheit" in the palette (under the subflows category).
3. Drag it onto the canvas.
4. Add an inject node, set payload to 25 (number type), and name it "25°C".
5. Add a debug node.
6. Wire: inject → subflow → debug.
7. Click Deploy.
8. Click the inject button. The debug sidebar should show 77 (25°C = 77°F).

Verification Checklist

• Deploy succeeds without errors.
• Debug output matches expected conversion: (input * 9/5) + 32.
• Edit the subflow function node (e.g., change to msg.payload = msg.payload * 1.8 + 32), redeploy, and verify all instances reflect the change immediately.

Trade-offs and Limitations

Debugging Inside a Subflow

Breakpoints set on nodes inside a subflow apply to the subflow instance, not the internal nodes directly. You can't step into a subflow's internal nodes from the main flow debugger. Workaround: add a temporary debug node inside the subflow during development, or test the subflow logic in a separate flow first.

Portability

Subflows are stored in the flow file. To share across projects or teams, use the library feature: right-click the subflow in the palette → "Export to library". Import it in another Node-RED instance via the library sidebar.

Environment Variables

Subflows can reference env.get('VAR_NAME') for instance-specific configuration, but the variable must be set in the Node-RED settings.js or via the command line — not per-instance in the editor.

When to Reach for a Subflow

• You have 3+ flows using identical node sequences.
• The logic is stable enough that changes should propagate everywhere.
• You want to hide complexity from the main flow canvas.

Avoid subflows for one-off logic or when each instance needs significantly different behavior — that's what function nodes with msg properties are for.

Next Steps

Open your Node-RED editor and identify a repeated pattern — maybe a timestamp formatter, an MQTT topic builder, or an error-handling chain. Wrap it in a subflow, deploy, and verify the debug output. Then try editing the subflow and watch every instance update. That's the moment the abstraction pays off.