How to proper debug custom node


I've created my fist custom node following the ufficial doc and so far it's fine, but is not really clear to me how to debug efficiently the node...everytime I modify something and want to test it out I need to re-install the node using npm install?

Hi @Deca

if you followed the guide, you should have run npm install <location of node module> which, if you have npm 5 or later, will have created a filesystem link between the .node-red directory and where your node is located. That means you don't need to reinstall the node each time - you just need to restart node-red.

Personally, I use nodemon to run node-red and have it automatically restart whenever it sees changes to the node files.


I now have a very strong muscle memory: ctrl-c, uparrow, enter (selects "y" to cancel the script), uparrow, enter (selects the last command which starts Node-RED) :slight_smile:

I often don't use a watcher because of another strong muscle-memory: ctrl-s !

As I develop using VScode, I have an npm start script to start the dev version of Node-RED manually. I also have a similar "inspect" script that starts Node-RED with Node.JS's inspect feature turned on so that I can dig into detailed debugging if needed. The Vivaldi browser (and I imagine all other Chromium-based browsers) has a handy icon in the developer tools interface that opens a Node.js debugging window. VSCode of course, also has this built in.

Sorry for the late reply, weekend arrived and then I had other urgent work to I'm back to testing my custom node :slight_smile:
I'm working on windows so I guess there no filesystem link generation, at the moment I was editing the node directly in the /node_modules directory...anyway I'll give a try to nodemon, because manually relaunching node-red every time I touch something is very exausting and timeconsuming

FS Links work fine on Windows and have done ever since NTFS was introduced.

Just use npm link in your custom node's devel directory to create a global link.
Then use npm link node-red-contrib-mynode in your NR workspace dir to "install" the node as a symbolic link. Substitute the package name, of course. :grinning:

Works fine on Windows, too.

I find it a lot easier and simpler to just npm install /path/to/source/code


I must admit, I have never tried that. :flushed:

I first started developing with NodeJS using Linux, so symlinks just felt as a natural tool. I symlinked the packages manually in the beginning, until I came across npm link. When we started developing NodeJS at work using Windows, I just kept that approach.

There are some advantages to this approach:

  • the workspace is relocatable, because the links always point to the location of your global npm package directory
  • you can just "install" it using its package name, no need to know the path to the package

That makes it easier for setup scripts (e.g. for a VSCode workspace) to get everything up and running. :grinning:

But I will surely give it a try. Maybe it works with relative paths, too.

1 Like

Actually, neither did I until recently.

That's what I was doing until npm messed it up. It used to work great but if you try that now, at least on Windows, running any kind of npm update/install overwrites the linked installation .. grrr.

I don't like using that on Windows as it does strange things with the links. It puts an intermediate link in the global area - weird.

I wouldn't ever want to do that, all my source code is in a fixed place. c:\src. Also, my dev node-red installation sits in c:\src\nr rather than global with the userDir folder as c:\src\nr\data. That way I can easily run up multiple different configurations and even different versions of Node-RED in parallel. Very helpful when working on something like uibuilder where I need to test on different configurations (e.g. with and without projects enabled).

Is there more info available on how to get this to work with NodeMon? I have little node developing experience and have no clue how to set this up.

Here is the package.json that I use - this one from the master folder that contains the Node-RED installation, the userDir folder sits in the "data" subfolder and has a similar package.json file.

  "name": "node-red-master",
  "version": "0.20.5",
  "description": "Test environment for developing Node-RED flows",
  "main": "node_modules/node-red/red.js",
  "scripts": {
    "start": "nodemon node_modules/node-red/red.js --userDir ./data",
    "inspect": "node --inspect node_modules/node-red/red.js --userDir ./data",
    "update": "npm install --unsafe-perm --production node-red",
    "check": "npm outdated",
    "check-data": "cd data && npm outdated",
    "update-data": "cd data && npm update",
    "check-master": "npm outdated",
    "update-master": "npm update",
    "admin": "node node_modules/node-red-admin/node-red-admin.js",
    "adminui": "start http://localhost:1880/red/",
    "ui": "start http://localhost:1880/ui/",
    "log": "sudo journalctl -u nrlive -f -n 0 -o cat"
  "nodemonConfig": {
    "ignore": [
    "watch": [
    "env": {
      "NODE_ENV": "development"
    "ext": "js,html"
  "keywords": [
  "author": "Julian Knight",
  "license": "MIT",
  "dependencies": {
    "node-red": "^0.20.5",
    "node-red-admin": "^0.1.5"
  "browserslist": [
    "> 0.5%",
    "maintained node versions",
    "last 2 versions",
    "not dead",
    "not ie < 11"

Typically, you install nodemon globally npm install nodemon -g.

You can use a separate configuration file for it if you like but I prefer to have the settings together in package.json.

You can see the npm start script, that is what starts node-red via nodemon.

This is how I debug a custom node in VS Code...

It works for me however since this is a dist version of node-red its difficult sometimes to debug client side issues. Other than that, debug stop points work in my node js files. For debuging my .html files, i enter debugger into the function & open F12 (chrome debugger stops on the debugger statement)


  1. Install node-red as per instructions on
  2. Run it one time so that .node-red folder is generated
  3. Install own node...
    1. cd c:\users\me\.node-red (or linux equivelant)
    2. npm install c:\path_to_my_node
  4. Open VS code & "open folder" created on step 2 e.g. c:\users\me\.node-red (or linux equivelant)
  5. Add following configuration to vscode launch.json (press CTRL+SHIFT+P then type launch.json)...
  "version": "0.2.0",
  "configurations": [
      "type": "node",
      "request": "launch",
      "name": "Launch Node-red",
      "program": "c:\\path_to_npm_global\\node-red\\red.js",
      "runtimeArgs": ["--preserve-symlinks", "--experimental-modules"],
      "env": {
        "NO_UPDATE_NOTIFIER": "1"
      "type": "node",
      "request": "launch",
      "name": "Debug Current File",
      "program": "${file}"
    { "type": "node", "request": "attach", "name": "Attach to Process", "processId": "${command:PickProcess}" } 
  1. Select "Launch Node-red" from the debug drop down & press F5

Hope this helps

Some notes on my vs code setup

  • "NO_UPDATE_NOTIFIER": "1" Without this, node-red takes over 3 minute startup (corporate proxy issue)
  • --preserve-symlinks because npm install c:\folder\my_node creates a symlink & debug points wont stop on your .js code without it

Thanks for the help both of you! I'll dive into this :blush:

I guess I'm stumbling over my limited knowledge, but I'm not giving up. I've setup a custom node using the sample lowercase conversion code. It works fine. So I want to use it as a setup case to make sure I know how VS code is to work. I've set the breakpoint but it seems to be ignored. Makes me think I need to make sure VS code is looking at the right piece of js in the right place. From the last post maybe symlink is my problem. The node-red is in the same machine as the VS code but there is only an inject node+custom+debug so that should be ok as server side. What am I missing?

Hard to say as you haven't really said what you have tried, where things are installed plus a whole bunch of other salient details.

Did you follow the step by step info I posted above?

I'll go thru everything again tomorrow (I'm in Rome and at home with the lockdown so have plenty of time). Then I'll update with precise details on what I'm doing (right or wrong). Thanks in advance.

Here's the update:

  1. Mac OS installation per
  2. .node-red folder exists as ~/.node-red
  3. my development folder is ~/My Documents/Dev/node/node-red-contrib-hex2buffer. With NPM install I find in the /usr/local/lib/node_modules
    lrwxr-xr-x 1 thepadol wheel 55 Mar 19 13:39 node-red-contrib-hex2buffer -> ../../My Documents/Dev/Node/node-red-contrib-hex2buffer
  4. in launch.json I coded:
    "type": "node",
    "request": "launch",
    "name": "Launch Node-red",
    "program": "/usr/local/lib/node_modules/node-red/red.js",
    "runtimeArgs": ["--preserve-symlinks", "--experimental-modules"],
    "env": {"NO_UPDATE_NOTIFIER": "1"}

As far as I can tell vs code launches node-red correctly. If I select attach I can see the process running and recognized by vs code (just for purposes of looking at what vs code thinks is a node process).

What is hex2buffer.js? Currently a test custom node for purposes of verifying vs code. The source is
module.exports = function(RED) {
function hex2buffernode(config){
var node = this;
node.on('input', function(msg) {
msg.payload = msg.payload.toLowerCase();
the flow is

and the results:
Screen Shot 2020-03-19 at 4.30.30 PM

When using launch "node-red" from vs code I get the flow editor and can inject as expected. However no matter what breakpoint I place in hex2buffer.js seems to be ignored. I suspect that i must be placing the breakpoint in the wrong file or version of hex2buffer.js. Since the node-red launch shows the right flow I assume that I installed the custom node properly.

What other salient info can I provide? thanks.

1 Like

Guess I'm replying to myself, but it's progress. I decided to start from scratch on a different computer in the hope of cleaner environment (by experience it's a possible factor). Initially the behavior looked the same. Between considering a bug in the software vs being a user (me) problem, 99% it's the latter. VS code was stopping at node-red startup so that was a good sign. So I said to myself what am I assuming that I shouldn't? How about the breakpoint itself? I mean VS code allows you to set breakpoints but it assumes you know when that breakpoint is to occur and that depends on what the code is doing. A good haha moment. I selected a different point and it now stops as I would have expected. Tried on the original PC and it does the same. The original breakpoint only works at the point in time when the custom node is defined, not when executing. I think this sorts out my problem. Thanks for showing the way on VS code.


Were you able to debug your custom node successfully.
I am trying but any break point is showing as "unbound"


HI Steve,
I tried the steps you mentioned above. When I start the debugger, it automatically starts nod-red. I have no place to select "Launch Node Red" and any break point I add in my custom node code, is showing as "unbound" and VC code is ignoring them. Can you please help?

Hi @mathurv, did you follow this step by step? Obviously, you will need to set your file paths.

It still works (I refer to it every time I set up another machine for debugging)