Integrating Node’s Debugger to VSCode

—

,

When I was creating a simple photo booth web app to explore Next.JS and Typescript, I noticed that developers tend to use console.log() to debug, me included. That’s fine for simple bugs, but when you are deep into a large codebase, it gets more and more time consuming as you try to figure out what variables to monitor and where.

In PHP, there is a debugger tool called XDebug, so I wondered if Node, with its huge user base, had something similar. Turns out it does have one, and the best part is that it’s built right into Node itself — you can even use it from VSCode.

This guide will help you set it up, and get right to activating Node’s god mode.

What You’ll Need

  • Node.js (latest version; this guide uses v23.4.0)
  • VSCode (or VSCodium)

Quick Notes:

This guide assumes that your project uses Typescript. Because of this, the guide will use tsx, a package that makes Node.js run TypeScript much easier. This guide will still work with plain JavaScript, just substitute the tsx command to node.

Steps to Set Up Debugging

1. Modify Your Package Script

  1. First, go to the package.json of your project and modify the command that executes the project locally.
  2. Add a --inspect command argument after node or tsx if your project uses that.

❗NOTE: For this guide, we will be using npm run dev with dev running a tsx command tsx src/app.ts

JSON
  "scripts": {<br>    "build": "npm run clean && tsc  && npm run copy-files",<br>    "dev": "tsx --inspect src/app.ts",<br>  },<br>
JSON

2. Enable Source Maps

  1. Go to your tsconfig.jso and add “sourceMap”: true under “compilerOptions”. This allows the compiler to generate sourcemap files, which allow debuggers to work with the original Typescript code, even when the code being executed has been compiled to Javascript already.
  2. If you’d like, you can read more about sourcemaps here and here.
JSON
"compilerOptions": {
        // your other settings here
    "sourceMap": true,
},
JSON

3. Set Up VSCode Debug Configuration.

  1. Go to VSCode and on the upper left menu.
  2. Click Run.
  3. Select the “Add Configuration” button. It will create a launch.json file for your project. This is where commands to run the debugger will be placed.

4. Add Debugger Settings.

  1. Copy the following in your launch.json below the version property.
JSON
"configurations": [
    {
        "name": "Attach by Process ID",
        "processId": "${command:PickProcess}",
        "request": "attach",
        "port": 9229,
        "skipFiles": [
            "<node_internals>/**"
        ],
        "sourceMaps": true,
        "sourceMapPathOverrides": {
            "webpack:///./~/*": "${workspaceFolder}/node_modules/*",
            "webpack://?:*/*": "${workspaceFolder}/*"
        },
        "type": "node"
    },
]
JSON

5. Attach the Debugger.

  1. Close the launch.json tab.
  2. Click on the Run and Debug menu item which can be found on the left side. It’s the one that looks like a play button with an insect outline icon. You should see “Attach by Process ID” ready to be run.

6. Run Your Project in Debug Mode.

  1. Run npm run dev and once you click the green play button, you should see a list of running processes.
  2. You will see run dev in that list, select it.

7. Set Breakpoints and Debug.

  1. VSCode’s bottom bar will turn orange, which indicates the debugger is running and ready to go.
  2. Set a breakpoint by hovering behind the line number and clicking the dark red hint marker.
  3. If all goes well, you should see the web application freeze when that piece of code you set a breakpoint to is reached. You can now see the values of each variable in that function and step through the code line by line to check its behavior.

Conclusion

The Node.js debugger offers a powerful alternative to console.log(for debugging your JavaScript applications. By integrating it with VSCode, you can efficiently step through code, inspect variables, and identify issues quickly. This significantly improves the development workflow.

At Bonito Tech, we specialize in software development services, including debugging and optimization. Whether you’re building a web app or fine-tuning an existing project, we’re here to help. Contact us today to learn how we can support your goals!

References:

Node.js debugging in VS Code – https://code.visualstudio.com/docs/nodejs/nodejs-debugging Debugging Node.js – https://nodejs.org/en/learn/getting-started/debugging