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
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.
We’ll use a simple Express app as an example.
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.
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
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
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.
We’ll use the TypeScript Express sample project as an example here.
npm run build for that.
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
--debugflag, 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
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.