Docs

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.

Aplica a MotorNube Al lanzar

Ver como Markdown
En esta página
  1. Agrega el paquete y los tres archivos
  2. Pon las variables en Vercel
  3. Despliega y lee el registro de la compilación
  4. Abre el despliegue
  5. Lo que Vercel le da a Sypnia por sí solo
  6. Funciones
  7. Visitantes con bloqueadores de anuncios
  8. Si la app ya usa OpenTelemetry
  9. Revisa todo

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.

  1. Agrega el paquete y los tres archivos

    Terminal
    npm install @sypnia/next
    next.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.

  2. Pon las variables en Vercel

    En tu proyecto de Vercel, abre los ajustes de variables de entorno y agrega:

    VariableValorEntornosSensible
    SYPNIA_PROJECT_KEYTu llave de ingesta, spk_…Production, Preview, DevelopmentNo. 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 motorTodosSolo con alojamiento propio.
    SYPNIA_BASE_URLLa URL base de tu motorLos mismos que el tokenSolo con alojamiento propio.

    No le pongas a ninguna el prefijo NEXT_PUBLIC_. withSypnia pasa las públicas al navegador por su cuenta, y el token nunca debe llegar ahí.

    Deberías ver
    Las variables aparecen en el proyecto. El siguiente despliegue las usa; los despliegues que ya existen no cambian.
  3. Despliega y lee el registro de la compilación

    Sube un commit, o vuelve a desplegar.

    Deberías ver
    Cerca 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ó.

  4. Abre el despliegue

    Abre tu dirección de producción, haz clic en varias cosas, y mira Sesiones en Sypnia con el entorno production.

    Deberías ver
    Tu sesión en menos de 10 minutos. En Trazas, las peticiones a tus Route Handlers y páginas, con sus llamadas salientes.

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:

SypniaSale deResultado
environmentVERCEL_ENVproduction para el despliegue de producción, preview para cada despliegue de vista previa, development bajo next dev y vercel dev.
releaseVERCEL_GIT_COMMIT_SHA, primeros 7 caracteresEl 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 entorno preview, aparte de producción.
  • Las vistas previas sí cuentan para el plan de Sypnia Cloud, como todo entorno. Si abres muchas, deja SYPNIA_PROJECT_KEY fuera 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:

next.config.ts
const nextConfig: NextConfig = {
  async rewrites() {
    return [{ source: '/_sy/:path*', destination: 'https://ingest.sypnia.com/:path*' }];
  },
};
instrumentation-client.ts
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:

Variables de entorno en Vercel
OTEL_EXPORTER_OTLP_ENDPOINT=https://ingest.sypnia.com/v1/otlp
OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e
instrumentation.ts
import { 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

RevisaDóndeDeberías ver
El navegador envíaPestaña Network, filtro ingest (o _sy)POST …/v1/ingest/events, 200
El servidor envíaSypnia, Trazas, entorno productionTus rutas, con spans
La versión está puestaCualquier sesiónVersión 4f2a91c, el commit desplegado
Los source maps aplicanLa pila del siguiente problemasrc/checkout/checkout.tsx:142, no …-3f9c.js:1:48211
Las vistas previas están aparteEntorno previewSolo sesiones de direcciones de vista previa

Secciones

Empieza aquíQué es Sypnia, cómo funciona, qué es código abierto y qué es la nube de pago, y las dos maneras de recibir tu primer problema en palabras claras.ConceptosLas diez ideas de las que está hecho Sypnia, cada una definida con precisión, desde un proyecto y sus llaves hasta los problemas, las trazas y las alertas.SDKCómo envía tu app los datos a Sypnia. Un SDK para el navegador, uno para Node, uno para Next.js, y la entrada de OpenTelemetry para cualquier otro backend.El agenteCómo analiza Sypnia un problema, qué escribe, qué le envía a un modelo y qué nunca hace.MCP y skillsConecta tu agente de código a Sypnia para que pregunte qué está fallando en producción, lea lo que necesita para arreglarlo y configure Sypnia por ti.Referencia de la APILa API HTTP de Sypnia: una sola API para el motor de código abierto y para Sypnia Cloud, con cada endpoint, parámetro, respuesta y error.Referencia de la CLIEl comando sypnia: cómo instalarlo, qué variables lee, qué significan sus códigos de salida y dónde está documentado cada comando.Alojamiento propioQué corres cuando alojas tú mismo el motor de Sypnia, qué necesitas, cuánto cuesta y qué no tienes frente a Sypnia Cloud.Cómo está construido el motorTodo el motor de Sypnia en una página, desde un clic en tu app hasta la frase que lee tu agente de código, con las reglas de diseño y el código que las sostiene.Sypnia CloudCómo funciona el servicio pago, desde las organizaciones y los roles hasta los planes, los límites, la facturación, dónde viven tus datos, la GitHub App y el soporte.Privacidad y seguridadQué recoge Sypnia de tu app y de sus usuarios, qué no recoge nunca, cómo funciona el enmascarado, cómo eliminar datos y cómo se protege el servicio.LicenciasQué licencia cubre cada parte de Sypnia, qué puedes hacer con ella, cómo se puede usar el nombre, y los términos de una contribución.GuíasRecetas paso a paso para las formas comunes de usar Sypnia, desde apps hechas con constructores de IA y Next.js en Vercel hasta Supabase, source maps en CI, correos de alerta desde tu propio motor, y venir desde Sentry.ReferenciaLas páginas donde se consulta, desde el esquema de eventos y el glosario hasta lo planeado, el registro de cambios y las preguntas frecuentes.
↑↓ para moverte↵ para abrirEsc para cerrar