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. And you can start debugging your app very quickly. Here’s how.

We’ll use a simple Express app as an example.

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).


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.

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 --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.

About Ekaterina Prigara

Ekaterina Prigara is WebStorm product marketing manager at JetBrains. She's passionate about new technologies, UX and coffee.
This entry was posted in Tutorials and tagged , . Bookmark the permalink.

18 Responses to Debugging Node.js apps in WebStorm

  1. What is the best method to debug Typescript, Webpack and Create-React-App ?

  2. Kunal Khandelwal says:

    Works right away! Thank you soooooo much

  3. nxsearch says:

    Thank you for this. It makes debugging much easier to me.

  4. Stephen Harper says:

    Hi, I’m trying to use and debug this seed project ( 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?

    Many Thanks

    • Stephen Harper says:

      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?

      Thanks again.

      • lena_spb says:

        Hi Stephen,

        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 application doesn’t have predefined dev npm script, and the dev server is listening on localhost:3000, not on localhost:4200

        • Stephen Harper says:

          Hi Lena,

          Thanks for looking. Apologies, but I specified the wrong mean seed project :( I actually meant:

          Sorry, I’ve bookmarked a few and picked the wrong one.

          So I just verified i can debug UI code on port 4200, but I can’t figure out how to debug server code. Is there no way to have a config that will allow you to debug both?

          Thanks again,

          • lena_spb says:

            what would you like to debug namely? dev script runs “mongod”, “ng serve”, “tsc” and “dist/server/app.js”. Would you like to debug app.js? or?

  5. Stephen Harper says:

    I would like to debug app.js, well, app.ts, but I understand the debug config should point at dist/server/app.js

    • lena_spb says:

      What’s a problem? Just create a Node.js run configuration, specify the app.js as JavaScript file, add breakpoints to server/app.ts and hit Debug

      Note that you would need to start mongod, etc. first

      • Stephen Harper says:

        Many thanks Lena. I’ve got it working now. I can also debug the client code at the same time by installing jetbrains plugin for chrome and and attaching remote debugger, so I’m very happy now.

        Thanks again for all your help!

  6. Josh says:

    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.

    • Ekaterina Prigara says:

      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!

  7. Adam Parrish says:

    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.

    • Ekaterina Prigara says:


      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:
      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!

  8. Alon Mizrahi says:

    is there any work on the async await debugging issues?

Leave a Reply

Your email address will not be published. Required fields are marked *