Cómo utilizar herramientas de depuración con Next.js

Esta documentación explica cómo puedes depurar el código frontend y backend de tu aplicación Next.js con soporte completo de mapas de fuentes utilizando el depurador de VS Code, Chrome DevTools o Firefox DevTools.

Cualquier depurador que pueda conectarse a Node.js también puede usarse para depurar una aplicación Next.js. Puedes encontrar más detalles en la Guía de Depuración de Node.js.

Depuración con VS Code

Crea un archivo llamado .vscode/launch.json en la raíz de tu proyecto con el siguiente contenido:

launch.json

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Next.js: depuración del lado del servidor",
      "type": "node-terminal",
      "request": "launch",
      "command": "npm run dev"
    },
    {
      "name": "Next.js: depuración del lado del cliente",
      "type": "chrome",
      "request": "launch",
      "url": "http://localhost:3000"
    },
    {
      "name": "Next.js: depuración del lado del cliente (Firefox)",
      "type": "firefox",
      "request": "launch",
      "url": "http://localhost:3000",
      "reAttach": true,
      "pathMappings": [
        {
          "url": "webpack://_N_E",
          "path": "${workspaceFolder}"
        }
      ]
    },
    {
      "name": "Next.js: depuración de pila completa",
      "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}"
      }
    }
  ]
}

Nota: Para usar la depuración con Firefox en VS Code, necesitarás instalar la extensión Firefox Debugger.

npm run dev puede reemplazarse por yarn dev si estás usando Yarn o pnpm dev si estás usando pnpm.

En la configuración "Next.js: depuración de pila completa", serverReadyAction.action especifica qué navegador abrir cuando el servidor esté listo. debugWithEdge significa lanzar el navegador Edge. Si estás usando Chrome, cambia este valor a debugWithChrome.

Si estás cambiando el número de puerto en el que inicia tu aplicación, reemplaza el 3000 en http://localhost:3000 con el puerto que estés usando.

Si estás ejecutando Next.js desde un directorio que no es la raíz (por ejemplo, si estás usando Turborepo), entonces necesitas agregar cwd a las tareas de depuración del lado del servidor y de pila completa. Por ejemplo, "cwd": "${workspaceFolder}/apps/web".

Ahora ve al panel de Depuración (Ctrl+Shift+D en Windows/Linux, ⇧+⌘+D en macOS), selecciona una configuración de lanzamiento, luego presiona F5 o selecciona Debug: Start Debugging desde la Paleta de Comandos para iniciar tu sesión de depuración.

Usando el depurador en Jetbrains WebStorm

Haz clic en el menú desplegable que lista la configuración de tiempo de ejecución y haz clic en Edit Configurations.... Crea una configuración de depuración JavaScript Debug con http://localhost:3000 como la URL. Personalízala a tu gusto (por ejemplo, navegador para depuración, guardar como archivo de proyecto) y haz clic en OK. Ejecuta esta configuración de depuración y el navegador seleccionado debería abrirse automáticamente. En este punto, deberías tener 2 aplicaciones en modo de depuración: la aplicación Node NextJS y la aplicación cliente/navegador.

Depuración con DevTools del navegador

Código del lado del cliente

Inicia tu servidor de desarrollo como de costumbre ejecutando next dev, npm run dev o yarn dev. Una vez que el servidor inicie, abre http://localhost:3000 (o tu URL alternativa) en tu navegador preferido.

Para Chrome:

Abre las Herramientas de Desarrollo de Chrome (Ctrl+Shift+J en Windows/Linux, ⌥+⌘+I en macOS)
Ve a la pestaña Sources

Para Firefox:

Abre las Herramientas de Desarrollo de Firefox (Ctrl+Shift+I en Windows/Linux, ⌥+⌘+I en macOS)
Ve a la pestaña Debugger

En cualquier navegador, cada vez que tu código del lado del cliente alcance una declaración debugger, la ejecución del código se pausará y ese archivo aparecerá en el área de depuración. También puedes buscar archivos para establecer puntos de interrupción manualmente:

En Chrome: Presiona Ctrl+P en Windows/Linux o ⌘+P en macOS
En Firefox: Presiona Ctrl+P en Windows/Linux o ⌘+P en macOS, o usa el árbol de archivos en el panel izquierdo

Ten en cuenta que al buscar, tus archivos fuente tendrán rutas que comienzan con webpack://_N_E/./.

Código del lado del servidor

Para depurar código del lado del servidor de Next.js con DevTools del navegador, necesitas pasar la bandera --inspect al proceso subyacente de Node.js:

Terminal

NODE_OPTIONS='--inspect' next dev

Bueno saber: Usa NODE_OPTIONS='--inspect=0.0.0.0' para permitir acceso remoto de depuración fuera de localhost, como cuando ejecutas la aplicación en un contenedor Docker.

Si estás usando npm run dev o yarn dev, entonces deberías actualizar el script dev en tu package.json:

package.json

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

Iniciar el servidor de desarrollo de Next.js con la bandera --inspect se verá algo así:

Terminal

Debugger listening on ws://127.0.0.1:9229/0cf90313-350d-4466-a748-cd60f4e47c95
For help, see: https://nodejs.org/en/docs/inspector
ready - started server on 0.0.0.0:3000, url: http://localhost:3000

Para Chrome:

Abre una nueva pestaña y visita chrome://inspect
Haz clic en Configure... para asegurarte de que ambos puertos de depuración estén listados
Agrega tanto localhost:9229 como localhost:9230 si no están presentes
Busca tu aplicación Next.js en la sección Remote Target
Haz clic en inspect para abrir una ventana separada de DevTools
Ve a la pestaña Sources

Para Firefox:

Abre una nueva pestaña y visita about:debugging
Haz clic en This Firefox en la barra lateral izquierda
En Remote Targets, encuentra tu aplicación Next.js
Haz clic en Inspect para abrir el depurador
Ve a la pestaña Debugger

Depurar código del lado del servidor funciona de manera similar a la depuración del lado del cliente. Al buscar archivos (Ctrl+P/⌘+P), tus archivos fuente tendrán rutas que comienzan con webpack://{nombre-de-la-aplicación}/./ (donde {nombre-de-la-aplicación} será reemplazado con el nombre de tu aplicación según tu archivo package.json).

Inspeccionar errores del servidor con DevTools del navegador

Cuando encuentres un error, inspeccionar el código fuente puede ayudar a rastrear la causa raíz de los errores.

Next.js mostrará un ícono de Node.js debajo del indicador de versión de Next.js en el overlay de errores. Al hacer clic en ese ícono, la URL de DevTools se copiará a tu portapapeles. Puedes abrir una nueva pestaña del navegador con esa URL para inspeccionar el proceso del servidor Next.js.

Depuración en Windows

Los usuarios de Windows pueden encontrar un problema al usar NODE_OPTIONS='--inspect' ya que esa sintaxis no es compatible con plataformas Windows. Para solucionar esto, instala el paquete cross-env como dependencia de desarrollo (-D con npm y yarn) y reemplaza el script dev con lo siguiente.

package.json

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

cross-env establecerá la variable de entorno NODE_OPTIONS independientemente de la plataforma en la que estés (incluyendo Mac, Linux y Windows) y te permitirá depurar consistentemente entre dispositivos y sistemas operativos.

Bueno saber: Asegúrate de que Windows Defender esté desactivado en tu máquina. Este servicio externo verificará cada lectura de archivo, lo que según reportes aumenta considerablemente el tiempo de Fast Refresh con next dev. Este es un problema conocido, no relacionado con Next.js, pero sí afecta el desarrollo con Next.js.

Más información

Para aprender más sobre cómo usar un depurador de JavaScript, consulta la siguiente documentación:

Cómo utilizar herramientas de depuración con Next.js

On this page