Master Node.js Debugging with VS Code: A Complete Guide

Developers who cannot debug Node.js are not qualified developers.

Today we will explore Node.js debugging methods, focusing on using Visual Studio Code (VS Code) to debug Node.js applications.

Node.js Debugging Principles

Node.js runs on the V8 engine, which provides built‑in debugging support. The V8 debugging protocol lets developers set breakpoints, inspect variables, and evaluate code while the application runs.

The V8 debugging protocol is based on the Chrome DevTools Protocol (CDP); many debugging tools and IDEs, including VS Code, rely on this protocol to communicate with Node.js.

Chrome DevTools Protocol (CDP)

CDP is a set of APIs developed by the Chrome team for controlling and inspecting the browser, covering DOM, CSS, network, performance, and JavaScript debugging.

CDP consists of several domains, each handling a specific area:

Page : Manage page lifecycle and content.

DOM : Operate the Document Object Model.

CSS : Control style sheets.

Network : Monitor and control network requests.

Debugger : Manage JavaScript breakpoints and execution state.

Runtime : Manage the JavaScript execution environment.

Console : Control console output.

Each domain contains commands and events. Commands trigger actions; events are notifications sent by the browser or Node.js.

CDP communicates over WebSocket. The client sends requests, the server replies, and the server can also push event messages.

To debug a Node.js application with CDP:

Start the Node.js app with debugging enabled: <code>node --inspect app.js</code>

Node.js will output a WebSocket URL, e.g.: <code>Debugger listening on ws://127.0.0.1:9229/12345678-1234-5678-1234-567812345678 For help, see: https://nodejs.org/en/docs/inspector</code>

Connect to the debugging server using Chrome or any CDP‑compatible tool: <code>const WebSocket = require('ws'); const ws = new WebSocket('ws://127.0.0.1:9229/12345678-1234-5678-1234-567812345678'); ws.on('open', () => { console.log('Connected to Node.js debugger'); ws.send(JSON.stringify({ id: 1, method: 'Runtime.enable' })); }); ws.on('message', (data) => { console.log('Received message:', data); }); </code>

In the example above we use the ws module to connect to the Node.js debugging server and send a command that enables the Runtime domain.

Common CDP commands and events:

Debugger.enable

Enables the debugger and starts receiving debugger‑related events.

<code>{
  "id": 1,
  "method": "Debugger.enable"
}
</code>

Debugger.setBreakpointByUrl

Sets a breakpoint at a specific URL and line number.

<code>{
  "id": 2,
  "method": "Debugger.setBreakpointByUrl",
  "params": {
    "url": "file:///path/to/file.js",
    "lineNumber": 10
  }
}
</code>

Debugger.paused

Event emitted when script execution is paused (e.g., at a breakpoint).

<code>{
  "method": "Debugger.paused",
  "params": {
    "callFrames": [...],
    "reason": "breakpoint",
    "data": {...}
  }
}
</code>

Runtime.evaluate

Evaluates a JavaScript expression in the global context and returns the result.

<code>{
  "id": 3,
  "method": "Runtime.evaluate",
  "params": {
    "expression": "2 + 2"
  }
}
</code>

Puppeteer, a popular headless‑browser library, also uses CDP internally:

<code>const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch({ headless: false });
  const page = await browser.newPage();
  await page.goto('https://example.com');
  // other operations...
  await browser.close();
})();
</code>

Built‑in Debugger

Node.js can be started with built‑in debugging commands:

<code>node inspect app.js</code>

Or add the --inspect flag when running code:

<code>node --inspect app.js</code>

Or use --inspect‑brk to break on the first line:

<code>node --inspect-brk app.js</code>

After the debugging server starts, open Chrome and navigate to chrome://inspect to see the interface.

Clicking “inspect” opens the DevTools window automatically.

If the debugging server runs on a non‑default port or a remote device, you need to add the target manually:

Click the “Configure…” button.

In the dialog, add the debugging server address, e.g. localhost:9229 or 192.168.1.100:9229 .

Click “Done”.

The chrome://inspect page provides three main functions:

Discover and manage local and remote targets : automatically finds Node.js debugging targets and Chrome instances on devices.

Connect to Node.js debugging server : quickly attach Chrome DevTools to a Node.js process.

Configure custom targets : manually add remote debugging targets, such as a Node.js server or a Chrome instance on another device.

It can also be used to debug Chrome on Android devices:

Enable developer options and USB debugging on the Android device.

Connect the device via USB.

Enter chrome://inspect in Chrome’s address bar and press Enter.

In the “Devices” section, you will see the connected Android device and its open Chrome pages.

Click the “inspect” button next to a page to open DevTools for that device.

Debugging Node.js with VS Code

Chrome debugging can be cumbersome; most backend developers prefer in‑editor breakpoint debugging, which VS Code fully supports.

VS Code’s debugger uses the V8 debugging protocol to communicate with Node.js, enabling breakpoints, step‑through execution, and variable inspection.

Configure VS Code for Node.js Debugging

To debug a Node.js app in VS Code, follow these steps:

Step 1: Install Node.js Extension (optional)

Open VS Code, go to the Extensions view, and search for “Node.js Extension Pack”. VS Code already supports Node.js debugging out of the box, but the pack adds useful utilities.

Step 2: Create a Debug Configuration File

Create a .vscode folder at the project root and add a launch.json file.

Open VS Code.

Press Ctrl+Shift+D to open the Debug view.

Click the gear icon at the top of the Debug view and select “Node.js” to generate a default launch.json .

A typical default launch.json looks like this:

<code>{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Launch Program",
      "skipFiles": ["<node_internals>/**"],
      "program": "${workspaceFolder}/app.js"
    }
  ]
}
</code>

Step 3: Configure Debug Options

Adjust the fields in launch.json according to your project:

type : debugging type, usually node .

request : launch to start a new process or attach to connect to an existing one.

name : a friendly name for the configuration.

skipFiles : files to ignore, such as Node.js internal modules.

program : the entry file of the application.

Common configuration examples:

Launch Node.js Program

<code>{
  "type": "node",
  "request": "launch",
  "name": "Launch Program",
  "program": "${workspaceFolder}/app.js",
  "skipFiles": ["<node_internals>/**"]
}
</code>

Attach to a Running Node.js Process

<code>{
  "type": "node",
  "request": "attach",
  "name": "Attach to Process",
  "processId": "${command:PickProcess}",
  "skipFiles": ["<node_internals>/**"]
}
</code>

Use Nodemon for Automatic Restart

<code>{
  "type": "node",
  "request": "launch",
  "name": "Nodemon",
  "runtimeExecutable": "nodemon",
  "program": "${workspaceFolder}/app.js",
  "restart": true,
  "console": "integratedTerminal",
  "internalConsoleOptions": "neverOpen"
}
</code>

After configuration, you can start debugging Node.js apps. Common debugging actions include:

Set Breakpoints

Click the gutter next to a line number to toggle a breakpoint; the marker turns red when active.

Start Debugging

Press F5 or click the green play button in the Debug view. VS Code launches the Node.js process and pauses execution at breakpoints.

Inspect Variables

When paused, view variable values in the “Variables” pane or hover over them in the editor.

Step Execution

Use the toolbar buttons to step over ( F10 ), step into ( F11 ), or step out ( Shift+F11 ) of code.

Debug Console

Use the Debug Console to evaluate JavaScript expressions and modify variables at runtime.

VS Code Node.js Debugging Best Practices

Use Environment Variables

Configure environment variables in launch.json with the env field:

<code>{
  "type": "node",
  "request": "launch",
  "name": "Launch Program",
  "program": "${workspaceFolder}/app.js",
  "env": {
    "NODE_ENV": "development",
    "API_KEY": "your‑api‑key"
  }
}
</code>

Automate Debugging Workflow with Tasks

Combine VS Code tasks to start dependent services before launching the app:

<code>{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Start MongoDB",
      "type": "shell",
      "command": "mongod",
      "isBackground": true
    },
    {
      "label": "Launch Program",
      "type": "shell",
      "command": "node app.js",
      "isBackground": true,
      "dependsOn": "Start MongoDB"
    }
  ]
}
</code>

Conclusion

Debugging is a crucial part of Node.js development. By understanding the underlying principles, mastering VS Code debugging techniques, and following best practices, you can dramatically improve debugging efficiency and quickly locate and resolve issues.

We hope this guide helps you better understand and apply Node.js debugging methods. Feel free to leave comments with questions or suggestions for further discussion.