Debugging Node.js Applications in WebStorm Using Chrome DevTools

Useful answer

To debug a Node.js app in WebStorm, create a Node.js run/debug configuration that launches the script with the --inspect-brk flag and selects Chrome as the debug adapter. This opens Chrome DevTools inside WebStorm, letting you set breakpoints, inspect variables, and step through code.

How it works

WebStorm acts as a front‑end for the Chrome DevTools Protocol. When you start the configuration, WebStorm:

1. Launches the Node.js process with --inspect-brk (or --inspect if you prefer).
2. Starts Chrome (or reuses an existing instance) with remote debugging enabled on the same port.
3. Connects to the DevTools endpoint, maps source files (including TypeScript source maps), and displays the DevTools UI inside the IDE.
4. Allows you to set breakpoints, view the call stack, inspect variables, and use Live Edit for HTML/CSS/JS files served by the built‑in web server.

Configuration example

Below is a minimal example you can reproduce in any WebStorm project.

1. Sample code

// server.js
const http = require('http');

function handler(req, res) {
  res.writeHead(200, {'Content-Type': 'text/plain'});
  res.end('Hello from Node.js\n');
}

const server = http.createServer(handler);
server.listen(3000, () => {
  console.log('Listening on http://localhost:3000');
});

2. Create the debug configuration

• Open Run → Edit Configurations…
• Click the + button, choose Node.js.
• Fill in the fields:
  • Name: Node.js Debug with Chrome
  • JavaScript file: $ProjectFileDir$/server.js
  • Node parameters: --inspect-brk $FilePath$
  • Check Chrome debug adapter (this tells WebStorm to use Chrome DevTools).
• Apply and close.

3. Start debugging

Select the new configuration from the toolbar and click the Debug icon. WebStorm will launch Node.js, start Chrome, and open a DevTools tab inside the IDE. The execution will pause at the first line because of --inspect-brk.

4. Set a breakpoint and verify

Click in the gutter of server.js next to the res.end line to set a breakpoint. Then reload http://localhost:3000 in a browser or use curl. The DevTools pane should pause at your breakpoint, showing the call stack, scopes, and watch expressions.

Limits and common mistakes

Chrome availability

WebStorm relies on a locally installed Chrome executable. If Chrome is not found or is not reachable, the debug configuration will fail to start. Ensure Chrome is in your PATH or specify its location in Settings → Tools → Web Browsers and Preview.

Port conflicts

The --inspect-brk flag opens port 9229 (or a dynamically chosen port). If another process already uses that port, Node.js will fail to launch. Change the port with --inspect-brk=9230 or free the conflicting port.

Source maps for TypeScript

When debugging TypeScript, WebStorm automatically uses generated source maps. If you compile with tsc without the --sourceMap flag, breakpoints will not map correctly. Verify that tsconfig.json contains "sourceMap": true.

Async call stacks

Heavy use of promises or async/await can produce confusing stack frames because the DevTools protocol shows the underlying JavaScript engine frames. Enable "Async call stacks" in the DevTools settings (gear icon → Settings) for clearer traces.

Live Edit constraints

Live Edit updates the browser in real time only for files served by WebStorm’s built‑in server (activated via Run → Edit Configurations → Built‑in server port). Editing files that are served by an external process (e.g., a custom Express static middleware) will not trigger Live Edit.

Remote debugging

If you need to debug a Node.js process running on another machine, you must expose the inspector port (e.g., --inspect=0.0.0.0:9229) and adjust firewalls. WebStorm can then attach via Run → Attach to Node.js/Chrome using the remote host and port.

Practical verification

After starting the debug configuration:

1. Confirm that a Chrome tab appears inside WebStorm with the DevTools panel visible.
2. Check that the breakpoint you set is highlighted and the debugger is paused.
3. Inspect the Scope pane to see local variables (e.g., req, res).
4. Press the Resume button (F8) and verify that the server responds to the request.

If any of these steps fail, revisit the Chrome availability, port, and source‑map settings described above.