Node-RED projects turn your flows into a git repository, so every change is committed, reviewable and reversible. In this tutorial you will enable projects mode, create a project, commit and push to a remote, clone it onto another machine and, importantly, keep your MQTT broker credentials encrypted and out of the repository.
Why Version Control Your Flows
Without projects, Node-RED keeps everything in a single flows.json file in the user directory. When someone deploys a broken change, there is no history to look at and no easy way back. Copies of flows travel by email or chat as exported JSON, and nobody is sure which version runs in production.
Projects fix this with tools developers already know:
- History. Every commit records who changed what and when.
- Diffs. The editor shows node-level differences before you commit.
- Branches. Try a risky change on a branch, then merge it when it works.
- Remotes. Push to GitHub, GitLab, Gitea or Azure DevOps for backup and collaboration.
- Dependencies. Each project has a
package.jsonlisting the nodes it needs, so a new machine knows what to install.
Prerequisites
Projects rely on the git command line and, for SSH remotes, ssh-keygen. Check both are installed on the machine running Node-RED:
git --version
ssh-keygen -h 2>&1 | head -1
On Debian, Ubuntu or Raspberry Pi OS, install git with sudo apt install git. The official Docker image already includes git.
Enable Node-RED Projects
Projects mode is off by default. Open settings.js in your user directory (~/.node-red/settings.js, or /data/settings.js in Docker), find the editorTheme section and enable it:
editorTheme: {
projects: {
enabled: true,
workflow: {
// "manual": you commit explicitly
// "auto": Node-RED commits on every deploy
mode: "manual"
}
}
},
Restart Node-RED. The first time you open the editor, a welcome screen offers to create a project, clone a repository or skip. Manual mode is the better default for teams: you deploy as often as you like while testing and commit only when a change is ready, with a meaningful message.
Create Your First Project
- Choose Create Project on the welcome screen, or later via Projects → New in the main menu.
- Enter your git user name and email if asked; these appear in commit history.
- Name the project, for example
plant-telemetry. - Choose a flow file name. The default
flow.jsonis fine. - Set up credentials encryption. Pick "Enable encryption" and enter a strong key. Store it in your password manager.
- Click Create Project.
Node-RED creates a folder under projects/ in the user directory with this layout:
~/.node-red/projects/plant-telemetry/
.git/
.gitignore
README.md
package.json
flow.json
flow_cred.json
The credentials file is encrypted with the key from step 5, and that key is stored in your local Node-RED runtime settings, not in the repository. That is the design that keeps broker passwords out of git: the repository contains only ciphertext, and only machines you give the key to can decrypt it.
Build a Flow and Commit It
Add a simple MQTT flow so there is something to version. Configure a broker node for the free public MQTT broker with server broker.connectmq.com, port 1883 and a unique client ID such as nr-proj-a19e. Subscribe an mqtt in node to connectmq/demo/a19e/# and wire it to a debug node. Deploy.
Open the Project history tab in the sidebar (the git icon). Under Local Changes you will see the flow file listed as modified. Click it to see a visual diff of the nodes you added. Stage the file, write a commit message such as "Add telemetry subscriber" and commit.
Now make a change, perhaps renaming the debug node, and deploy again. The history tab shows a fresh diff of exactly that change. This is where Node-RED projects pay off: in a review, you see that one property changed rather than an unreadable JSON blob.
Push to a Remote Repository
Create an empty repository on your git host. In Node-RED, open Projects → Project Settings → Settings → Git remotes and add the remote URL.
For SSH remotes, generate a key inside Node-RED via User Settings → Git config → SSH Keys → Add key. Node-RED shows the public key; add it to your git host as a deploy key with write access. HTTPS remotes with a personal access token also work, and Node-RED will prompt for credentials on the first push.
Back in the history tab, the Commit History section now shows push and pull arrows. Push your commits. From the terminal, you can verify the repository contents:
git clone git@github.com:your-org/plant-telemetry.git
cd plant-telemetry
cat flow_cred.json # prints ciphertext such as {"$":"8f2c..."}
Keep Broker Credentials out of Git
Credentials need a deliberate strategy. You have three reasonable options:
| Strategy | What goes into git | Key handling | Good for |
|---|---|---|---|
| Encrypted credentials file (default) | flow_cred.json as ciphertext |
Key entered once per machine | Most teams |
| Ignore the credentials file | Nothing | Credentials typed into each instance | Strict policies against any secrets in git |
| Environment variables | Only ${VAR} references in non-secret fields, secrets in env |
Set per environment | Containers and CI pipelines |
For the second option, add flow_cred.json to .gitignore and re-enter the MQTT username and password on each instance after cloning. For the third, define values such as the broker host or client ID prefix as environment variables and read them in node properties with ${MQTT_HOST} or in function nodes with env.get().
Whichever you pick, follow two rules. Never paste a password into a function node or an inject node, because those are stored in plain text in the flow file. And use separate broker credentials per environment, so a development instance can never publish into production topics; with ConnectMQ that can be as simple as a separate broker for each environment. Our secure Node-RED checklist covers the remaining hardening steps.
Clone a Project on Another Machine
On a second Node-RED instance with projects enabled, choose Projects → New → Clone Repository, enter the remote URL and, if the credentials file is encrypted, the credentials key. Node-RED clones the repository, reads package.json and tells you which nodes are missing. Install them from the prompt or with npm in the project folder, then deploy.
With Docker, clone into the mounted /data/projects folder so the project survives container recreation; see our Node-RED Docker guide for the volume setup.
Node-RED Projects Workflow Checklist
- Enable projects in manual mode and restart Node-RED.
- Create one project per deployable application, not one per tab.
- Enable credentials encryption and store the key in a password manager.
- List every contributed node in
package.jsonwith a version range. - Commit small, described changes; review diffs before committing.
- Use branches for experiments and merge when tested.
- Push to a remote after every meaningful commit.
- Keep environment-specific values in environment variables, not in the flow.
- Use separate MQTT credentials for development and production brokers.
Reusable logic is easier to version when it lives in Node-RED subflows, because a change to one template shows up as one clear diff. The official projects documentation covers advanced settings and the full editor UI. If you are just getting started with MQTT in Node-RED, begin with the Node-RED MQTT tutorial.
Version Your Flows, Let ConnectMQ Run the Broker
Projects give your flows history and repeatable deployments; the broker they connect to should be just as dependable. ConnectMQ is a managed MQTT broker with MQTT 3.1.1 and 5.0, TLS on 8883 and per-broker credentials, so it is simple to create separate brokers for development and production and keep each environment's credentials apart. Start with the free Serverless plan at app.connectmq.com, no credit card needed. To compare hosting approaches, see our overview of running an MQTT broker in the cloud.
Frequently Asked Questions
How do I enable projects in Node-RED?
Set editorTheme.projects.enabled to true in settings.js, make sure git is installed and restart Node-RED. The editor then offers to create or clone a project.
Are MQTT passwords stored in git with Node-RED projects?
Only in encrypted form, if you enable credentials encryption. The credentials file contains ciphertext, and the key stays on each machine. You can also add the credentials file to .gitignore.
Can I use GitHub with Node-RED projects?
Yes. Add the repository as a remote using SSH with a key generated in Node-RED or HTTPS with a token, then push and pull from the Project history sidebar.
What is the difference between manual and auto workflow mode?
In manual mode you commit explicitly when a change is ready. In auto mode, Node-RED creates a commit every time you deploy, which is simpler but produces a noisier history.
