Monitorear errores en producción es la forma más honesta de escuchar a tus usuarios. Cuando integras Sentry en Next.js, conviertes cada fallo en feedback accionable y dejas de depender de reportes manuales para saber qué está roto en tu aplicación.

Esta guía te muestra cómo conectar Sentry con Next.js usando el archivo de instrumentation, configurar variables de entorno y validar que los errores lleguen a tu dashboard. Es relevante para desarrolladores que ya tienen una app en producción y quieren profesionalizar su monitoreo.

Por qué la observabilidad importa en una app Next.js

Los usuarios rara vez te escriben para contarte que algo falló. Se van. Por eso necesitas un sistema que capture los errores por ti antes de que se conviertan en abandono.

La observabilidad es el conjunto de procesos y sistemas que permiten a tu aplicación monitorear todo lo que puede salir mal: errores de JavaScript en el cliente, fallos en ejecución del servidor, problemas de red. Todo eso se centraliza en un dashboard donde puedes clasificar, revisar y detectar patrones [01:05].

¿Qué es la observabilidad en aplicaciones web? Es la capacidad de capturar automáticamente errores del cliente, servidor y red, agruparlos en un panel y analizarlos para encontrar patrones que afectan a tus usuarios.

Qué hace Sentry y por qué se integra tan bien con Next.js

Sentry es un servicio popular de captura de errores que ganó tracción gracias a su integración nativa con frameworks como Next.js y Nuxt. Funciona tanto en cliente como en servidor, y se conecta con las APIs especializadas que Next.js expone para herramientas de terceros [01:48].

La pieza clave que habilita esta integración profunda es el archivo instrumentation.ts, una funcionalidad de Next.js diseñada precisamente para que servicios externos accedan a información de la app de Node.js que está corriendo.

Cómo se conecta Sentry con el archivo instrumentation

Cuando corres el instalador de Sentry, se crea un instrumentation.ts en la raíz del proyecto. Allí se importa Sentry, se registra y se aplican configuraciones distintas para tres entornos:

• Cliente, para errores que ocurren en el navegador.
• Servidor, para errores en Node.js.
• Edge, útil si despliegas en Vercel o Cloudflare.

En la mayoría de proyectos no necesitas tocar este archivo. Solo dejas que Sentry lo administre.

Cómo instalar Sentry paso a paso en un proyecto Next.js

El flujo recomendado es usar el script que Sentry genera al crear tu cuenta en sentry.io. Cuando seleccionas Next.js como frontend, te entrega un comando listo para copiar y pegar en tu terminal [03:30].

Durante la instalación, Sentry te hará varias preguntas. Estas son las decisiones clave:

1. Proxy a través de Next.js Server para evitar adblockers: opcional.
2. Tracing: muy recomendado activarlo.
3. Session replay: depende de tu caso de uso.
4. Página de ejemplo para probar errores: actívala para validar la integración.
5. Compatibilidad con Turbopack: aún no es completa, así que prepárate para deshabilitarlo.

Después de la instalación, Sentry modifica tu next.config, agrega una nueva dependencia especializada para Next.js y recrea el global-error.tsx con la diferencia crítica de que ahora envía cada error a sus servidores.

Cómo manejar el SENTRY_DSN con variables de entorno

El instalador deja la llave DSN escrita directamente en los archivos de configuración. Para una app profesional, esto no escala. Lo correcto es moverla a tu .env:

SENTRY_DSN=tu_llave_aqui

Luego referencias process.env.SENTRY_DSN en las configuraciones de cliente, servidor y edge. También conviene replicarla en tu .env.example (vacía) para que otros desarrolladores sepan qué variables necesitan [07:45].

¿Por qué usar variables de entorno para el DSN de Sentry? Aunque el DSN puede exponerse públicamente, manejarlo como variable de entorno mantiene tu configuración limpia, escalable y consistente entre entornos de desarrollo, staging y producción.

Cómo probar que Sentry está capturando errores correctamente

Sentry te crea automáticamente una página en /sentry-example-page con un botón que arroja un error a propósito. Antes de probarla, deshabilita Turbopack en tu package.json modificando el comando dev para que use Webpack por defecto, ya que el SDK aún tiene fricciones con Turbopack [09:20].

Corre pnpm dev, navega a la página de ejemplo y haz clic en el botón. En modo desarrollo, Next.js intercepta el error y lo muestra en pantalla en vez de mostrar la página global de error. Aun así, Sentry captura el error en segundo plano y lo envía al dashboard.

El issue puede tardar unos segundos en aparecer dependiendo de tu plan y de la carga en los servidores de Sentry. Una vez que llega, puedes inspeccionar el stack trace, los archivos involucrados y el contexto del usuario.

Qué archivos de Next.js trabajan con servicios de observabilidad

La señal de que un servicio está bien integrado con Next.js es que use estos tres archivos:

• error.tsx para errores en rutas específicas.
• global-error.tsx para errores que escapan al layout raíz.
• instrumentation.ts para conectar con APIs profundas de Next.js.

Si el servicio que eliges no aprovecha instrumentation, vas a capturar menos datos. No es obligatorio, pero marca la diferencia entre una integración superficial y una completa.

Ahora te toca a ti: crea tu cuenta gratuita en sentry.io, integra el SDK en una app real y cuéntame en los comentarios qué tipo de errores estás detectando que antes pasaban desapercibidos.