Moving a Node-RED MQTT Application: Choose Between Flow Export and Project Transfer

Choose the transfer unit before moving a Node-RED MQTT application to another gateway. A selected-node export, a complete flow export and a Git-backed project solve different parts of the job. None should be treated as proof that the receiving runtime has the same installed nodes, broker access or active application.

The practical question is whether the receiver needs a reusable fragment, the deployed flow topology or a maintainable application repository. Answering that question first prevents a visually successful import from becoming an incomplete commissioning handover.

Match the export scope to the requested outcome

The official flow import and export guide provides three export scopes: selected nodes, the current flow and the complete flow configuration. Import can place nodes into an existing flow or a new one. These are editor-level choices, so name the scope in the delivered package.

For a hypothetical MQTT temperature adapter, a selected transformation fragment may be enough for another engineer who already owns the broker connection and monitoring flow. It is a poor substitute for delivering the entire gateway application when those surrounding components are part of the requested work.

Before transfer, draw a boundary around the intended application. Include the receiving and publishing paths, configuration references, required subflows and operational monitoring that belong inside that boundary. Identify environment-owned settings separately. This is an application-specific dependency review, not a recommendation to export every unrelated flow on the development machine.

Use a project when versioned application ownership matters

Node-RED Projects provides Git-backed flow management and a project dependency list. The documentation identifies used-but-unlisted node modules as a state to resolve. It also distinguishes changed project files from staged and committed changes. A deployed editor change is therefore not automatically the revision a receiver can retrieve from Git.

For the temperature adapter, choose a named project revision as the reference and reconcile the modules used by its flows with the recorded dependencies. Inspect the repository diff before calling that revision the handover version. Record any required runtime settings or external files outside the project as separate deployment inputs.

A screenshot of the canvas is useful for orientation but cannot replace this inventory. It does not show which module version implemented a contributed node, or whether the working copy contains changes that were never committed.

Keep credential ownership explicit

The Projects documentation states that the credential-encryption key is not stored in the project. A receiver needs an authorized way to decrypt the credentials or must supply their own credentials. That is a deliberate transfer decision, not a missing value to repair by embedding a password in the flow or repository.

Prefer a commissioning process in which the receiving environment supplies its approved broker identity. Document the required credential role and endpoint without distributing live secrets in the explanatory package. If existing encrypted credentials must be transferred, use the organization's approved secret-management process and authorized recipients.

Treat project activation as a runtime change

Node-RED runs one project at a time; opening another project changes the running flows. Consequently, inspecting or switching a project on a production gateway is not equivalent to opening a passive document. Schedule activation through the site's change procedure and prepare an agreed recovery path.

Use a separate staging runtime to prove the transfer first. Confirm the selected revision, resolve missing modules and configure a test broker identity. Exercise one known input through the intended output, including the monitoring branches included in the application boundary. Check the receiving runtime's effective settings rather than assuming they arrived with the flow JSON.

This staging exercise has not been executed for this article. Its result should establish which artifact can be recreated and activated by the receiver, and which site-owned inputs remain necessary. A clean distinction between flow scope, project revision and runtime activation makes the transfer reviewable without confusing an imported canvas with a commissioned MQTT application.