Debugging

Core Idea

Como debugar frontend e backend de um app Next.js com source maps completos, usando VS Code, WebStorm ou DevTools do Chrome/Firefox.

Key Concepts

• .vscode/launch.json: define configurações de debug (node-terminal para server-side, chrome/firefox para client-side, node para full stack).
• --inspect flag: passado ao next dev (npm run dev -- --inspect) para expor o processo Node.js a um debugger externo; usar --inspect=0.0.0.0 para debug remoto (ex.: Docker).
• NODE_OPTIONS=--inspect-brk: necessário para usar --inspect-brk/--inspect-wait, que não podem ser passados como flag direta do next dev.
• webpack://_N_E/./: prefixo de path usado pelos source maps do client-side ao buscar arquivo (Ctrl+P/⌘+P) no DevTools.
• webpack://{application-name}/./: prefixo equivalente para arquivos server-side, onde {application-name} vem do package.json.
• Node.js icon no error overlay: ao clicar, copia a URL de DevTools do processo server do Next.js para a área de transferência.
• React Developer Tools: extensão de browser para inspecionar componentes, editar props/state e identificar problemas de performance.

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 estratégias de debug configuráveis no VS Code (server-side isolado, client-side isolado, full stack com auto-abertura do browser); debugWithEdge troca para debugWithChrome conforme o browser usado.

# Server-side debug via terminal, aberto no chrome://inspect ou about:debugging
npm run dev -- --inspect

• O que demonstra: flag mínima para expor o processo Node do next dev a qualquer debugger externo compatível.

Anti-patterns

• Debugar em máquina Windows com Windows Defender ativo no diretório do projeto: o scan de "every file read" degrada bastante o tempo de Fast Refresh no next dev; desabilitar/excluir a pasta é recomendado.
• Usar Turborepo/monorepo sem setar cwd: rodando o Next.js fora da raiz do workspace, as configs de debug server-side/full stack precisam de "cwd": "${workspaceFolder}/apps/web" ou falham ao localizar o processo.

Key Takeaways

1. Debug client e server são configurações separadas em launch.json; full stack combina ambas com serverReadyAction.
2. --inspect (ou NODE_OPTIONS=--inspect-brk para break-on-start) é o mecanismo comum a VS Code, Chrome DevTools e Firefox DevTools.
3. Os paths dos source maps mudam entre client (webpack://_N_E/./) e server (webpack://{app-name}/./) ao buscar arquivo no DevTools.
4. Em Windows, Windows Defender é uma causa conhecida (não relacionada ao Next.js) de Fast Refresh lento durante debug/dev.

Connects To

• Deploying to Platforms (ch039): debug local não reflete requisitos de streaming/self-hosting cobertos ali.
• Environment Variables (ch041): NODE_ENV interage com qual .env* é carregado durante sessões de debug/test.