Cómo añadir el seguimiento de errores de Sentry a una aplicación de Webflow Cloud y dejar de trabajar a ciegas en producción

La observabilidad en producción es una tarea distinta al despliegue, y en Webflow Cloud, añadir Sentry es la forma más directa de conseguirla. La integración funciona perfectamente tanto para Next.js como para Astro, con un detalle de configuración que determina si los eventos de error llegan realmente.

El entorno de ejecución de Cloudflare Workers sobre el que corre Webflow Cloud tiene un requisito poco evidente para que Sentry pueda enviar eventos de error: una compatibility_date de 2025-08-16 o posterior en tu wrangler.jsonc.

Sin esto, Sentry se inicializa correctamente, tu panel no muestra errores y no tienes forma de saber si es porque no ha ocurrido nada o porque no se está capturando nada. La mayoría de las configuraciones omiten esto.

Esta guía cubre la configuración completa de Sentry para Webflow Cloud: el SDK correcto para Next.js o Astro, el almacenamiento seguro de tu DSN en el panel de variables de entorno de Webflow Cloud y el wrangler.jsonc cambio que hace que los eventos lleguen realmente.

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

Necesitas un despliegue activo en Webflow Cloud, una cuenta de Sentry con un DSN de proyecto y una copia local de tu aplicación con acceso de envío (push) a GitHub. No se requiere ninguna cuenta adicional de Cloudflare, middleware de terceros ni actualizar tu plan de Webflow.

Aquí tienes el desglose completo antes de empezar.

Un proyecto activo en Webflow Cloud

Tu aplicación debe estar desplegada en Webflow Cloud, ya sea creada mediante la CLI de Webflow o importada como tu propia aplicación. Webflow Cloud es compatible con Next.js (versión 15 o superior) y Astro. Si aún no lo has configurado, hazlo antes de continuar.

Webflow Cloud realiza despliegues desde una rama de GitHub que vinculas durante la configuración del proyecto. Si has completado la configuración de la CLI o has importado tu propia aplicación, tu proyecto tendrá al menos un entorno (normalmente production) con un ID de despliegue al que puedes hacer referencia en el panel de entornos.

Si aún no has realizado ningún despliegue, la guía de inicio de Webflow Cloud te explica cómo crear tu primer proyecto desde la CLI. Vuelve aquí una vez que tengas un despliegue activo. Sentry necesita un entorno de ejecución real al que enviar eventos, y las configuraciones locales no completarán el paso de verificación del paso 5.

Una cuenta y un proyecto de Sentry

Crea una cuenta gratuita en sentry.io si aún no tienes una.

Una vez que hayas iniciado sesión, crea un nuevo proyecto y selecciona la plataforma que coincida con tu framework: Next.js para una aplicación de Next.js, o Cloudflare para una aplicación de Astro en Cloudflare. La plataforma determina qué SDK recomienda Sentry y qué instrucciones de configuración muestra.

El DSN de tu proyecto es la cadena que Sentry utiliza para dirigir los eventos de error. Tiene este aspecto:

https://abc123xyz@o12345.ingest.sentry.io/9876543

Necesitarás esta cadena en el paso 3.

Acceso a GitHub y una copia local de tu aplicación

Webflow Cloud realiza despliegues desde GitHub automáticamente con cada envío (push) a la rama vinculada. Asegúrate de que tu repositorio local esté actualizado con la rama desplegada antes de empezar.

Webflow Cloud se conecta a GitHub mediante la aplicación de GitHub de Webflow Cloud, la cual autorizas durante la configuración del proyecto. Cuando haces un push a la rama vinculada, Webflow Cloud detecta el cambio e inicia una compilación automáticamente. No se requiere ningún paso de despliegue manual.

Node.js 20.0.0+ y npm

Necesarios para instalar los paquetes de Sentry. Actualmente, Webflow Cloud solo admite el npm gestor de paquetes para las dependencias del proyecto.

Node.js 20 es el mínimo requerido porque los paquetes del SDK de Sentry utilizan APIs de Node.js que no están disponibles en versiones LTS anteriores. Puedes verificar tu versión actual ejecutando node --version en tu terminal. Si tienes una versión inferior a la 20, instala la última versión LTS desde nodejs.org o utiliza un gestor de versiones como nvm para cambiar de versión.

npm viene incluido con Node.js, por lo que al actualizar Node.js también se actualiza npm. El entorno de compilación de Webflow Cloud utiliza Node.js 20 de forma predeterminada; hacer coincidir tu versión local evita discrepancias en la resolución de dependencias entre las instalaciones locales y la compilación en la nube.

Una vez que todo esté listo, la configuración completa toma entre 20 y 30 minutos, dependiendo de tu framework.

5 pasos para añadir el seguimiento de errores de Sentry a una aplicación de Webflow Cloud

La configuración se divide en dos rutas (Next.js y Astro) porque cada framework requiere paquetes de SDK y archivos de configuración diferentes.

Los conceptos básicos son los mismos: instalar el SDK, configurarlo para que lea el DSN desde una variable de entorno, almacenar esa variable en el panel de control de Webflow Cloud y confirmar la fecha de compatibilidad del entorno de ejecución de Workers.

Algo importante que debes saber antes de empezar: Webflow Cloud inyecta las variables de entorno solo en tiempo de ejecución, no durante la compilación. Cualquier código que lea process.env.SENTRY_DSN durante la compilación (incluidas las comprobaciones de validación de nivel superior) hará que la compilación falle, incluso si la variable está configurada correctamente.

Los pasos a continuación están redactados para evitar esto.

1. Instala el/los SDK de Sentry para tu framework

El SDK de Sentry que instales depende de tu framework. Next.js utiliza un único paquete que gestiona el seguimiento tanto del lado del cliente como del servidor.

Astro requiere dos:

• Uno para el seguimiento del lado del cliente a través del proceso de compilación de Astro
• Uno para el seguimiento del lado del servidor a través del entorno de ejecución de Cloudflare Workers

Instalar el paquete incorrecto (o solo uno de los dos en el caso de Astro) es el error de configuración más común.

Antes de ejecutar el comando de instalación, asegúrate de estar en la raíz de tu proyecto local y de que tu terminal apunte al directorio correcto. Todos los paquetes se instalan en el node_modules de la raíz del proyecto y deberían aparecer en package.json bajo dependencies, no en devDependencies.

Instala el paquete que corresponda a tu framework.

Para Next.js:

npm install @sentry/nextjs --save

Este paquete único gestiona el seguimiento del lado del cliente (navegador), del lado del servidor y en el borde (edge). En el paso 2, crearás archivos de inicialización separados para cada entorno.

@sentry/nextjs está diseñado específicamente para Next.js e incluye instrumentación para App Router, compatibilidad con el entorno de ejecución edge e integración de mapas de origen. Es el paquete correcto y completo para una aplicación Next.js en Webflow Cloud.

Para Astro:

Astro en Webflow Cloud requiere dos paquetes: uno para el seguimiento del lado del cliente y mapas de origen, y otro para el seguimiento del entorno de ejecución edge del lado del servidor:

npx astro add @sentry/astro
npm install @sentry/cloudflare --save

@sentry/astro gestiona la captura de errores del lado del cliente y se integra con la canalización de compilación de Astro para los mapas de origen. @sentry/cloudflare gestiona el seguimiento de errores del lado del servidor mediante el middleware de Cloudflare Pages. Ambos son necesarios para una cobertura completa.

Tras la instalación, verifica que ambos paquetes aparezcan en package.json bajo dependencies.

Los paquetes de Sentry correctos para tu framework aparecen en package.json bajo dependencies.

2. Crea los archivos de configuración de Sentry

Los archivos de configuración de Sentry le indican al SDK cómo inicializarse, qué DSN utilizar y cómo conectarse a la canalización de errores de tu framework.

Los archivos exactos dependen de tu framework: Next.js necesita tres archivos para cubrir el entorno de ejecución edge, el entorno de ejecución del servidor y el hook de errores de solicitud. Astro necesita un archivo de configuración de cliente, una entrada de configuración en astro.config.mjs y un archivo de middleware para la cobertura del lado del servidor.

Todos los archivos de configuración leen el DSN desde una variable de entorno, nunca codificada de forma rígida. La variable aún no está disponible (la añadirás en el paso 3), pero hacer que la configuración la referencie por su nombre ahora significa que solo tendrás que establecerla una vez en el panel de control de Webflow Cloud para que se aplique a los tres archivos.

Aquí tienes la configuración completa para cada framework.

Para Next.js (App Router):

Crea cuatro archivos en la raíz del proyecto:

• instrumentation-client.ts: Captura de errores del lado del navegador
• instrumentation.ts: Registra las configuraciones del servidor y edge con Next.js
• sentry.server.config.ts: Inicialización del lado del servidor (entorno de ejecución Node.js)
• sentry.edge.config.ts: Inicialización del entorno de ejecución edge

Webflow Cloud despliega Next.js a través del adaptador OpenNext Cloudflare, que utiliza el entorno de ejecución Node.js de Next.js. En producción, NEXT_RUNTIME se evalúa como "nodejs", lo que significa que sentry.server.config.ts es la configuración activa del lado del servidor.

La configuración sentry.edge.config.ts se incluye para mayor completitud, pero no será la ruta activa en Webflow Cloud.

Cada archivo cumple una función distinta en la cadena de inicialización.

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, middleware, and proxies
export const onRequestError = Sentry.captureRequestError;

sentry.edge.config.ts:

import * as Sentry from "@sentry/nextjs";

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  tracesSampleRate: 1.0,
  enableLogs: true,
});

sentry.server.config.ts:

import * as Sentry from "@sentry/nextjs";

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  tracesSampleRate: 1.0,
  enableLogs: true,
});

Next.js invoca register() en ambos entornos de ejecución al iniciar. La protección NEXT_RUNTIME garantiza que cada archivo de configuración se cargue solo en su entorno de destino. La exportación onRequestError es la que se conecta a la canalización de errores de solicitud de Next.js. Sin ella, los errores de los Server Components y las rutas de API se capturan con menos fiabilidad.

If you ran Sentry's wizard: The wizard adds withSentryConfig to next.config.ts, which expects SENTRY_AUTH_TOKEN at build time for source map upload. If you skip adding this token, your first push will fail with a build error. Either add SENTRY_AUTH_TOKEN as an environment variable in Webflow Cloud (Step 3), or remove withSentryConfig from next.config.ts to get basic error tracking working first — source map upload can be added later.

instrumentation-client.ts:

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

Sentry.init({
  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
  tracesSampleRate: 1.0,
  enableLogs: true,
});

Para Astro:

La configuración de Astro tiene dos partes: registrar la integración @sentry/astro en astro.config.mjs para el seguimiento del lado del cliente, y añadir el middleware @sentry/cloudflare para el seguimiento del lado del servidor.

Primero, añade la integración de Sentry a astro.config.mjs junto con el adaptador de Cloudflare:

// astro.config.mjs
import { defineConfig } from "astro/config";
import cloudflare from "@astrojs/cloudflare";
import sentry from "@sentry/astro";

export default defineConfig({
  adapter: cloudflare(),
  integrations: [sentry()],
});

Luego, crea un archivo sentry.client.config.ts en la raíz del proyecto para la inicialización del lado del cliente:

// sentry.client.config.ts
import * as Sentry from "@sentry/astro";

Sentry.init({
  dsn: import.meta.env.PUBLIC_SENTRY_DSN,
  tracesSampleRate: 1.0,
  enableLogs: true,
});

Finalmente, crea functions/_middleware.ts en la raíz del proyecto para el seguimiento del lado del servidor:

// functions/_middleware.ts
import * as Sentry from "@sentry/cloudflare";

export const onRequest = [
  // Sentry must be the first middleware in the array
  Sentry.sentryPagesPlugin((context) => ({
    dsn: context.env.SENTRY_DSN,
    tracesSampleRate: 1.0,
    enableLogs: true,
  })),
];

Dos nombres de variables DSN para Astro: La configuración del lado del cliente (sentry.client.config.ts) accede al DSN mediante import.meta.env.PUBLIC_SENTRY_DSN — el prefijo PUBLIC_ hace que la variable esté disponible en el navegador.

La configuración del lado del servidor (functions/_middleware.ts) accede a él mediante context.env.SENTRY_DSN. Tendrás que añadir tanto PUBLIC_SENTRY_DSN como SENTRY_DSN como variables de entorno en Webflow Cloud en el paso 3.

Resultado esperado: Los archivos de configuración existen en tu proyecto y hacen referencia al DSN de Sentry solo a través de una variable de entorno; nada de cadenas codificadas directamente.

3. Añade tu DSN de Sentry como secreto en Webflow Cloud

Tu DSN debe estar disponible en tiempo de ejecución como una variable de entorno. Webflow Cloud inyecta las variables de entorno solo en tiempo de ejecución; no son accesibles durante el proceso de compilación.

Abre tu sitio de Webflow, navega a Site Settings y selecciona Webflow Cloud en la barra lateral.

Haz clic en el nombre de tu proyecto para abrir el Environments Dashboard, luego haz clic en el nombre de tu entorno para abrir el Deployment Dashboard. Selecciona la pestaña Environment Variables y haz clic en Add variable.

Para Next.js, añade dos variables:

• Nombre de la variable: SENTRY_DSN | Valor: tu cadena DSN completa | Habilita Secret (usado por las configuraciones de servidor y edge)
• Nombre de la variable: NEXT_PUBLIC_SENTRY_DSN | Valor: tu cadena DSN completa | Habilita Secret (usado por la configuración del cliente; el prefijo NEXT_PUBLIC_ lo expone al navegador)

Para Astro, añade dos variables:

• Nombre de la variable: SENTRY_DSN | Valor: tu DSN | Habilita Secret
• Nombre de la variable: PUBLIC_SENTRY_DSN | Valor: tu DSN | Habilita Secret (esta es pública, pero ocultarla en el panel evita que se exponga accidentalmente en los registros)

Resultado esperado: Las variables requeridas aparecen en la lista de Environment Variables con valores ocultos.

Atajo de importación masiva: En la pestaña Environment Variables, haz clic en Add variable > Bulk import para arrastrar un archivo .env . Webflow Cloud marca automáticamente las variables que terminan en _DSN, _KEY, o _TOKEN como candidatas a secreto.

4. Actualiza tu wrangler.jsonc local

Webflow Cloud genera automáticamente un wrangler.json de producción al momento de la implementación. No puedes editarlo directamente. Para el desarrollo local y la vista previa de Wrangler, crea o actualiza tu wrangler.jsonc en la raíz del proyecto:

// wrangler.jsonc
{
  // nodejs_compat is automatically applied by Webflow Cloud in production.
  // Include here so local previews match production behavior.
  "compatibility_flags": ["nodejs_compat"],
  // Required for Sentry — introduces https.request to the Workers runtime,
  // which Sentry needs to deliver events to sentry.io.
  "compatibility_date": "2025-08-16"
}

La línea "compatibility_date": "2025-08-16" es el cambio fundamental. Sentry utiliza https.request para enviar eventos, y Cloudflare introdujo esa API en esta fecha de compatibilidad. Las fechas anteriores o la omisión de este dato provocan que Sentry se inicie silenciosamente, pero los eventos nunca llegan a tu panel de control de Sentry.

Test locally before pushing: Run npm run preview (the Wrangler preview command configured by the Webflow CLI) to serve your app locally against the Workers runtime. Navigate to your debug route (localhost:PORT/your-mount-path/debug-sentry) and check whether the error appears in Sentry. If it does locally but not after deploying, the issue is Webflow Cloud's production compatibility date. If it doesn't appear locally either, the issue is your wrangler.jsonc config or the DSN value itself.

Nota sobre la configuración de wrangler de producción de Webflow Cloud: Webflow Cloud gestiona la configuración de wrangler de producción, por lo que no puedes inspeccionarla ni editarla directamente. El wrangler.jsonc que creas se aplica únicamente al desarrollo local.

Si los eventos aparecen en la vista previa local de Wrangler pero no en la aplicación implementada, es posible que la fecha de compatibilidad de producción de Webflow Cloud sea anterior a 2025-08-16.

Resultado esperado: wrangler.jsonc el nodejs_compat en la raíz del proyecto contiene tanto "compatibility_date": "2025-08-16" como una fecha posterior.

5. Envía a GitHub y verifica los eventos en Sentry

Confirma y envía tus cambios a la rama de GitHub vinculada a tu entorno de Webflow Cloud:

git add .
git commit -m "add Sentry error tracking"
git push origin main

Webflow Cloud detecta el envío e inicia automáticamente una implementación. En Webflow Cloud, haz clic en el nombre de tu proyecto para abrir el Panel de Entornos, haz clic en el nombre de tu entorno para abrir el Panel de Implementación y, a continuación, haz clic en el ID de implementación (SHA de confirmación) para supervisar los registros de compilación en tiempo real.

Una vez completada la implementación, añade una ruta de prueba temporal para confirmar que Sentry está recibiendo eventos:

Next.js (App Router):

// app/debug-sentry/route.ts
export async function GET() {
  throw new Error("Sentry test error from Webflow Cloud");
}

Astro:

// src/pages/api/debug-sentry.ts
export const prerender = false;

export async function GET() {
  throw new Error("Sentry test error from Webflow Cloud");
}

Tu ruta de montaje es la que configuraste al crear tu entorno de Webflow Cloud. Por ejemplo, si tu ruta de montaje es /app, la URL es yoursite.webflow.io/app/debug-sentry.

Navega a yoursite.webflow.io/your-mount-path/debug-sentry (o /api/debug-sentry para Astro). En unos segundos, el error debería aparecer en la pestaña Issues de tu proyecto de Sentry.

Resultado esperado: El error de prueba aparece en la lista de Issues de Sentry con un seguimiento de pila y el contexto de la solicitud. Una vez confirmado, elimina la ruta de prueba y vuelve a realizar el envío. No dejes esta ruta en producción. Elimínala y realiza el envío antes de publicar.

¿Qué hace que Sentry falle en Webflow Cloud?

Las categorías de error más comunes son la falta de una fecha de compatibilidad, la sincronización de las variables de entorno y una limitación de rastreo conocida en el tiempo de ejecución de Workers. La mayoría de estos fallos son silenciosos: Sentry se inicia sin errores, pero los eventos nunca aparecen en tu panel de control.

Known issue (as of Q1 2026): Sentry's server-side integration with Next.js on OpenNext/Cloudflare Workers has known compatibility issues currently being tracked in sentry-javascript #18842. If you encounter AsyncLocalStorage errors or "Server failed to respond" after adding server-side Sentry, try removing sentry.server.config.ts and sentry.edge.config.ts temporarily — client-side tracking via instrumentation-client.ts and withSentryConfig in next.config.ts will still function. Monitor the linked issue for resolution status.

Aquí te explicamos cómo identificar a qué fallo te enfrentas y cómo solucionarlo.

Los eventos se inician pero nunca aparecen en los Issues de Sentry

Causa: "compatibility_date" el wrangler.jsonc en 2025-08-16 es anterior a .request o no existe. Sentry se inicia sin errores, pero no puede enviar eventos a través de HTTPS porque no está disponible en fechas anteriores.

Solución: Abre wrangler.jsonc y confirma que "compatibility_date": "2025-08-16" o una versión posterior esté configurada. Envía un nuevo commit para volver a desplegar. Si los eventos aparecen en la vista previa local de Wrangler pero no en la aplicación desplegada, contacta al soporte de Webflow, ya que la fecha de compatibilidad de producción de Webflow Cloud podría ser anterior a tu configuración local.

SENTRY_DSN is undefineden los registros de tiempo de ejecución

Causa: La variable no se guardó, el nombre de la clave está mal escrito o estás consultando las variables de un entorno diferente. Webflow Cloud solo inyecta variables de entorno durante la ejecución, no durante la compilación.

Solución: En el panel de control de Webflow Cloud, navega a tu entorno → Variables de entorno y confirma que el nombre de la variable esté escrito exactamente igual (distingue entre mayúsculas y minúsculas). Para Astro, confirma que tanto SENTRY_DSN como PUBLIC_SENTRY_DSN estén presentes. Haz clic en Editar para verificar que la cadena DSN comience con https://. Después de guardar, envía un nuevo commit para volver a desplegar.

Nota:No verifiques SENTRY_DSN durante el tiempo de compilación a nivel de módulo. Cualquier verificación de nivel superior, como if (!process.env.SENTRY_DSN) throw new Error(...), hará que la compilación de Webflow Cloud falle, incluso si la variable está configurada correctamente en tiempo de ejecución.

Los tramos del lado del servidor muestran una duración de 0ms

Causa: Este es el comportamiento esperado, no un error de configuración. El tiempo de ejecución de Cloudflare Workers impide que performance.now() y Date.now() avancen durante operaciones que solo utilizan CPU, como medida de seguridad contra ataques de temporización. Esto afecta a todos los frameworks desplegados en Cloudflare Workers.

Solución: No hay solución. El rastreo del lado del cliente desde el navegador muestra tiempos precisos. Para obtener contexto de tiempo del lado del servidor, utiliza registros estructurados con marcas de tiempo manuales.

Los errores de las rutas de API y los componentes de servidor de Next.js no se capturan

Causa: Las aplicaciones Next.js de Webflow Cloud se ejecutan en el entorno de Node.js a través del adaptador OpenNext Cloudflare: NEXT_RUNTIME se evalúa como "nodejs" en producción. Si sentry.server.config.ts no se carga correctamente o si falta onRequestError en instrumentation.ts, los errores de los componentes de servidor y las rutas de API no se capturarán.

Solución: Confirma que instrumentation.ts exporte onRequestError = Sentry.captureRequestError y que el bloque NEXT_RUNTIME === "nodejs" importe correctamente ./sentry.server.config. Además, confirma que SENTRY_DSN esté configurado en el panel de variables de entorno de Webflow Cloud y que el despliegue se haya completado después de añadirlo.

La compilación falla tras añadir Sentry a Next.js

Causa: El asistente de Sentry añade withSentryConfig a next.config.ts, que espera SENTRY_AUTH_TOKEN durante la compilación para cargar los mapas de origen. Si falta este token, la compilación falla.

Solución: Añade SENTRY_AUTH_TOKEN como variable de entorno en Webflow Cloud, o elimina temporalmente withSentryConfig de next.config.ts para que el seguimiento básico de errores funcione primero. La carga de mapas de origen es opcional para la configuración inicial.

Qué instrumentar a continuación

El seguimiento de errores es la base.

Una vez que Sentry reciba eventos, vale la pena añadir tres cosas antes de considerar que la configuración está lista para producción:

• Mapas de origen: Sin ellos, Sentry muestra seguimientos de pila minificados difíciles de leer. Añade withSentryConfig a next.config.ts (Next.js) o configura la carga de mapas de origen en @sentry/astro (Astro), luego añade SENTRY_AUTH_TOKEN como variable de entorno en Webflow Cloud.
• Seguimiento de versiones: Etiqueta cada versión de Sentry con el SHA del commit de GitHub de tu despliegue en Webflow Cloud. Esto vincula los errores a despliegues específicos y facilita el seguimiento de regresiones.
• Monitoreo de rendimiento: tracesSampleRate: 1.0 captura el 100% de las transacciones en desarrollo, pero los sitios en producción deberían reducir esta cifra (0.1–0.2 es lo habitual) para evitar alcanzar los límites de cuota de Sentry.

Explora Webflow + Sentry para límites de error personalizados, rastreo distribuido entre servicios y la referencia completa de configuración de Webflow Cloud.