Debugging

Core Idea

Debugar Next.js (frontend e backend) com source maps completos via VS Code debugger, Chrome/Firefox DevTools ou WebStorm; qualquer debugger que anexa em Node.js funciona.

Key Concepts

• .vscode/launch.json: define configs separadas pra debug server-side (node-terminal + npm run dev -- --inspect), client-side (Chrome/Firefox) e full stack (node + --inspect no binário do Next.js).
• serverReadyAction: na config full stack, abre automaticamente o browser (debugWithEdge/debugWithChrome) quando o servidor sobe.
• --inspect: flag passada ao processo Node subjacente pra permitir debug server-side via chrome://inspect ou about:debugging.
• --inspect=0.0.0.0: libera debug remoto (fora de localhost), útil em Docker.
• NODE_OPTIONS=--inspect-brk: necessário pra usar --inspect-brk/--inspect-wait, que não podem ser passados como flag direta do next dev.
• Ícone Node.js no error overlay: copia a URL do DevTools pro clipboard, pra inspecionar o processo do servidor após um erro.

Code Examples

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

• O que demonstra: três modos de debug (server, client, full stack) numa mesma config de VS Code.

Anti-patterns

• Debug lento no Windows: Windows Defender inspeciona cada leitura de arquivo, aumentando bastante o tempo de Fast Refresh; desabilitar (ou excluir a pasta do projeto) resolve.
• Rodar em monorepo sem cwd: em setups como Turborepo, esquecer "cwd": "${workspaceFolder}/apps/web" quebra a config de debug.

Key Takeaways

1. Debug server-side sempre exige a flag --inspect (ou NODE_OPTIONS=--inspect-brk pra variantes com breakpoint).
2. A config full stack do VS Code cobre client+server numa sessão só, abrindo o browser automaticamente.
3. React Developer Tools complementa o debug de componentes (props/state/performance).
4. No Windows, Defender é a causa mais comum de Fast Refresh lento durante debug.

Connects To

• ch306 Instrumentation: outra ferramenta de observabilidade server-side complementar ao debug manual.