Depurar aplicaciones Astro SSR

Depurar aplicaciones Astro con Visual Studio Code añadiendo breakpoints en el lado del servidor SSR.

Depurar y añadir breakpoints en una aplicación Astro es sencillo si queremos hacerlo en el código JavaScript que se ejecuta en el navegador, basta con añadir debugger y abrir la aplicación Devtools de Chrome para que el programa pare en el punto especificado. Sin embargo, es un poco más complicado si queremos parar el programa el el código que se ejecuta en el servidor, por ejemplo si usamos Astro Server Side Rendering.

Para lograrlo, basta con crear una configuración mínima dentro del proyecto en Visual Studio Code que nos permita lanzar nuestro servidor de desarrollo directamente desde el editor con soporte para breakpoints. Vamos a verlo paso a paso.

Preparando el entorno

Primero, asegurémonos de tener un proyecto Astro funcionando con pnpm. Si usamos npm o yarn, la lógica es parecida pero hay que cambiar el comando.

Después, vamos a crear la configuración de depuración. En la raíz del proyecto ejecutamos:

mkdir .vscode
touch .vscode/launch.json

Luego, editamos el archivo launch.json con este contenido:

{
  "version": "0.2.0",
  "configurations": [
    {
      "command": "pnpm dev",
      "name": "Development server",
      "request": "launch",
      "type": "node-terminal"
    },
    {
      "command": "pnpm build",
      "name": "Build",
      "request": "launch",
      "type": "node-terminal"
    }
  ]
}

Esto le indica a VS Code que queremos iniciar el servidor de desarrollo desde su terminal integrada.

Habilitando breakpoints en el código del servidor

Si queremos colocar un breakpoint en el código que se ejecuta en el servidor, por ejemplo, dentro de un archivo archivo.ts o directamente en un archivo .astro, necesitamos que ese código pase por Node.js en modo desarrollo.

Ahora, para que los puntos de control funcionen, abrimos alguno de estos archivos y colocamos un breakpoint en la línea que queremos inspeccionar. Podemos hacerlo con el ratón haciendo clic cerca del número de línea, o bien añadir la palabra debugger donde queremos que pare. Luego, iniciamos la configuración “Development server” desde la vista de ejecución de VS Code (Ctrl+Shift+D o desde el ícono de depuración en la barra lateral) y pulsamos el botón de play (o pulsamos f5) para iniciar el servidor en modo debugger.

Ahora podemos ir al navegador y cuando accedamos a la ruta que ejecuta ese archivo, VS Code pausará justo donde colocamos el breakpoint. Ahí podemos inspeccionar variables, el contexto de ejecución, el stack… todo desde el mismo editor.

Un ejemplo simple de un archivo .astro con código del lado del servidor y un breakpoint:

---
import { getData } from '../lib/data'

const result = await getData()
debugger
if (!result) {
  throw new Error("No data received")
}
---
<html>
  <body>
    <h1>Datos cargados</h1>
  </body>
</html>

Añadimos un breakpoint (debugger) en la línea siguiente del await getData() y luego usar la consola de depuración para ver qué está devolviendo.

Un par de detalles útiles

Si el breakpoint no se activa, es probable que estemos accediendo a una ruta distinta o que el archivo esté siendo cargado de forma diferente.
También puede ayudar reiniciar la sesión de depuración y limpiar el caché (.astro) si hay cambios que no se reflejan.
En proyectos grandes, mantener los breakpoints organizados es clave para no perder tiempo.

Para terminar

Con esta configuración básica ya podemos depurar el SSR de Astro desde VS Code sin depender sólo de console.log. Tener esta visibilidad desde el editor mejora el flujo de trabajo y permite detectar errores con mayor precisión.