Version-Controlled Flows: Using Node-RED Projects with Git

Node-RED saves flows to a single flows.json file by default, which makes sharing work, rolling back a bad deploy, or collaborating with a teammate awkward. The built-in Projects feature fixes this by putting your flows under Git version control directly from the editor. This guide walks through enabling Projects, creating a project, committing changes, and recovering from common problems.

What you need before starting

• Node-RED v1.0 or later (Projects shipped in 1.0; the examples here assume a 1.x/2.x/3.x install with the default ~/.node-red user directory).
• Git installed and available on the system PATH. Check with git --version in a terminal on the machine running Node-RED.
• Write permission for the Node-RED process user on the user directory (where settings.js lives).
• Optional: a remote Git repository (GitHub, GitLab, or a private server) if you want to push or share flows.

Enable Projects in settings.js

Projects are disabled by default. Open settings.js in your Node-RED user directory (commonly ~/.node-red/settings.js) and find the editorTheme section. Add or uncomment the projects block:

editorTheme: {
    projects: {
        enabled: true
    }
}

Restart Node-RED for the change to take effect. How you restart depends on how it runs: systemctl restart nodered for a systemd service, docker restart <container> for Docker, or Ctrl+C and relaunch for a foreground process.

Check: after restart, the editor shows a Projects button in the sidebar (top right), and a projects/ directory plus a .config.projects.json file appear inside your user directory.

Create your first project

1. In the editor, open the Projects sidebar and choose to create a new project.
2. Give it a name. Node-RED initialises a Git repository under ~/.node-red/projects/<name>/ and moves your active flow file into it.
3. Optionally set your Git username and email when prompted — these are written into the repo config and used for commit authorship.

If you already have flows in a remote repository, choose the clone option instead and provide the repository URL. For SSH remotes, the editor can generate a key pair and show you the public key to add to your Git host.

Day-to-day workflow: edit, deploy, commit

Editing flows works exactly as before. The difference is what happens on Deploy: Node-RED writes the flow file inside the project repo, and the Projects sidebar shows the changed files. From there you can:

• Commit: open the commit dialog in the sidebar, write a message, and commit staged changes.
• Push/pull: use the remote buttons once a remote is configured.
• History: view the commit log and diff individual commits against the working copy.

A typical verification loop looks like this:

1. Make a small visible change (rename a node or move it).
2. Click Deploy.
3. In the Projects sidebar, confirm the flow file appears as modified, then commit it.
4. In a terminal, run cd ~/.node-red/projects/<name> && git log --oneline -3 — your commit should appear, and git status should report a clean working tree.

Keep the repository healthy

Two practical rules prevent most pain:

• Add a .gitignore. Node-RED creates one by default, but extend it if your flows pull in local files. Never commit node_modules/ or large payload files — repository bloat slows every clone and pull.
• Keep credentials out of flows. Credentials are stored separately in flows_cred.json; treat that file as sensitive and do not push it to a public remote. Use environment variables or the credential secret mechanism instead.

Recovery options

Because every deploy is a file change and every commit is a snapshot, recovery is straightforward:

• Bad deploy, not yet committed: in a terminal, run git checkout -- flows.json (or your flow filename) inside the project directory to restore the last committed version, then restart Node-RED or redeploy.
• Committed mistake: use git revert <commit> or check out an earlier commit of the flow file, then restart Node-RED.
• Lost or corrupted project folder: delete or rename the broken folder, then re-clone the project from the remote via the Projects sidebar. Confirm the flows load and the remote URL is correct afterward.

If commits fail silently, the usual cause is permissions: confirm the Node-RED process user can execute git and write to the project directory. Check the Node-RED log (journalctl -u nodered on systemd systems) for Git error messages.

Limitations to know

Projects manage flow files and project-level dependencies, not your installed palette nodes globally — a fresh clone on another machine still needs npm install in the project directory (Node-RED can prompt for this). Merge conflicts in flows.json are possible when two people edit the same flow; resolve them with standard Git tooling outside the editor. Finally, Projects is a single-active-project model: only one project's flows run at a time, so it is not a multi-tenant deployment mechanism.