Debugging Node.js apps in WebStorm

WebStorm makes it easier to debug Node.js apps. You can put breakpoints right in your source code (no more debugger and console.log() statements!), which can be written in JavaScript or TypeScript.

You can do many things that will help you explore the code and understand where the bug is. In the debugging tool window, you can see the call stack and the variables in their current state, evaluate expressions in the editor, and step through the code – read more about that in the How to debug with WebStorm blog post. And you can start debugging your app very quickly. Here’s how.

Running and debugging the app

We need to do two things: first, create a new Node.js run/debug configuration that will start the app, and then put a breakpoint.

To create a configuration, go to the Run menu and select Edit configurations… Click the + icon and select Node.js configuration type.

Now specify the path to the main file of the application that starts it. For the Express app it’s bin/www

Save the configuration. Put the breakpoints in your code. Now press Ctrl-D on macOS or Shift+F9 on Windows & Linux to debug the app (or click the green bug-like icon).

If you just want to run the app, click the green run icon next instead or press Ctrl-D / Shift + F10.

Now if you do the actions that trigger the code where the breakpoint is, the app will pause on the breakpoint. Explore the call stack and the variables in the debugging tool window, hover over the expressions in the editor to see their current state, step through the code, or put new breakpoints to help you debug further.

Tip: another way to quickly run or debug a Node.js file is using the Run <file name> or Debug <file name> actions in the context menu of the JavaScript file.

Debugging protocols

As you may know, in version 7+ Node.js changed its debugging protocol to the Chrome Debugging Protocol. The command-line options that you need to use to start debugging have changed to --inspect and --inspect-brk.

With WebStorm, you don’t have to worry about the protocols and options. WebStorm will check the node version you’re using and if it’s 8+, it will use the new options and protocol. For any earlier versions it will use the old options and protocol.

Debugging Node.js apps in TypeScript

With WebStorm you can also debug code written in TypeScript (though you need to compile it to JavaScript first to run it with node).
There’s one extra thing you need for that – Source Maps. WebStorm’s debugger will use them to map the compiled code that is executed to the source code in the editor, and you will be able to put breakpoints in TypeScript code and step through it.

The TypeScript compiler can generate the source maps. To enable source map generation, add "sourceMap": true in the tsconfig.json file. That way the compiler will add a .map.js file next to every generated .js file.

First, we need to compile the app to JavaScript. The right way to it depends of the configuration of the app’s build pipeline. In our example, we need to run npm run build for that.

Now let’s create a new Node.js debug configuration (select Run – Edit configurations – Add). Specify the path to the compiled JavaScript file that starts the app. In our example it’s dist/server.js.

Save the configuration. Put the breakpoints and start the debug configuration (Ctrl-D on macOS or Shift+F9 on Windows & Linux). Once the breakpoint is hit, you can step through the code and do everything you would when debugging a JavaScript app.

Attaching debugger to the running node process

In the cases we described above, the application is actually started from WebStorm, but sometimes you may want to attach to a process that is already running (for example, in a Docker container started on your machine). Good news: you can still debug this app with WebStorm!

To be able to connect to the running process, you need to start it with the debugging flags.
You can use --inspect=port number for Node.js versions 6.5+, and/or --debug=port number for any Node.js versions earlier than 8.

If you use the --debug flag, create a Node.js Remote Debug configuration in WebStorm and specify the host (for a local machine it’s localhost) and the port number you’ve used in it.

If you used the --inspect flag, create and use a new Chromium Remote debug configuration.

Put breakpoints in the code, run the app, and then run the newly created debug configuration.

If you want the execution to stop on the first line of the app and wait till you attach the debugger to it, use the --inspect-brk flag.

Running node apps in Docker from WebStorm

WebStorm can also run the node app in the Docker container, and then connect to it with debugger. For more details on that, see our blog post, Quick tour of WebStorm and Docker.

You can also find information on developing, running and debugging Node.js apps in WebStorm in its online documentation.

29 Responses to Debugging Node.js apps in WebStorm

You’re interested in debugging the client-side code and not Node.js server-side code, right?
Please have a look at this blog post: https://blog.jetbrains.com/webstorm/2017/01/debugging-react-apps/
It talks about debugging Create React App written in JavaScript, but it works the same way for TypeScript (tested the app created using react-script-ts).

Hi, I’m trying to use and debug this seed project (https://github.com/linnovate/mean) which uses typescript for client and server, but I cannot get debugging to work. I don’t see how I can run “npm run dev” and attach a debugger. Can you please explain steps required?

I’ve tried running using “npm run dev”, then debugging in Intellij using JavaScript Debug and pointing to localhost:4200, but no breakpoints are hit. I’ve also verified that tsconfig.json has property “sourceMap”: true. Where am I going wrong?

unfortunately I have been unable to get MEAN2 (master branch) working – it doesn’t compile and run. BTW, what project are you actually using? the https://github.com/linnovate/mean application doesn’t have predefined dev npm script, and the dev server is listening on localhost:3000, not on localhost:4200

Okay, I’m trying to do what was described in the first part and sometimes it works and sometimes it doesn’t. For example, when it doesn’t work, express just closes and I cant’ do anything but the dubugger is still running.

Can you should the code as well the project xml file so I can figure out what is different.

Hello Josh,
Please contact our tech support – we’d be glad to help. Please provide the following info: WebStorm, Node.js and Express versions you’re using and the error messages that you see when the Express exits. IDE logs might also be helpful (menu Help – Show logs). Thank you!

I am in a similar boat as someone above on debugging remotely with source maps. I have a node project I am working on and would love to be able to test out the remote debugging features of Chromium with Node 8+.

I am able to get the debugger to connect but none of the source downloads properly into the debugger, it also seems that Chrome’s inspect tools are able to view all of the sources mapped in inline sourcemaps just fine, but the WebStorm debugger doesn’t download the sourceMaps or the complete application compiled sources.

Any suggestions on how I can help you guys reproduce this? I have a project on Github that’s pretty simple that generates the issue if you want it.

Yes, sorry, at the moment WebStorm can only guess the mappings between the files on the server and in the app when you use remote debug. Please vote for and follow this issue for updates: https://youtrack.jetbrains.com/v2/issue/WEB-23258
We are also planning to make it possible to put the breakpoints in the virtual files (which are loaded from the source maps) and not in the physical files in the project – the same way Chrome does.

By the way, can you please describe your project configuration a bit more: you’ve mentioned that you can inspect the app using Chrome (so I assume that the app is running on your machine), but is it then possible run your app in the debug mode from the IDE instead of using a remote debug configuration? Can you please send a link to your project? Thanks!

I am using ts-node and have a child process that I fork. Webstorm is hitting breakpoints on the parent process but I’m having trouble getting breakpoints to hit on the child process. I have tried setting execArgv: [‘–debug-brk=xxxx’], but after I attach a debugger it will not progress. It looks like the child that is forked is getting a port of +1 the master.
I’m on node 6.11.4 and webstrom 2018.1.

If i run the child file on its own with a debugger set up then everything works fine. I am using -r ts-node/register in the node options. This is only giving me difficulty in child processes.

I have kind of figured out what is going on. I am listening to the online event:
cluster.on(‘online’, worker => {
worker.send(‘start’);
});

and I have a log at the bottom of the worker file. The online event is being fired before the log in the worker is hit so it never receives the ‘message’ event. I can restructure the process so that the worker will send a message to the master letting it know when it is really ready.

Thankfully my requirements have changed so that I don’t have to communicate to the master. I am only seeing this when debugging. Just running the configuration has no issues.

Thanks for posting the update. It’s actually true that the child process gets a debugging port of +1 the main process. There’s, unfortunately, no way for the IDE to know that the child process has started and the new debugger needs to be launched for it.

If the code is executed by node, then you need a Node.js run/debug configuration to debug it. In the JavaScript file field you need to specify the path to the file that starts your app. In your case, that should probably be something like node_modules/.bin/webpack. Alternatively, you can attach node debugger to an already running node process using the Attach to Node.js configuration. But in this case, you need to start the node process with the debug flag --inspect-brk=9229.
To debug the client-side code, executed by the browser you need to run a JavaScript debug configuration. You can start it simultaniously with the Node.js configuration.

Hi, I have an Angular application, i read this :
“Now specify the path to the main file of the application that starts it. For the Express app it’s bin/www”
I haven’t the file “bin/www”, and i want to know what is the main file in my application? I try to set in it the file main.ts, but when i start the application in debug mode i have an error.
What is the file i have to add in the “Javascript File”?

Hello Simone,
What exactly do you want to do? If you want to run your Angular app, usually you have to run the npm start command. If you want to debug your client-side application, you need to use the JavaScript debug configuration as described here.
This blog post describes how to debug a server-side Node.js application.