Debugging

Basic Node.js Debugging Commands

Command	Purpose
--inspect	Enables debugging without pausing execution
--inspect-brk	Enables debugging and pauses at first line
Default port: 9229	The standard debugging port Node.js uses

Nx Monorepo Debugging Commands

# Run with debugging enabled (continues execution)
nx serve your-app-name --inspect
 
# Run with debugging enabled (pauses at first line)
nx serve your-app-name --inspect-brk
 
# Run with debugging on specific port
nx serve your-app-name --inspect=9230
 
# Run with debugging and watch mode
nx serve your-app-name --watch --inspect
 
# Debug tests
nx test your-app-name --watch --runInBand --inspect-brk

VS Code Configuration

Create a .vscode/launch.json file:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "attach",
      "name": "Attach to Nx app",
      "port": 9229,
      "restart": true,
      "skipFiles": ["<node_internals>/**"]
    },
    {
      "type": "node",
      "request": "launch",
      "name": "Debug Nx app",
      "runtimeExecutable": "npx",
      "runtimeArgs": [
        "nx",
        "serve",
        "your-app-name",
        "--inspect=9229"
      ],
      "console": "integratedTerminal",
      "skipFiles": ["<node_internals>/**"]
    }
  ]
}

Debugging Workflow Options

Option 1: Manual Start + Attach

1. Start the app with: nx serve your-app-name --inspect
2. In VS Code Debug panel, select “Attach to Nx app” configuration
3. Click the green play button to attach

Option 2: Automatic Start + Debug

1. In VS Code Debug panel, select “Debug Nx app” configuration
2. Click the green play button (starts app and attaches debugger)

Option 3: Debug from the Beginning

1. Start the app with: nx serve your-app-name --inspect-brk
2. Attach debugger as in Option 1
3. App will be paused at first line of code

Debugging Tips for Nx Monorepos

• Set breakpoints in VS Code by clicking left of line numbers
• Use conditional breakpoints for complex logic
• Use the VS Code Debug Console to evaluate expressions
• Add console.log statements strategically for tracing
• The debug configuration restart: true ensures the debugger reattaches after app restarts
• Use launch configurations over attach when possible for simplicity

Common Issues and Solutions

• If debugger won’t connect, check for port conflicts
• If breakpoints are not hitting, verify source maps are correctly configured
• For TypeScript projects, ensure sourceMap: true is set in tsconfig.json
• If performance is slow during debugging, be selective with breakpoints