Debugging with VSCode

These notes are compatible with VSCode/Cursor having the following specs. Steps for other versions may vary.

Version: 0.42.3
VSCode Version: 1.93.1
Commit: 949de58bd3d85d530972cac2dffc4feb9eee1e40
Date: 2024-10-16T17:56:07.754Z
Electron: 30.4.0
Chromium: 124.0.6367.243
Node.js: 20.15.1
V8: 12.4.254.20-electron.0
OS: Windows_NT x64 10.0.19045

Web Applications (JavaScript)

Debugging Server-Like Node Apps Running Inside a Container

For example, if we have an Express server app with nodemon following the project structure:

├─ server
│   ├─ src
│   ├──── index.js
│   ├──── ...
│   ├─ package.json
│   ├─ package-lock.json

Update the NPM script in package.json:
"dev": "nodemon --inspect=0.0.0.0:9229 src/index.js"

Copy the following VSCode launch configurations to the /.vscode/launch.json file's configurations[] array:

{
  "type": "node",
  "request": "attach",
  "name": "Docker: Attach to Node",
  "port": 9229,
  "address": "localhost",
  "localRoot": "${workspaceFolder}//server",
  "remoteRoot": "/opt/server",
  "protocol": "inspector",
  "restart": true,
  "sourceMaps": true,
  "skipFiles": ["<node_internals>/**"]
}

Ensure the directory paths defined in localRoot (host) and remoteRoot (container) match the host project directory and container directory paths in the Docker or docker-compose file.

Ensure port 9229 is mapped and exposed from the Docker file.
- For example, -p 9229:9229
Run the app from a container.
Select a debugger to run in VSCode. Press Ctrl + Shift + D
- Select the "Docker: Attach to Node" option.

Debugging Webpack Apps in VSCode

Add breakpoints in the JavaScript (*.js) files inside webpack's app directory entry point for example, at the "src/" directory.

Copy the following VSCode launch configurations to the /.vscode/launch.json file's configurations[] array:

Debug with MS Edge

{
  "name": "Debug in Edge",
  "request": "launch",
  "type": "msedge",
  "url": "http://localhost:8080",
  "runtimeArgs": [
    "--remote-debugging-port=9222"
  ]
}

Debug with Chrome

{
  "name": "Debug in Chrome",
  "request": "launch",
  "type": "chrome",
  "url": "http://localhost:8080",
  "runtimeArgs": [
    "--remote-debugging-port=9222"
  ]
}

Run the app using Node or from a container.
Select a debugger to run in VSCode. Press Ctrl + Shift + D
- Select "Debug in Edge" to launch an Edge web browser.
- Select "Debug in Chrome" to launch a Chrome web browser.

Debugging Traditional Web Apps in VSCode

Debugging traditional (vanilla) web apps, consisting of static HTML, CSS and JavaScript with VSCode is similar to debugging and adding breakpoints from the Chrome or Edge browser's Sources tab.

TIP
Take note of its VSCode launch settings with a "pathMapping" key. It is quite similar to the VSCode launch settings of web apps launched with Webpack.

Add breakpoints in the JavaScript (*.js) files inside the website's directory.

Copy the following VSCode launch configurations to the /.vscode/launch.json file's configurations[] array. The "public" directory contains the JavaScript files in the web app's local directory.

Debug with MS Edge

{
  "name": "Debug Regular App in Edge",
  "request": "launch",
  "type": "msedge",
  "url": "http://localhost:3000",
  "pathMapping": {
    "/": "${workspaceFolder}/public",
  }
}

Debug with Chrome

{
  "name": "Debug Regular App in Chrome",
  "request": "launch",
  "type": "chrome",
  "url": "http://localhost:3000",
  "pathMapping": {
    "/": "${workspaceFolder}/public",
  }
}

Run the app using Node or from a container.
Select a debugger to run in VSCode. Press Ctrl + Shift + D
- Select "Debug Regular App in Edge" to launch an Edge web browser.
- Select "Debug Regular App in Chrome" to launch a Chrome web browser.

Node Scripts (JavaScript)

Debugging Node NPM Scripts

Method 1 - Using the JavaScript Debug Terminal

Launch a JavaScript Debug Terminal in VSCode.
Run an NPM script in the JavaScript Debug Terminal, for example, "npm run dev." Running an NPM script in the JavaScript Debug terminal automatically runs it in VSCode debug mode.

Method 2 - Using Run/Debug Script Shortcut in the package.json file

Open the Node app's package.json file in VSCode.
Hover over the name of an NPM script listed under its "scripts" section.
Press the Debug Script. It runs the NPM script and catches breakpoints in VSCode.

Method 3 - Using VSCode Launch Settings

Add the following "configurations" settings inside a .vscode/launch.json file.

Set the "program" part to the entry point of a Node script.

Add an "envFile" entry, pointing to the Node app's .env file if needed.

{
  "type": "node",
  "request": "launch",
  "name": "Launch Program",
  "skipFiles": [
    "<node_internals>/**"
  ],
  "program": "${workspaceFolder}\\server\\src\\index.js",
  "envFile": "${workspaceFolder}/server/.env"
}

Run the VSCode Debugger. It will launch the program in debug mode.

Debugging Node NPM Scripts Running Inside a Container

Add a --inspect=0.0.0.0:9229 flag in a Node script inside the package.json file. For example:

"scripts": {
  "start": "npm run hipsum",
  "scrape": "node --inspect=0.0.0.0:9229 src/scripts/scrape.js",
  "hipsum": "node src/scripts/hipsum.js",
  ...
},

Add the following entry in the "configurations" array of a .vscode/launch.json file. Ensure the "localRoot" points to the script source codes in the host machine, and "remoteRoot" maps to its counterpart in the container.
```
{
  "type": "node",
  "request": "attach",
  "name": "Attach to Docker",
  "port": 9229,
  "address": "localhost",
  "localRoot": "${workspaceFolder}/src/scripts",
  "remoteRoot": "/opt/app/src/scripts"
},
```
Prepare the NPM script for debugging. A delay setTimeout() of several seconds might be necessary before running the script to prevent it from exiting early to enable attaching the VSCode debugger.
Mark breakpoints in the script/s to debug in VSCode.
Run the NPM script using Docker.
Launch the Attach to Docker VSCode debugger.

weaponsforge/debugging_with_vscode.md