Docs

Next.js

Una sola configuración de @sypnia/next cubre el navegador y el servidor de una app Next.js, en el App Router y en el Pages Router, y sube los source maps cuando compilas.

Aplica a MotorNube Al lanzar

Ver como Markdown
En esta página
  1. Instalar
  2. Configurar
  3. Envuelve tu configuración de Next.js
  4. Enciende el servidor
  5. Enciende el navegador
  6. Córrela y mira
  7. Qué obtienes
  8. Errores que muestra un límite de errores
  9. Identificar personas
  10. withSypnia(nextConfig, options)
  11. Source maps al compilar
  12. Sigue con

Esta página es para quien corre una app Next.js. @sypnia/next es el SDK del navegador y el SDK de Node configurados juntos, más lo que es propio de Next.js: la navegación del App Router, los errores lanzados en el servidor y los source maps. Tiene licencia MIT y es idéntico para el motor de código abierto y para Sypnia Cloud.

Al final tendrás: sesiones, grabaciones y rendimiento de páginas desde el navegador, cada petición al servidor trazada, los errores del servidor unidos a la página que los mostró, y pilas que apuntan a tus propios archivos.

Necesitas: Next.js 15.3 o más nuevo.

Instalar

npm

npm install @sypnia/next

Configurar

Tres archivos pequeños. La configuración vive en el primero; los otros dos solo encienden Sypnia, en el servidor y en el navegador. Pon los dos archivos de instrumentación junto a app/ o pages/: en la raíz del proyecto, o en src/ si la usas.

  1. Envuelve tu configuración de Next.js

    Sypnia Cloud

    next.config.ts
    import type { NextConfig } from 'next';
    import { withSypnia } from '@sypnia/next';
    
    const nextConfig: NextConfig = {};
    
    export default withSypnia(nextConfig, {
      project: process.env.SYPNIA_PROJECT_KEY,
      service: 'shop-web',
    });
    .env.local
    SYPNIA_PROJECT_KEY=spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e

    withSypnia lee estos valores cuando Next.js compila y se los da a los dos lados de tu app, así que los escribes una vez. La llave de ingesta es pública: está hecha para terminar en el paquete del navegador.

  2. Enciende el servidor

    instrumentation.ts
    export { register, onRequestError } from '@sypnia/next/server';
  3. Enciende el navegador

    instrumentation-client.ts
    import { init } from '@sypnia/next/client';
    
    init();
    
    export { onRouterTransitionStart } from '@sypnia/next/client';

    init() toma sus valores de withSypnia. También acepta cualquier opción del navegador, por ejemplo init({ maskAllText: true }).

  4. Córrela y mira

    Corre next dev, abre una página y haz clic en un enlace. En la pestaña Network del navegador, filtra por ingest.

    Deberías ver
    Un POST a …/v1/ingest/events respondido con 200, en menos de 10 segundos. Con debug: true en withSypnia, la terminal también imprime un server_request por cada petición que atendió el servidor.

Qué obtienes

LadoCubreNotas
NavegadorTodo lo que captura el SDK del navegador.Las navegaciones del App Router las reporta Next.js mismo con onRouterTransitionStart; el Pages Router se sigue con la History API. Ambas son vistas de página.
Servidor, App RouterPáginas y layouts que se pintan, Route Handlers, Server Actions.Un server_request por cada uno, con la ruta como la nombra Next.js (/orders/[id]).
Servidor, Pages RouterPáginas con getServerSideProps, rutas de API bajo pages/api.Lo mismo.
Llamadas salientesfetch, http, pg, Supabase y PostgREST, como en el SDK de Node.Spans bajo la petición.
Errores del servidorTodo error que Next.js captura en el servidor, con onRequestError.Con el digest que Next.js le da.
TrazaLa llamada del navegador y la petición del servidor comparten un id de traza.Nada que configurar para llamadas a tu propia app.

No se cubre al lanzar: el código que corre en el runtime Edge (rutas con export const runtime = 'edge', y el middleware). Ni se traza ni se reportan sus errores. Planeado

Si tu app ya registra OpenTelemetry en instrumentation.ts (por ejemplo con @vercel/otel), no agregues encima el register de Sypnia. Conserva tu configuración, apunta su exportador a la entrada OTLP, y usa @sypnia/next para el lado del navegador y para onRequestError.

Errores que muestra un límite de errores

Cuando un Server Component lanza un error, Next.js muestra tu error.tsx y le oculta el mensaje real al navegador. Les da a los dos lados el mismo digest. Reporta el error desde el límite con ese digest, y Sypnia une la página que vio la persona con el error del servidor y su pila.

app/error.tsx
'use client';

import { useEffect } from 'react';
import { reportError } from '@sypnia/next/client';

export default function Error({ error, reset }: { error: Error & { digest?: string }; reset: () => void }) {
  useEffect(() => {
    reportError(error, { source: 'boundary', digest: error.digest });
  }, [error]);

  return (
    <div>
      <p>Algo salió mal.</p>
      <button onClick={reset}>Intentar de nuevo</button>
    </div>
  );
}

Haz lo mismo en app/global-error.tsx si lo tienes. En el Pages Router no hay nada que agregar: los errores al pintar en el navegador llegan a la ventana y se reportan.

Identificar personas

En el navegador, desde un Client Component que conoce a la persona que inició sesión:

app/identify.tsx
'use client';

import { useEffect } from 'react';
import { identify } from '@sypnia/next/client';

export function Identify({ id, name, email }: { id: string; name?: string; email?: string }) {
  useEffect(() => {
    identify({ person: { id, name, email } });
  }, [id, name, email]);
  return null;
}

Píntalo en tu layout raíz cuando alguien haya iniciado sesión. En el servidor no necesitas identificar las peticiones que vienen de ese navegador. Mira Identificar personas.

withSypnia(nextConfig, options)

OpciónTipoPor defectoQué hace
projectstringprocess.env.SYPNIA_PROJECT_KEYLa llave de ingesta, spk_…. Sin ella la compilación imprime un aviso y Sypnia queda apagado.
endpointstringprocess.env.SYPNIA_ENDPOINT, si no 'https://ingest.sypnia.com'A dónde enviar. La URL base de un motor con alojamiento propio.
servicestringprocess.env.SYPNIA_SERVICE, si no 'next'El nombre del lado del servidor en las trazas.
environmentstringprocess.env.SYPNIA_ENVIRONMENT, si no process.env.VERCEL_ENV, si no 'development' bajo next dev y 'production' en lo demásEl entorno, el mismo para los dos lados.
releasestringprocess.env.SYPNIA_RELEASE, si no los primeros 7 caracteres de process.env.VERCEL_GIT_COMMIT_SHA, si no git rev-parse --short HEAD, si no ningunoLa versión (release), la misma para los dos lados y para los source maps.
debugbooleanfalseImprime cada evento, en la consola del navegador y en la salida del servidor.
sourceMapsbooleantrueSube los source maps cuando compilas. Mira abajo.
apiUrlstringprocess.env.SYPNIA_BASE_URL, si no 'https://api.sypnia.com'A dónde se suben los source maps. La URL base de un motor con alojamiento propio.
serveropciones del SDK de Node{}Cualquier opción del SDK de Node salvo las de arriba, por ejemplo { ignoreRoutes: ['/api/health'] }.

Las opciones solo del navegador van en init(), en instrumentation-client.ts.

Source maps al compilar

Una compilación de producción con SYPNIA_API_TOKEN en su entorno hace cuatro cosas, en orden:

  1. Enciende los source maps de los paquetes del navegador.
  2. Registra la versión (release), con el commit cuando git puede decirlo.
  3. Sube cada source map de esa versión.
  4. Borra los archivos .map de la salida de la compilación, para que nunca se publiquen.
Entorno de compilación
SYPNIA_PROJECT_KEY=spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e
SYPNIA_API_TOKEN=sps_4Kq9Zt2MxV7bN1cR5wY8pL3dF6hJ0sA2gE4uT9iO

El token es un token de API con el permiso admin. Es un secreto: ponlo en tu CI o en los ajustes de compilación de tu proveedor, nunca en el código y nunca en una variable que empiece por NEXT_PUBLIC_.

Deberías ver
Al final de next build: Sypnia: release 4f2a91c registered, 312 source maps uploaded, 312 removed from the build output.

La subida nunca hace fallar tu compilación. Sin el token imprime Sypnia: source maps not uploaded (SYPNIA_API_TOKEN is not set) y sigue; si la subida falla, dice por qué y sigue. Bajo next dev no se sube nada.

Los source maps de los paquetes del servidor están Planeado: al lanzar, la pila de un error del servidor muestra el archivo compilado. Su ruta, su traza y la página que lo mostró están ahí de todos modos.

Sigue con

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