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.
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.
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.
We’ll use the TypeScript Express sample project as an example here.
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
--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 --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.
Subscribe to WebStorm Blog updates
