Cómo añadir la monitorización de Sentry a una aplicación Webflow Cloud

Cómo configurar el seguimiento de errores de Sentry en una aplicación Next.js de Webflow Cloud

Webflow Cloud funciona sobre Cloudflare Workers, que es un entorno gestionado. No controlas el tiempo de ejecución directamente, y su observabilidad integrada incluye métricas a nivel de solicitud: recuento de solicitudes, tiempo de CPU y uso de memoria. Útil para la planificación de capacidad.

Si quieres añadir depuración, Sentry proporciona capas de monitorización como el agrupamiento de errores, seguimientos de pila, seguimientos de rendimiento y reproducción de sesiones. Cuando un gestor de rutas falla, verás exactamente dónde. Cuando un componente de cliente se bloquea, verás exactamente por qué.

En este artículo, repasamos la configuración manual completa, incluidas las configuraciones de túnel específicas para Cloudflare, además de los cinco modos de fallo silencioso y sus soluciones.

¿Qué necesitas para añadir Sentry a una aplicación de Webflow Cloud?

Necesitas una cuenta de Sentry (el plan gratuito funciona) y una aplicación de Webflow Cloud ejecutando Next.js. Crearás cinco archivos, modificarás uno y añadirás cuatro variables de entorno. El asistente de Sentry puede generar la mayor parte de esto automáticamente, pero aquí explico la configuración manual para que cada pieza sea comprensible, no solo esté ahí.

Si estás empezando desde cero con la aplicación en la nube, esta guía de Webflow Cloud cubre el andamiaje inicial. La configuración manual que aparece a continuación funciona tanto para proyectos creados a través de la CLI de Webflow como para aplicaciones existentes migradas a Webflow Cloud.

Cada paso incluye el razonamiento detrás de la configuración, para que entiendas qué hacer cuando algo no funciona, en lugar de limitarte a tener archivos de configuración sin contexto.

4 pasos para añadir la monitorización de Sentry a una aplicación de Webflow Cloud

La configuración afecta a cinco archivos y un archivo de configuración. Los pasos 1 y 2 instalan el SDK y crean los archivos de inicialización de Sentry. El paso 3 gestiona las variables de entorno y el ajuste del túnel específico para Cloudflare que la mayoría de las guías de Sentry pasan por alto. El paso 4 verifica la canalización completa y configura las alertas.

Así es como encaja cada paso.

1. Instala el SDK de Sentry y envuelve tu configuración de Next.js

Aquí ocurren dos cosas: la instalación del paquete trae el SDK, y envolver next.config.ts con withSentryConfig activa la carga de mapas de origen y la instrumentación automática en todos los gestores de rutas y componentes de servidor.

El paquete <a href="https://docs.sentry.io/platforms/javascript/guides/nextjs/" target="_blank" rel="noopener noreferrer">@sentry/nextjs</a> gestiona la instrumentación tanto del cliente como del servidor con una sola instalación:

npm install @sentry/nextjs --save

Luego abre next.config.ts (o next.config.js si eso es lo que generó el andamiaje) y envuelve tu configuración existente con withSentryConfig:

// next.config.ts
import type { NextConfig } from "next";
import { withSentryConfig } from "@sentry/nextjs";

const nextConfig: NextConfig = {
  basePath: "/app",       // your Webflow Cloud mount path
  assetPrefix: "/app",
};

export default withSentryConfig(nextConfig, {
  org: "your-org-slug",
  project: "your-project-slug",

  // Upload source maps — requires SENTRY_AUTH_TOKEN in CI
  authToken: process.env.SENTRY_AUTH_TOKEN,
  widenClientFileUpload: true,

  // Suppress upload logs outside of CI
  silent: !process.env.CI,

  // Route Sentry events through your Next.js server
  // This is required for Webflow Cloud — see Step 3 for why
  tunnelRoute: "/sentry-tunnel",
});

withSentryConfig inyecta el plugin de webpack de Sentry en la compilación. Gestiona la carga de mapas de origen durante el despliegue y configura la instrumentación automática para capturar errores de los gestores de rutas, componentes de servidor y middleware sin necesidad de envolver nada más.

La opción tunnelRoute es importante. Explicaré exactamente por qué en el paso 3. Por ahora, mantenla exactamente como se muestra.

2. Crea los cinco archivos de inicialización

Sentry necesita archivos de inicio independientes para los tres entornos en los que se ejecuta tu aplicación: navegador, servidor Node.js (desarrollo local) y Cloudflare Workers edge (producción). Un cuarto archivo, `instrumentation.ts`, carga el correcto en tiempo de ejecución. El quinto, `app/global-error.tsx`, va en el directorio app.

Crea los cuatro primeros en la raíz de tu proyecto.

Inicialización del lado del cliente (instrumentation-client.ts)

instrumentation-client.tsse ejecuta en el navegador. Inicializa la captura de errores, la reproducción de sesiones y el seguimiento de rendimiento para todo lo que se ejecuta en el navegador del usuario, y exporta `onRouterTransitionStart` para instrumentar las transiciones de ruta del lado del cliente.

Crea este archivo en la raíz de tu proyecto:

// instrumentation-client.ts
import * as Sentry from "@sentry/nextjs";

Sentry.init({
  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,

  // Capture 100% of traces in dev, 10% in production
  tracesSampleRate: process.env.NODE_ENV === "development" ? 1.0 : 0.1,

  // Record session replays for 10% of sessions, 100% when an error occurs
  replaysSessionSampleRate: 0.1,
  replaysOnErrorSampleRate: 1.0,

  integrations: [Sentry.replayIntegration()],
});

// Instrument client-side route transitions
export const onRouterTransitionStart = Sentry.captureRouterTransitionStart;

La división de tracesSampleRate (100% en desarrollo, 10% en producción) evita que el volumen de trazas infle tu cuota de Sentry con tráfico real, manteniendo al mismo tiempo una visibilidad total a nivel local.

Inicialización del entorno de ejecución Edge (sentry.edge.config.ts)

sentry.edge.config.tsse ejecuta en Cloudflare Workers (producción). Mantén esta configuración al mínimo: el entorno de ejecución de Workers descarta silenciosamente las integraciones específicas del navegador o de Node.js, así que prueba cuidadosamente cualquier cosa más allá del DSN y la tasa de muestreo antes de añadirla aquí.

Crea este archivo en la raíz de tu proyecto:

// sentry.edge.config.ts
import * as Sentry from "@sentry/nextjs";

Sentry.init({
  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
  tracesSampleRate: 0.1,
});

Un tracesSampleRate más bajo en la configuración edge tiene sentido: este archivo está activo en cada solicitud de producción, y capturar el 100% de las trazas consumiría rápidamente tu cuota de Sentry con cualquier volumen de tráfico significativo.

Inicialización del servidor Node.js (sentry.server.config.ts)

sentry.server.config.tsse ejecuta en Node.js (desarrollo local). Nunca se despliega en Cloudflare Workers; `instrumentation.ts` (el siguiente) solo lo importa cuando `NEXT_RUNTIME` es igual a "nodejs".

Crea este archivo en la raíz de tu proyecto:

// sentry.server.config.ts
import * as Sentry from "@sentry/nextjs";

Sentry.init({
  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
  tracesSampleRate: 1.0, // 100% in dev
});

Establecer tracesSampleRate en 1.0 aquí es intencional. En desarrollo, quieres una cobertura total de trazas para detectar problemas antes de que lleguen a producción.

Selector de entorno de ejecución (instrumentation.ts)

instrumentation.tscarga la configuración edge o de servidor según el entorno de ejecución activo. Lee `NEXT_RUNTIME` al inicio e importa la configuración de Sentry correcta para el entorno actual. También exporta `onRequestError`, que captura excepciones de los Server Components, Route Handlers y middleware.

Crea este archivo en la raíz de tu proyecto:

// instrumentation.ts
import * as Sentry from "@sentry/nextjs";

export async function register() {
  if (process.env.NEXT_RUNTIME === "nodejs") {
    await import("./sentry.server.config");
  }
  if (process.env.NEXT_RUNTIME === "edge") {
    await import("./sentry.edge.config");
  }
}

// Captures errors from Server Components, Route Handlers, and middleware
export const onRequestError = Sentry.captureRequestError;

La comprobación le indica a Sentry si se está ejecutando en Cloudflare Workers () o en el servidor de desarrollo local de Next.js (). En una desplegada, es la configuración activa. En tu máquina ejecutando , se ejecuta en su lugar.NEXT_RUNTIME"edge""nodejs"sentry.edge.config.tsnext devsentry.server.config.ts

Límite de error global (app/global-error.tsx)

Por último, añade para capturar errores de renderizado de React que superen tus límites de error:app/global-error.tsx

// app/global-error.tsx
"use client";

import * as Sentry from "@sentry/nextjs";
import NextError from "next/error";
import { useEffect } from "react";

export default function GlobalError({ error }: { error: Error & { digest?: string } }) {
  useEffect(() => {
    Sentry.captureException(error);
  }, [error]);

  return (
    <html>
      <body>
        <NextError statusCode={0} />
      </body>
    </html>
  );
}

Después de crear los cinco archivos, ejecuta localmente para confirmar que la compilación se completa sin errores. Si Sentry no puede encontrar la configuración , registra una advertencia pero no falla. Presta atención a esto en la salida de la compilación.next buildwithSentryConfig

3. Configura las variables de entorno

Este paso cumple dos funciones. Primero, añade las cuatro variables de entorno que Sentry necesita. Segundo, explica por qué tunnelRoute es necesario específicamente para Webflow Cloud. Si te saltas esto, Sentry capturará los errores, pero nunca los enviará.

Añade cuatro variables a .env.local:

NEXT_PUBLIC_SENTRY_DSN=https://your-dsn@o0.ingest.sentry.io/0
SENTRY_AUTH_TOKEN=sntrys_your_auth_token_here
SENTRY_ORG=your-org-slug
SENTRY_PROJECT=your-project-slug

NEXT_PUBLIC_SENTRY_DSN lleva el prefijo NEXT_PUBLIC_ porque el SDK del lado del cliente lo requiere. El DSN no es un secreto; es seguro exponerlo en el navegador. SENTRY_AUTH_TOKEN es un secreto y no debe incluirse en el control de versiones. Añádelo a .gitignore junto con .env.local.

Encuentra tu DSN en el panel de control de Sentry, en Configuración del proyecto → Claves de cliente (DSN). Genera un token de autenticación de organización en Configuración de desarrollador → Tokens de autenticación. Los tokens de autenticación de organización tienen permisos automáticos para subir mapas de origen y crear versiones.

¿Por qué es necesario tunnelRoute en Webflow Cloud?

Nota: La documentación de Sentry requiere compatibility_date: "2025-08-16" o posterior en wrangler.json para que el SDK pueda enviar eventos a los servidores de Sentry mediante https.request. Webflow Cloud genera automáticamente un archivo `wrangler.json` con una fecha de compatibilidad anterior al `2025-08-16`, y no puedes editar ese archivo directamente. Si configuras Sentry sin solucionar esto, los errores se capturarán en la memoria, pero nunca se enviarán.

El tunnelRoute: "/sentry-tunnel" que añadiste a next.config.ts en el paso 1 resuelve esto. En lugar de que el SDK de Sentry realice una solicitud saliente directa desde el Worker (lo cual requiere una fecha de compatibilidad más reciente), redirige los eventos a través de un controlador de rutas de Next.js usando fetch(), que está disponible en todas las versiones de Cloudflare Workers.

El túnel también evita que los bloqueadores de anuncios intercepten el tráfico de Sentry, algo que resultó ser más importante de lo que esperaba. En una herramienta que lancé para un cliente, aproximadamente el 30% de los usuarios tenía algún tipo de bloqueador de contenido activo.

Cómo añadir variables de entorno a Webflow Cloud

Antes de desplegar, añade NEXT_PUBLIC_SENTRY_DSN y SENTRY_AUTH_TOKEN a tu entorno de Webflow Cloud. En la configuración de tu sitio de Webflow, ve a Webflow Cloud, abre tu entorno y añade ambos en Variables de entorno:

webflow auth login
webflow cloud deploy

O haz un push a tu rama de GitHub conectada para activar un despliegue automático.

4. Verifica la captura de errores y configura alertas

Tras el despliegue, provoca un error de prueba para confirmar que todo el proceso funciona correctamente.

Añade un botón a cualquier página que genere un error al hacer clic:

// Add temporarily to any page to test
<button
  onClick={() => {
    throw new Error("Sentry test — Webflow Cloud");
  }}
>
  Test Sentry
</button>

Haz clic en él y luego abre la sección de incidencias (Issues) en tu panel de Sentry. El error debería aparecer en menos de 30 segundos. Si es así, la captura de errores del lado del cliente funciona.

Para probar la captura del lado del servidor, provoca un error intencionado dentro de un controlador de rutas y confirma que aparece en Sentry. El seguimiento de la pila (stack trace) debería incluir el nombre de tu archivo fuente y el número de línea, no el código compilado.

Eso significa que la SENTRY_AUTH_TOKEN subida de mapas de origen funciona. He lanzado aplicaciones en la nube donde faltaban los mapas de origen, y depurar errores críticos significaba tener que rastrear código minificado. La configuración adicional merece la pena para obtener seguimientos legibles.

Para las alertas, ve a Alertas → Crear alerta en Sentry. Las dos reglas que configuro para cada proyecto son:

• Una alerta de tasa de error por proyecto que se activa cuando los nuevos errores superan un nivel base.
• Una alerta de incidencia individual para excepciones no controladas en los controladores de rutas.

Configura el canal de notificaciones a correo electrónico o Slack. Ambos funcionan sin necesidad de configuración adicional.

Resultado esperado: Los errores del navegador, los Server Components y el entorno de ejecución edge de Cloudflare Workers aparecen en Sentry con seguimientos de pila legibles. Las repeticiones de sesión se graban al producirse un error. Las alertas se activan cuando surgen nuevos problemas.

¿Por qué los eventos de Sentry desaparecen silenciosamente en Webflow Cloud?

Los fallos silenciosos son la parte más frustrante de la configuración de Sentry. El SDK se inicializa, no aparecen errores en la consola, pero no se muestra nada en el panel de control. Casi todos los casos se deben a cinco causas.

Revisa estos puntos en orden. Los dos primeros explican la mayoría de los casos.

Eventos capturados pero no enviados

Si omitiste tunnelRoute o lo configuraste incorrectamente en next.config.ts, el SDK de Sentry capturará los errores en la memoria pero no podrá enviarlos debido a la restricción de fecha de compatibilidad de Webflow Cloud.

Confirma que tunnelRoute: "/sentry-tunnel" esté configurado en las opciones de withSentryConfig, vuelve a desplegar y prueba de nuevo.

Falta la variable de entorno DSN en producción

NEXT_PUBLIC_SENTRY_DSN Debe añadirse al panel de entorno de Webflow Cloud. .env.local solo se aplica localmente. Si falta el DSN, el SDK se desactiva silenciosamente sin lanzar ningún error.

Comprueba que la variable esté presente en Webflow Cloud → Variables de entorno y, a continuación, vuelve a desplegar.

Los mapas de origen se suben localmente, pero los seguimientos de pila siguen estando minificados en producción

La carga de mapas de origen requiere que SENTRY_AUTH_TOKEN esté configurado tanto localmente (para despliegues manuales) como en tu entorno de CI. Si la carga tiene éxito localmente pero falla en CI, el despliegue en producción no tendrá mapas de origen.

Configura el token como un secreto de GitHub Actions y verifica que los registros del paso de carga muestren Successfully uploaded N source maps en la salida del despliegue.

Seguimientos que muestran una duración de cero para operaciones vinculadas a la CPU

Este es el comportamiento esperado en Cloudflare Workers. performance.now() y Date.now() solo avanzan después de que se produzca una E/S, una medida de seguridad para evitar ataques de temporización. Los tramos que solo usan CPU siempre mostrarán una duración de cero.

Esto no es una mala configuración de Sentry; es una restricción de la plataforma Workers. Las operaciones vinculadas a E/S (consultas a bases de datos, llamadas a API externas) se rastrean correctamente.

La repetición de sesión no se está grabando

La repetición de sesión solo se ejecuta en instrumentation-client.ts, la configuración del navegador. Confirma que el archivo existe en la raíz de tu proyecto, que Sentry se inicializa sin errores en la consola del navegador y que replaysSessionSampleRate es superior a 0.

En 0.1, las repeticiones se graban solo para el 10% de las sesiones; súbelo a 1.0 temporalmente si estás probando con poco tráfico para verificar que funciona.

Qué hacer después de que Sentry esté funcionando en tu Webflow Cloud App

Con Sentry en marcha, tienes visibilidad total de cada capa de una Webflow Cloud App: errores del navegador, errores del entorno de ejecución en el borde (edge) de los Route Handlers, fallos en los Server Components y repeticiones de sesión para depurar problemas reportados por los usuarios.

Explora Webflow + Sentry para obtener detalles sobre lo que cubre la integración de Sentry en todo el ecosistema de Webflow.