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.
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/nextpnpm
pnpm add @sypnia/nextyarn
yarn add @sypnia/nextbun
bun add @sypnia/nextConfigurar
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.
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', });Alojamiento propio
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, endpoint: 'https://sypnia.example.com', service: 'shop-web', });.env.local SYPNIA_PROJECT_KEY=spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2ewithSypnialee 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.Enciende el navegador
instrumentation-client.ts import { init } from '@sypnia/next/client'; init(); export { onRouterTransitionStart } from '@sypnia/next/client';init()toma sus valores dewithSypnia. También acepta cualquier opción del navegador, por ejemploinit({ maskAllText: true }).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 poringest.Deberías verUnPOSTa…/v1/ingest/eventsrespondido con200, en menos de 10 segundos. Condebug: trueenwithSypnia, la terminal también imprime unserver_requestpor cada petición que atendió el servidor.
Qué obtienes
| Lado | Cubre | Notas |
|---|---|---|
| Navegador | Todo 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 Router | Pá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 Router | Páginas con getServerSideProps, rutas de API bajo pages/api. | Lo mismo. |
| Llamadas salientes | fetch, http, pg, Supabase y PostgREST, como en el SDK de Node. | Spans bajo la petición. |
| Errores del servidor | Todo error que Next.js captura en el servidor, con onRequestError. | Con el digest que Next.js le da. |
| Traza | La 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.
'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:
'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ón | Tipo | Por defecto | Qué hace |
|---|---|---|---|
project | string | process.env.SYPNIA_PROJECT_KEY | La llave de ingesta, spk_…. Sin ella la compilación imprime un aviso y Sypnia queda apagado. |
endpoint | string | process.env.SYPNIA_ENDPOINT, si no 'https://ingest.sypnia.com' | A dónde enviar. La URL base de un motor con alojamiento propio. |
service | string | process.env.SYPNIA_SERVICE, si no 'next' | El nombre del lado del servidor en las trazas. |
environment | string | process.env.SYPNIA_ENVIRONMENT, si no process.env.VERCEL_ENV, si no 'development' bajo next dev y 'production' en lo demás | El entorno, el mismo para los dos lados. |
release | string | process.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 ninguno | La versión (release), la misma para los dos lados y para los source maps. |
debug | boolean | false | Imprime cada evento, en la consola del navegador y en la salida del servidor. |
sourceMaps | boolean | true | Sube los source maps cuando compilas. Mira abajo. |
apiUrl | string | process.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. |
server | opciones 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:
- Enciende los source maps de los paquetes del navegador.
- Registra la versión (release), con el commit cuando git puede decirlo.
- Sube cada source map de esa versión.
- Borra los archivos
.mapde la salida de la compilación, para que nunca se publiquen.
SYPNIA_PROJECT_KEY=spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e
SYPNIA_API_TOKEN=sps_4Kq9Zt2MxV7bN1cR5wY8pL3dF6hJ0sA2gE4uT9iOEl 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_.
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
- Variables, despliegues de vista previa y source maps en Vercel.
- Qué nunca sale del navegador.
- No llega nada, bloqueadores de anuncios, source maps que no aplican.