Debugging Nodejs app with VSCode

VSCode provides a robust set of tools to effectively troubleshoot and debug Node.js applications. From built-in debugging support to performance profiling and extensions, VSCode makes it easier to identify and fix issues within your code. This article will walk you through the key features and techniques available for troubleshooting Node.js applications in VSCode, helping you optimize your workflow and resolve problems efficiently.

Inspector

Inspector is a Node.js process that listens for a debugging client to connect to it.

There are 2 ways to enable Node inspector.

Method 1

Starting the Node.js app with the — inspect switch

node --inspect your-script.js

Method 2

Sending SIGUSR1 signal to the node process

# find the process ID (PID) of the node process
$ ps aux
$ kill -SIGUSR1 [PID]

Use VSCode Debugger

VSCode Debugger is an integrated feature of the Visual Studio Code editor that allows developers to debug their applications directly within the editor. It supports a wide range of programming languages and platforms such as JavaScript, TypeScript, Python, Java, C++, Go, .NET, and more. The debugger provides tools like breakpoints, stepping through code, variable inspection, and call stack navigation, making it an essential part of the development process.

In this document, I will only describe how to attach the VSCode debugger to a running Node.js inspector process.

Step 1: Create a launch.json file with the following content in a .vscode folder in your project directory.

{
  "name": "Attach",
  "port": 9229,
  "request": "attach",
  "skipFiles": ["<node_internals>/**"],
  "type": "node"
}

Step 2: On the left-hand side of VSCode, click the debug icon to open the debug panel.

Step 3: Start debugging with the "Attach" debug configuration.

Next, I will explain how to attach the VSCode debugger to:

• An application running locally on a machine
• An application running inside a Docker container
• An application running within a container in a remote Kubernetes cluster

each scenario, respectively.

Attach VSCode debugger to an app running locally on a machine

Step 1 — Start your Node.js app with the — inspect switch

node --inspect your-node-app-entry.js

Step 2 — Start debugging with the “Attach” debug configuration in VS Code debug panel.

Attach VSCode debugger to an app running inside a Docker container

Step 1 — Make sure your Node.js app is started in the docker container with the — inspect=0.0.0.0:9229 switch

node --inspect=0.0.0.0:9229 your-node-app-entry.js

By default, Node.js binds the debugger to localhost (127.0.0.1). However, localhost inside a container only refers to the container’s own loopback network interface, making it inaccessible from outside the container. By using 0.0.0.0, we allow the debugger to listen on all available interfaces, including the container's network interface that is exposed to the host machine and beyond. This enables external clients (such as VSCode) to connect to the debugger from outside the container.

Get Spencer Feng’s stories in your inbox

Join Medium for free to get updates from this writer.

Remember me for faster sign in

Step 2 — map container port 9229 to 9229 on our local machine

-p 9229:9229

Step 3 — Start debugging with the “Attach” debug configuration in VS Code debug panel.

Attach VSCode debugger to an app running within a container in a remote Kubernetes cluster

Step 1 — Get the running Node process

# List all the processes
ps aux

It will list all the running processes.

Step 2 — Start the inspector for the running node process

# The PID for the node process is 30
kill -SIGUSR1 30

Step 3 — Forward local machine port 9229 to K8s service port 9229

kubectl port-forward your-pod 9229:9229 -n your-namespace

Step 4 — Start debugging with the “Attach” debug configuration in VS Code debug panel.

Take performance profile with VSCode

Once the VSCode debugger is connected to a Node inspector, we can capture a performance profile of the running Node process.

VSCode debugger natively supports performance profiling, but with the Flame Chart Visualizer for JavaScript Profiles plugin, we can gain additional insights.

How to take performance profiles

Display a flame chart for the profile file

After capturing a performance profile, a profile file will be generated and saved in your root folder. You can open and visualise it as a flame chart in VSCode.

Realtime performance

We can see the realtime CPU and heap usage.