Node maintenance for dummies

Hi,

Anyone aware of any "node maintenance" documentation for existing nodes in github? I am thinking of something that describes good practices for fixing bugs/outdated dependencies of existing node red nodes in github. I know the material for creating new nodes but something that covers:

  • How can I fix an issue in an existing node through submitting a github pull request?
  • How do checkout and do local testing of an existing node?
  • How can I update a dependency of a node and check if it works?

Otherwise it might be a welcome addition to the documentation or a short video tutorial. Might make it easier for people to contribute to existing node red projects.

Hi @flipzz

To answer this will be to answer how to maintain any software, it's not an easy topic and one that is not specific to Node RED.

Maintaining a code base of a Node is no different to maintaining any other product.
There are of course some specifics - like the best way to test if changes to a node's code base are working.

But for submitting issues, raising PR's, this is not specific to Node RED - and plenty of guides on the internet for that - probably not the answer you are looking for, but it really is no different.

If you follow guides on Code Maintenance/GitHub/NPM in general, what you learn can be applied to Node RED Node Maintenance.

But I will address the way I do local testing of code changes in a Node.

Note: I have a dedicated Node RED install (i.e not production) for development purposes.

  • I first fork the repo in GitHub, and clone it locally - making a note of where I stored that clone.
    • It is this clone/fork where my changes originate, and a PR is raised
  • I then issue the npm install routine within that clone
    • This is to install its dependencies
  • I then cd to my .node-red directory and issue npm install <cloned-dir>
    • This creates a symbolic link to my clone, and Node RED will load it

From here, I change the code as necessary, and restart Node RED at each significant change I make.

For updating dependencies, I simply update them in the cloned package.json file, re-issue the npm install inside this clone, restart Node RED, so on and so forth.

There is not a 1 size fits all approach with this topic, but hopefully you can take something away from it.

I won't go into Nodes developed with Typescript and or unit testing - as that is too much of a complex topic for a forum (I think)

1 Like

Thank you very much Marcus for the answer.

I was looking for info about the Node Red specifics (as you outline quite a lot) when it comes to the flow module development more than general practices. Your post gives a good starting point.

Not node-red specific, but I did recently discover that there are a bunch of recommended GH actions that greatly improve the security and stability of your repo's - check out stepsecurity.io

I recently applied this to the UIBUILDER repo. One of the things it does is to automatically create pull requests against any GH action scripts and other dependencies. You can then apply or ignore as needed. I do this on my main branch and pull through any updates to development branches.

It also helps you lock down the repo to prevent unauthorised changes and will warn of any known dependency chain issues.

I get your point, might be nice to have something for node-red users. However, this is standard Git stuff which is easily looked up. Indeed GitHub themselves have good documentation.

This has been covered in the forum before but you are right, this should probably be another FAQ.

Here is how I do it.

  • Clone the repo to my own GH account.

  • Clone the copy to my local dev machine via GitHub Desktop.

  • Manually (command line) install the local clone to my dev instance of Node-RED:

    cd ~/.node-red
    npm install /local/path/to/clone/node-red-contrib-something
    cd /local/path/to/clone/node-red-contrib-something
    npm install
    

    That last 2 lines are important to get all the sub-dependencies locally installed. By default, you will get all the dev dependencies as well which is probably what you want.

  • Restart Node-RED

  • Edit using VSCode (some nodes might also need a build step)

  • Restart Node-RED on changes to any runtime components

  • Reload the Node-RED Editor on changes to any Admin components

I make use of PM2 with its file/folder watch feature to run my dev instance. When a watched file changes, it auto-restarts node-red for me.

If using something similar to the above process, at a command line inside the folder for the local clone of the repo, either install the updated dependency using npm with @latest on the end of the dependency name. Alternatively, edit the package.json file in that folder and then just run npm install which, of course, is easier if you've multiple dependencies to update.

After restarting Node-RED again, you will need to run through suitable tests to check everything is working. Some nodes might have test suites you can use. In that case, you'll also need to install the test apps as well - they may or may not have been included in the dev dependencies in package.json.


If you've made some successful changes, push them back upstream to your GH clone. Then in GH use the link it gives you to create a pull request against the original repo.

Along the way, check out the requirements that each repo will have for contributions. And before starting, engage with the node's author(s) on GH to make sure they are happy to get a PR.

I probably should say that my dev install does not use a "standard" install, I always use local installs of Node-RED, not "global" installs. That's for various reasons, mostly to do with being able to find things more easily and to be able to back everything up more easily. My userDir folder is not in the indicated position then but is rather always a sub-folder of the node-red install folder. Check out my node-red alternate install repo on GH for details.

I should also note that I do not leave the dev instance of Node-RED with the default settings. In particular, I change the path to the Editor (httpAdminRoot) and I add a path to httpNodeRoot. Some nodes make assumptions about URL paths that are incorrect and this always catches those errors.

If there is interest, I'm happy to create something in the FAQ category?

3 Likes

Thank you very much for your answers.

Would you be able to elaborate a bit more how your 'local' setup looks like? Like which install commands, folder structure etc. Would be very appreciated as I primarily use the global or docker installs.

Have a look at

It has the details.

I have a d:/src folder than contains all my development stuff whether Node-RED, Python, PowerShell, etc. So the folder structure for the dev node-red instance looks like:

/src/
  nr/
    (`npm install node-red` here if installing manually
      but the script in my alternate installer will to it for you)
    data/
       (this is the userDir folder. settings, flows, etc live here)

To install a locally cloned node:

cd /src/node-red-contrib-whatever
npm install
cd /src/nr/data
npm install /src/node-red-contrib-whatever
cd ..
npm restart

I have scripts defined in /src/nr/package.json that start and restart node-red (actually that tell PM2 to restart it since I run node-red under PM2 but that is optional).

If you want a different instance of node-red (potentially using a different version such as a beta version), you simply use the alternate installer script to install to a new folder, adjust either the environment variable or settings.js for the port and away you go.

If you want to back up the fully working system, you now have a single folder, e.g. d:/src/nr to back up. If you want to copy the working system to a new device or want a 2nd running copy, then you can do so very easily since everything lives together.

BTW, it helps if you do a bit of reading on how npm works. This is a magic tool and understanding it a little will make your node.js life vastly easier.


I would also say that this kind of setup is, in my view, greatly superior production configuration as well. Partly due to the ease of backup and maintenance. But also for ease of security - see the FAQ post on protecting Node-RED from itself - but this configuration also makes it easier to protect node-red from other things on your server. It also means that maintenance updates for node-red do not require root access, a more fine-grained access can be given.

If there is interest, I'm happy to create something in the FAQ category?

That would be very kind. I started to document a bit over here in case you want to add on. Thought it could be nice to start to iterate a bit on a good description. Have a look over at nr_docs/maintenance_introduction/docs.md at main · fasblom/nr_docs · GitHub