Node-RED allows you to quickly start developing applications by dragging in nodes and connecting them together to create a flow. This can be a great way to get started, but as traffic grows over time, it can make the application harder to maintain.
This guide provides some suggestions and best practices on how to create Node-RED flows that are reusable, easier to maintain, and more robust.
This guide assumes that you are already familiar with the basic usage of Node-RED. If you’re looking for more information about using Node-RED, the User Guide and Cookbook are great resources to get you started.
process structure
This section describes how to organize processes, strategies for breaking processes into smaller, reusable components, and how to customize processes for different platforms.
message design
This section looks at how message design can help create nodes and flows that work together and are easier to maintain.
Documentation process
All good code should be matched by good documentation. This section describes what tools and techniques Node-RED provides to help you document them.
When you first start using Node-RED, you may start by adding all your nodes to the same tab of the editor. You can import some example flows that others have shared, or build prototype flows to test different things.
Over time, this can lead to a clutter of nodes and lines, making it difficult to find specific parts of the process.
Thinking about how processes will be structured at the beginning of any development project can help keep them organized and make them easier to maintain.
The main way to organize flows in Node-RED is to separate them into tabs in the editor. There are several different strategies you can use to do this.
If you can identify the separate logical components of your application, consider placing them on separate tabs.
For home automation applications, you can put the flow logic for each room on a separate tab to reflect the physical space. Or you might want to separate processes based on functionality – so all lighting-related processes are on one tab, and heating on another.
If you are building an HTTP API backend, each tab can represent a separate type of resource that the API accesses.
The goal should be to make it easy to “read” a single process from start to finish. Keeping it on a single tab can help with this.
Another consideration is whether you are working with other developers on the same Node-RED application. Managing the merging of changes is much easier if the changes are on separate tabs. If you have developers with different roles or specializations, consider how this might affect how your process is organized.
Make reusable processes
As you build your process, you may find some common parts that you want to reuse in multiple places. You should avoid spreading multiple copies of these common parts throughout your process, as they become harder to maintain – you’ll end up applying fixes in multiple places and it’s easy to overlook one.
Node-RED provides two different ways to create reusable flows – linked nodes and subflows.
Link Nodes Link nodes allow you to create a stream that jumps between tabs in the editor – they add a virtual connection from the end of one stream to the start of another.
A substream allows you to create a new node in the palette, and its internal implementation is described as a stream. You can then add a new instance of the subflow anywhere on a normal node.
There are some important differences between these two methods. Link nodes cannot be used in the middle of a process, where messages are passed through the link and then returned when other processes complete. They can only be used to start or end a process. They can also be connected to multiple other link nodes. This allows you to deliver messages to multiple other streams, or have multiple streams deliver messages to a single stream. They can be used in a single tab to help flow around the workspace without a lot of wires crossing from right to left.
Subflows appear as regular nodes and can therefore be used at any point in the flow. However, each instance of a subflow is independent of other instances. Any flow context within a subflow will apply to individual instances. If a subflow creates a connection to a remote system, each instance will create its own connection.
Custom subflow
When creating subflows, you may want to be able to customize their behavior in some way. For example, change the MQTT topic it publishes to.
One pattern for doing this is to set msg.topic for every message passed to the subflow. But this requires adding a Change node before each subflow instance to set the desired value.
A simpler approach is to use substream properties. These are properties that can be set on a subflow instance and appear as environment variables within the subflow.