`Connection refused` in WebStorm NPM debug configuration

Question

Bearing in mind that I have only the loosest understanding of what a debugger is really doing, I need help setting up the WebStorm npm debug configuration for an express.js application.

Here's me so far-- I click debug with my settings as I think they should be (below):

/Users/me/.nvm/versions/node/v4.4.1/bin/node --debug=8090     
/Users/me/.nvm/versions/node/v4.4.1/lib/node_modules/npm/bin/npm-cli.js run-script start

To debug "start" script, make sure $NODE_DEBUG_OPTION string is specified as the first argument for node command you'd like to debug.
For example:
 { "start": "node $NODE_DEBUG_OPTION server.js" }
Debugger listening on port 8090
...
It has begun. Port: 3000

So at this point, the application has started up and responds to my POST to localhost:3000, but does not break on the breakpoint I set.

Looking in the Debugger>Variables pane, I see Connecting to localhost:57617, then a tooltip pops up saying "Connection refused" and the pane says Frame is not available.

I don't understand where that port number 57617 is coming from. It varies, though not according to any pattern I've yet discovered, except inasmuch as it is always different than the one I set in the --debug=X or --debug-brk=X node option.

Answer 1

The error message is indeed very unclear. You need to adjust your npm script entry in the package.json (sadly). Found a clear description in this blog post: http://pavelpolyakov.com/2016/05/01/webstorm-npm-tasks-debug/

Your start entry should look like the following:

"scripts": {
    "start": "node $NODE_DEBUG_OPTION ./node_modules/someModule/bin/someModule.js --arguments"
}

You could also go with two entries to keep the first one DRY. Though it is not really necessary since both run just fine from command line. So just for completeness' sake:

"scripts": {
    "start": "someModule --arguments",
    "startDebug": "node $NODE_DEBUG_OPTION ./node_modules/someModule/bin/someModule.js --arguments"
}

I don't find this method particularly clean, imo that is what the npm debugger should do for you without having to manipulate source code. But it appears to be the only way (for now).