Master Node.js Debugging: From Built‑in Inspector to VSCode Integration

Why Use Debugging

Code is written, not guessed. Debugging lets you observe program execution line‑by‑line without speculation, and even modify in‑memory values or control flow.

Node.js Built‑in Debugging

Node.js provides a simple built‑in debugger, which IDEs extend. Understanding breakpoints is essential.

Breakpoints

A breakpoint pauses execution at a specific line, allowing inspection of variables. In VSCode or VS Code, a red dot marks the breakpoint.

In non‑IDE environments, you can insert the debugger statement to trigger a breakpoint.

async function initMethod() {
  debugger;
  console.log('bbb');
}

initMethod();

Debug Mode

Node ignores debugger unless launched with --inspect, which opens a debugging port (default 9229) following the V8 protocol.

Debugger listening on ws://127.0.0.1:9229/…
For help, see: https://nodejs.org/en/docs/inspector

Using --inspect‑brk pauses at the first line, waiting for a debugger to attach.

Chrome Inspect UI

Open chrome://inspect/ in Chrome to list debuggable targets and attach to them, then you can step through code without the debugger statement.

VSCode Debugging

VSCode integrates the debugger UI. You still need to open the Node debugging port, but VSCode handles breakpoints directly.

The core of VSCode’s launch configuration is the runtimeExecutable and runtimeArgs fields; you no longer need to specify --inspect manually.

{
  "version": "0.2.0",
  "configurations": [{
    "name": "test",
    "type": "node",
    "request": "launch",
    "cwd": "${workspaceRoot}",
    "runtimeExecutable": "node",
    "runtimeArgs": ["test.js"],
    "console": "integratedTerminal",
    "protocol": "auto",
    "restart": true,
    "port": 7001,
    "autoAttachChildProcesses": true
  }]
}

The request field can be launch (VSCode starts the process) or attach (VSCode connects to an already running process).

AutoAttach Feature

When a Node process is started with --inspect, VSCode can automatically detect and attach to it, eliminating the need for complex launch.json settings.

Summary

All debugging methods share two steps: enable Node’s debugging port and attach a debugger that follows the V8 protocol. VSCode extends this with hooks, custom commands, and automatic child‑process debugging, making Node.js debugging more powerful and convenient.