Webstorm logo

The WebStorm Blog

The Smartest JavaScript IDE

Tips & Tricks

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

Comments below can no longer be edited.

35 Responses to Debugging Node.js Apps in WebStorm

  1. Anthoni Gardner says:

    September 22, 2017

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

    • Ekaterina Prigara says:

      September 25, 2017

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

  2. Kunal Khandelwal says:

    September 23, 2017

    Works right away! Thank you soooooo much

  3. nxsearch says:

    September 28, 2017

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

  4. Stephen Harper says:

    October 25, 2017

    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?

    Many Thanks

    • Stephen Harper says:

      October 25, 2017

      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:

        October 26, 2017

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

        • Stephen Harper says:

          October 26, 2017

          Hi Lena,

          Thanks for looking. Apologies, but I specified the wrong mean seed project 🙁 I actually meant: https://github.com/DavideViolante/Angular-Full-Stack

          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:

            October 26, 2017

            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:

    October 26, 2017

    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:

      October 27, 2017

      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:

        October 31, 2017

        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:

    October 29, 2017

    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:

      October 30, 2017

      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:

    November 12, 2017

    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:

      November 14, 2017


      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!

  8. Alon Mizrahi says:

    January 31, 2018

    is there any work on the async await debugging issues?

    • Ekaterina Prigara says:

      February 1, 2018

      What problems are you referring to? There’s support for debugging async code.

  9. Blake McCool says:

    March 28, 2018


    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.

    • Blake McCool says:

      March 28, 2018

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

      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.

      • Ekaterina Prigara says:

        March 29, 2018

        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.

  10. Kapil Lamba says:

    April 2, 2018

    Since i did not use express-generator, i do not have bin/www file.

    How do i debug an app which is not created using express-generator (default for webstorm)?
    Simply copying bin/www from another project and using it in my project gives me errors.

    • Ekaterina Prigara says:

      April 4, 2018

      In the Node.js run/debug configuration you need to specify the path to the file that starts your Node.js applications (e.g. runs the server) in the JavaScript file field.

  11. Nikolay Kupstas says:

    April 11, 2018

    What about if my application have an SSR using node. Node starts webpack that comliped front code. How can I debug in this situation?

    • Ekaterina Prigara says:

      April 11, 2018

      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.

  12. Simone says:

    March 20, 2019

    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”?

    • Ekaterina Prigara says:

      March 20, 2019

      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.

      • Simone says:

        March 20, 2019

        Thank you so much. I find solution in the post you linked, but if i have a dubt about it, where i can post a question?

  13. Dean says:

    August 18, 2019

    Hello, is there anyway I can configure Webstorm to run in debug mode and stop inside a lambda function?

    exports.handler = async function(event, context) {
    *stop here – debugger red circle left breakpoint*


    • Ekaterina Prigara says:

      August 19, 2019

      Hello, yes, sure, you should be able to debug the async functions in WebStorm. If it doesn’t work for your code, please provide a bit more information in an issue on our issue tracker: what IDE and Node.js versions you use; how the app is compiled and built; what is the exact code. Thanks!

  14. Nick says:

    June 9, 2020


    Attempting to debug a node.js + GraphQl(Apollo) application that I start using yarn run dev. The main javascript file is src/index.js, and starting the debugger, it bombs out on the very first line

    `import app from ‘./app’;`

    `SyntaxError: Cannot use import statement outside a module`

    My package.js dev script looks like:
    `dotenv-updater && nodemon src/index.js –exec “node -r dotenv/config -r babel-register”`

    My node.js debug configuration for index.js:
    Node Interpreter: ~/.nvm/versions/node/v12.14.1/bin/node
    Working Directory: ~/www/projectFolder
    Javascript File: src/index.js
    Application Params: –exec \”node -r dotenv/config -r babel-register\”

    What am I doing wrong here?


    • Nick says:

      June 9, 2020

      my package.json, not package.js.

    • lena_spb says:

      June 9, 2020


      your run configuration is wrong. As you have –exec \”node -r dotenv/config -r babel-register\” specified in Application Params: field, the resultant command is node src/index.js –exec \”node -r dotenv/config -r babel-register\”, i.e. your main javascript file is passed to Node.js without pre-processing. And, as Node.js doesn’t natively support ECMAScript 2015 modules in .js files, you get a syntax error.
      Try changing your configuration as follows:

      Node Interpreter: ~/.nvm/versions/node/v12.14.1/bin/node
      Node Parameters: -r dotenv/config -r babel-register
      Working Directory: ~/www/projectFolder
      Javascript File: src/index.js

      • Nick says:

        June 9, 2020

        That did it! Thanks a million!