# 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: el motor de Sypnia (código abierto, en tu propia infraestructura) y Sypnia Cloud (servicio pago). Estado: al lanzar.  
Fuente: https://docs.sypnia.com/es/sdks/nextjs/

Esta página es para quien corre una app Next.js. `@sypnia/next` es el [SDK del navegador](https://docs.sypnia.com/es/sdks/browser) y el [SDK de Node](https://docs.sypnia.com/es/sdks/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**

```bash
npm install @sypnia/next
```

**pnpm**

```bash
pnpm add @sypnia/next
```

**yarn**

```bash
yarn add @sypnia/next
```

**bun**

```bash
bun add @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`

```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`

```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`

```bash
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`

```ts
export { register, onRequestError } from '@sypnia/next/server';
```

### 3. Enciende el navegador

`instrumentation-client.ts`

```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](https://docs.sypnia.com/es/sdks/browser), 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

| Lado                   | Cubre                                                                                                        | Notas                                                                                                                                                             |
| ---------------------- | ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Navegador              | Todo lo que captura el [SDK del navegador](https://docs.sypnia.com/es/sdks/browser).                         | 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](https://docs.sypnia.com/es/sdks/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](https://docs.sypnia.com/es/sdks/opentelemetry), 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`

```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`

```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](https://docs.sypnia.com/es/sdks/identifying-people).

## `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](https://docs.sypnia.com/es/sdks/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`

```bash
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
