Next.js en Vercel
Configura @sypnia/next para una app desplegada en Vercel, con las variables de entorno, qué reportan los despliegues de vista previa, los source maps al compilar y la ruta para bloqueadores de anuncios.
Esta guía es para una app Next.js que Vercel compila y aloja. Aplica a Sypnia Cloud y a un motor con alojamiento propio; las variables que cambian están marcadas. Se apoya en Next.js, que tiene todas las opciones.
Al final tendrás: los despliegues de producción y de vista previa reportando a Sypnia en entornos separados, cada despliegue registrado como una versión (release) con sus source maps, y las peticiones al servidor trazadas dentro de las funciones de Vercel.
Necesitas: Next.js 15.3 o más nuevo, un proyecto de Sypnia con su llave de ingesta, y un token de API con el permiso admin para los source maps.
Agrega el paquete y los tres archivos
Terminal npm install @sypnia/nextnext.config.ts import type { NextConfig } from 'next'; import { withSypnia } from '@sypnia/next'; const nextConfig: NextConfig = {}; export default withSypnia(nextConfig, { service: 'shop-web' });instrumentation.ts export { register, onRequestError } from '@sypnia/next/server';instrumentation-client.ts import { init } from '@sypnia/next/client'; init(); export { onRouterTransitionStart } from '@sypnia/next/client';Nada más en el código: la llave, el entorno y la versión salen de variables.
Pon las variables en Vercel
En tu proyecto de Vercel, abre los ajustes de variables de entorno y agrega:
Variable Valor Entornos Sensible SYPNIA_PROJECT_KEYTu llave de ingesta, spk_…Production, Preview, Development No. Es pública. SYPNIA_API_TOKENUn token de API con admin,sps_…Production (y Preview, si quieres source maps ahí) Sí. Márcala como sensible. SYPNIA_ENDPOINTLa URL base de tu motor Todos Solo con alojamiento propio. SYPNIA_BASE_URLLa URL base de tu motor Los mismos que el token Solo con alojamiento propio. No le pongas a ninguna el prefijo
NEXT_PUBLIC_.withSypniapasa las públicas al navegador por su cuenta, y el token nunca debe llegar ahí.Deberías verLas variables aparecen en el proyecto. El siguiente despliegue las usa; los despliegues que ya existen no cambian.Despliega y lee el registro de la compilación
Sube un commit, o vuelve a desplegar.
Deberías verCerca del final del registro de la compilación:Sypnia: release 4f2a91c registered, 312 source maps uploaded, 312 removed from the build output.La versión son los primeros 7 caracteres del commit que Vercel compiló.Si dice
source maps not uploaded (SYPNIA_API_TOKEN is not set), el token falta en el entorno que se compiló.
Lo que Vercel le da a Sypnia por sí solo
withSypnia lee las variables propias de Vercel, así que no pones ninguno de estos valores:
| Sypnia | Sale de | Resultado |
|---|---|---|
environment | VERCEL_ENV | production para el despliegue de producción, preview para cada despliegue de vista previa, development bajo next dev y vercel dev. |
release | VERCEL_GIT_COMMIT_SHA, primeros 7 caracteres | El commit que se compiló, el mismo en el navegador, en el servidor y en los source maps. |
Esto necesita que «Automatically expose System Environment Variables» esté encendido en el proyecto, que es lo normal en Vercel; revisa la documentación actual de Vercel si release sale vacío.
Lo que esto significa en la práctica:
- Las vistas previas no te alertan. Las alertas y el resumen diario solo cubren
production. Un error que ves en una vista previa es un problema del entornopreview, aparte de producción. - Las vistas previas sí cuentan para el plan de Sypnia Cloud, como todo entorno. Si abres muchas, deja
SYPNIA_PROJECT_KEYfuera del entorno Preview para que queden en silencio. - Cada despliegue es una versión, así que un problema puede decir «desde el despliegue de las 18:40» y nombrar su commit.
Funciones
El código del servidor en Vercel corre en funciones que se congelan apenas se envía la respuesta. @sypnia/next envía los eventos de cada petición con el mecanismo que Next.js y Vercel ofrecen para trabajar después de la respuesta, así que trazar no agrega espera a tus respuestas y no pierde nada cuando la función se congela. No hay nada que configurar.
Dos límites al lanzar:
- Las rutas y el middleware en el runtime Edge no se trazan y sus errores no se reportan. Planeado
- Una función que Vercel detiene al llegar a su duración máxima no puede enviar su propio registro. Sypnia igual recibe el registro parcial escrito a los 20 segundos, con las llamadas que estaban en curso. Mira Trazas.
Visitantes con bloqueadores de anuncios
Envía por tu propio dominio para que las peticiones no se bloqueen por nombre de host. Agrega una reescritura y dile al lado del navegador que la use:
const nextConfig: NextConfig = {
async rewrites() {
return [{ source: '/_sy/:path*', destination: 'https://ingest.sypnia.com/:path*' }];
},
};init({ endpoint: '/_sy' });El lado del servidor sigue enviando directo a la ingesta. Con alojamiento propio, usa la URL base de tu motor como destino.
Si la app ya usa OpenTelemetry
Las apps que ya llaman a registerOTel de @vercel/otel en instrumentation.ts deberían conservarlo y enviar sus trazas a Sypnia con las variables estándar, en vez de agregar el register de Sypnia:
OTEL_EXPORTER_OTLP_ENDPOINT=https://ingest.sypnia.com/v1/otlp
OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2eimport { registerOTel } from '@vercel/otel';
export function register() {
registerOTel({ serviceName: 'shop-web' });
}
export { onRequestError } from '@sypnia/next/server';Deja instrumentation-client.ts como arriba. Mira OpenTelemetry para saber en qué se convierte cada span.
Revisa todo
| Revisa | Dónde | Deberías ver |
|---|---|---|
| El navegador envía | Pestaña Network, filtro ingest (o _sy) | POST …/v1/ingest/events, 200 |
| El servidor envía | Sypnia, Trazas, entorno production | Tus rutas, con spans |
| La versión está puesta | Cualquier sesión | Versión 4f2a91c, el commit desplegado |
| Los source maps aplican | La pila del siguiente problema | src/checkout/checkout.tsx:142, no …-3f9c.js:1:48211 |
| Las vistas previas están aparte | Entorno preview | Solo sesiones de direcciones de vista previa |