Using Debugging Tools with Next.js – Full Stack Inspection with VS Code, DevTools, and Server Flags

Introduction

Next.js supports full-stack debugging with source maps, allowing you to inspect both frontend and backend code. You can use VS Code, Chrome DevTools, Firefox DevTools, or any debugger that attaches to Node.js.

Debugging with VS Code

Create a .vscode/launch.json file with the following configurations:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Next.js: debug server-side",
      "type": "node-terminal",
      "request": "launch",
      "command": "npm run dev"
    },
    {
      "name": "Next.js: debug client-side",
      "type": "chrome",
      "request": "launch",
      "url": "http://localhost:3000"
    },
    {
      "name": "Next.js: debug client-side (Firefox)",
      "type": "firefox",
      "request": "launch",
      "url": "http://localhost:3000",
      "reAttach": true,
      "pathMappings": [
        {
          "url": "webpack://_N_E",
          "path": "${workspaceFolder}"
        }
      ]
    },
    {
      "name": "Next.js: debug full stack",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/node_modules/next/dist/bin/next",
      "runtimeArgs": ["--inspect"],
      "skipFiles": ["/**"],
      "serverReadyAction": {
        "action": "debugWithEdge",
        "killOnServerStop": true,
        "pattern": "- Local:.+(https?://.+)",
        "uriFormat": "%s",
        "webRoot": "${workspaceFolder}"
      }
    }
  ]
}

Change debugWithEdge to debugWithChrome if using Chrome. Add cwd if your Next.js app is in a subdirectory (e.g. Turborepo).

Debugging with WebStorm

Create a JavaScript Debug configuration with http://localhost:3000 as the URL. Run it to open your browser and attach to both server and client code.

Client-Side Debugging with Browser DevTools

• Start your server with npm run dev or next dev
• Open http://localhost:3000 in Chrome or Firefox
• Use Sources tab in Chrome or Debugger tab in Firefox
• Press Ctrl+P / ⌘+P to search files and set breakpoints

Source paths will start with webpack://_N_E/./.

React Developer Tools

Install the React Developer Tools browser extension to inspect components, props, state, and performance issues.

Server-Side Debugging with --inspect

Use the --inspect flag to attach browser DevTools to your Node.js server:

NODE_OPTIONS='--inspect' next dev

For remote access (e.g. Docker):

NODE_OPTIONS='--inspect=0.0.0.0' next dev

Update package.json:

{
  "scripts": {
    "dev": "NODE_OPTIONS='--inspect' next dev"
  }
}

Attaching DevTools to Server

Chrome

• Visit chrome://inspect
• Click Configure and add localhost:9229
• Find your app under Remote Target and click Inspect

Firefox

• Visit about:debugging
• Click This Firefox
• Find your app under Remote Targets and click Inspect

Inspecting Server Errors

When an error occurs, Next.js shows a Node.js icon below the version indicator. Click it to copy the DevTools URL and inspect the server process.

Debugging on Windows

Windows doesn’t support NODE_OPTIONS='--inspect' syntax. Use cross-env:

{
  "scripts": {
    "dev": "cross-env NODE_OPTIONS='--inspect' next dev"
  }
}

Install with npm i -D cross-env. Disable Windows Defender to improve Fast Refresh performance.

Conclusion

Next.js offers robust debugging support across environments. Whether you're inspecting client-side code, server logic, or full-stack behavior, tools like VS Code, DevTools, and --inspect give you full visibility and control over your application.