# 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: 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/guides/nextjs-on-vercel/

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

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

`next.config.ts`

```ts
import type { NextConfig } from 'next';
import { withSypnia } from '@sypnia/next';

const nextConfig: NextConfig = {};

export default withSypnia(nextConfig, { service: 'shop-web' });
```

`instrumentation.ts`

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

`instrumentation-client.ts`

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

| Variable             | Valor                                | Entornos                                           | Sensible                       |
| -------------------- | ------------------------------------ | -------------------------------------------------- | ------------------------------ |
| `SYPNIA_PROJECT_KEY` | Tu llave de ingesta, `spk_…`         | Production, Preview, Development                   | No. Es pública.                |
| `SYPNIA_API_TOKEN`   | Un token de API con `admin`, `sps_…` | Production (y Preview, si quieres source maps ahí) | **Sí.** Márcala como sensible. |
| `SYPNIA_ENDPOINT`    | La URL base de tu motor              | Todos                                              | Solo con alojamiento propio.   |
| `SYPNIA_BASE_URL`    | La URL base de tu motor              | Los mismos que el token                            | Solo 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:

| 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 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](https://docs.sypnia.com/es/concepts/traces).

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

```ts
const nextConfig: NextConfig = {
  async rewrites() {
    return [{ source: '/_sy/:path*', destination: 'https://ingest.sypnia.com/:path*' }];
  },
};
```

`instrumentation-client.ts`

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

```bash
OTEL_EXPORTER_OTLP_ENDPOINT=https://ingest.sypnia.com/v1/otlp
OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e
```

`instrumentation.ts`

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