How to Set Up VS Code Debugging for Node.js: Configuration and Best Practices

Apr 14, 2026

Developer workspace with code editor

When I tried to debug Node.js in VS Code, my breakpoints didn’t work. The debugger ignored them, or showed “breakpoint unverified” warnings. Setting up the right configuration fixed this.

Environment

VS Code 1.80+
Node.js v18+
Project with JavaScript files

What happened?

I had a Node.js Express server that crashed on certain requests. I opened VS Code, clicked Debug panel, and tried to set breakpoints. But clicking line numbers showed gray circles instead of red ones.

The issue was missing launch.json configuration. VS Code needs explicit settings to know what to run and how.

How to solve it?

Step 1: Generate launch.json

I opened VS Code Debug panel (Ctrl+Shift+D), clicked “create launch.json”, and selected Node.js.

VS Code created .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Launch Program",
      "program": "${workspaceFolder}/app.js",
      "console": "integratedTerminal"
    }
  ]
}

The key fields:

type: "node" - Node.js debugger
request: "launch" - Start new process
program - Entry point file
console: "integratedTerminal" - Use VS Code terminal for output

After creating this file, my breakpoints turned red and worked correctly.

Step 2: Configure for nodemon

For development, I use nodemon to restart on file changes. Debugging with nodemon requires different settings:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Debug with Nodemon",
      "runtimeExecutable": "nodemon",
      "program": "${workspaceFolder}/app.js",
      "restart": true,
      "console": "integratedTerminal",
      "internalConsoleOptions": "neverOpen"
    }
  ]
}

The runtimeExecutable: "nodemon" tells VS Code to use nodemon instead of node. The restart: true reconnects the debugger when nodemon restarts the process.

Step 3: Attach to running process

Sometimes the Node.js process is already running (in production or Docker). I can attach the debugger to it.

First, start the process with inspector:

node --inspect=9229 app.js

Then configure VS Code to attach:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "attach",
      "name": "Attach to Process",
      "port": 9229,
      "restart": true,
      "localRoot": "${workspaceFolder}",
      "remoteRoot": "/app"
    }
  ]
}

For Docker containers, remoteRoot maps the container path to local files.

Step 4: Debug TypeScript projects

My TypeScript projects needed extra configuration. Breakpoints in .ts files didn’t map to compiled .js files correctly.

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Debug TypeScript",
      "program": "${workspaceFolder}/src/index.ts",
      "preLaunchTask": "tsc: build",
      "outFiles": ["${workspaceFolder}/dist/**/*.js"],
      "sourceMaps": true
    }
  ]
}

The outFiles tells VS Code where compiled JavaScript lives. sourceMaps: true enables source map support.

The reason

I think the key points about VS Code debugging:

launch.json is required - Without it, VS Code doesn’t know how to start or attach to your Node.js process.
Program path matters - Wrong program path causes breakpoints to fail. Use ${workspaceFolder} for correct paths.
outFiles for TypeScript - TypeScript projects need outFiles setting for proper source map resolution.
Auto Attach feature - VS Code has “Auto Attach” setting that automatically debugs when running node in terminal. Enable it in Settings > “Debug > Node: Auto Attach”.

Common mistakes I made

Wrong program path - Used relative path instead of ${workspaceFolder}
Missing outFiles - TypeScript breakpoints showed “unverified” without this setting
Not using restart with nodemon - Debugger disconnected when nodemon restarted
Ignoring source maps - Compiled JavaScript breakpoints didn’t match TypeScript source

Summary

In this post, I showed how to configure VS Code debugger for Node.js. The key point is creating proper launch.json with correct program, outFiles, and runtimeExecutable settings. This enables visual debugging with breakpoints, variable inspection, and call stack navigation.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

👨‍💻 VS Code Node.js Debugging Guide
👨‍💻 VS Code Launch.json Reference

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!