# Next.js on Vercel

> Set up @sypnia/next for an app deployed on Vercel, with the environment variables, what preview deployments report, source maps at build, and the ad-blocker route.

Applies to: the Sypnia engine (open source, self-hosted) and Sypnia Cloud (paid service). Status: at launch.  
Source: https://docs.sypnia.com/guides/nextjs-on-vercel/

This guide is for a Next.js app that Vercel builds and hosts. It applies to Sypnia Cloud and to a self-hosted engine; the variables that differ are marked. It builds on [Next.js](https://docs.sypnia.com/sdks/nextjs), which has every option.

**At the end you will have:** production and preview deployments reporting to Sypnia under separate environments, each deploy registered as a release with its source maps, and server requests traced inside Vercel's functions.

**You need:** Next.js 15.3 or newer, a Sypnia project with its ingest key, and an API token with the `admin` scope for source maps.

### 1. Add the package and the three files

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

Nothing else in the code: the key, the environment and the release come from variables.

### 2. Set the variables in Vercel

In your project on Vercel, open the environment variables settings and add:

| Variable             | Value                              | Environments                                            | Sensitive                      |
| -------------------- | ---------------------------------- | ------------------------------------------------------- | ------------------------------ |
| `SYPNIA_PROJECT_KEY` | Your ingest key, `spk_…`           | Production, Preview, Development                        | No. It is public.              |
| `SYPNIA_API_TOKEN`   | An API token with `admin`, `sps_…` | Production (and Preview, if you want source maps there) | **Yes.** Mark it as sensitive. |
| `SYPNIA_ENDPOINT`    | Your engine's base URL             | All                                                     | Self-hosted only.              |
| `SYPNIA_BASE_URL`    | Your engine's base URL             | The same as the token                                   | Self-hosted only.              |

Do not prefix any of them with `NEXT_PUBLIC_`. `withSypnia` passes the public ones to the browser itself, and the token must never reach it.

**You should see:**The variables are listed in the project. The next deployment uses them; existing deployments do not change.

### 3. Deploy and read the build log

Push a commit, or redeploy.

**You should see:**Near the end of the build log: `Sypnia: release 4f2a91c registered, 312 source maps uploaded, 312 removed from the build output.` The release is the first 7 characters of the commit Vercel built.

If it says `source maps not uploaded (SYPNIA_API_TOKEN is not set)`, the token is missing from the environment that was built.

### 4. Open the deployment

Open your production address, click around, and look at **Sessions** in Sypnia with the environment `production`.

**You should see:**Your session within 10 minutes. In **Traces**, requests to your Route Handlers and pages with their outgoing calls.

## What Vercel gives Sypnia by itself

`withSypnia` reads Vercel's own variables, so you set neither value:

| Sypnia        | Comes from                                  | Result                                                                                                                               |
| ------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `environment` | `VERCEL_ENV`                                | `production` for the production deployment, `preview` for every preview deployment, `development` under `next dev` and `vercel dev`. |
| `release`     | `VERCEL_GIT_COMMIT_SHA`, first 7 characters | The commit that was built, the same on the browser, the server and the source maps.                                                  |

This needs «Automatically expose System Environment Variables» to be on in the project, which is Vercel's default; check Vercel's current documentation if `release` comes out empty.

What this means in practice:

- **Previews do not alert you.** Alerts and the daily summary cover `production` only. A bug you see in a preview is a problem in the `preview` environment, separate from production.
- **Previews do count** towards a Sypnia Cloud plan, like every environment. If you open many previews, leave `SYPNIA_PROJECT_KEY` out of the Preview environment to keep them silent.
- **Each deploy is a release**, so a problem can say «since the deploy of 18:40» and name its commit.

## Functions

Server code on Vercel runs in functions that are frozen as soon as the response is sent. `@sypnia/next` sends each request's events with the mechanism Next.js and Vercel provide for work after the response, so tracing adds no wait to your responses and loses nothing when the function is frozen. There is nothing to configure.

Two limits at launch:

- Routes and middleware on the **Edge runtime** are not traced and their errors are not reported. **\[Planned]**
- A function that Vercel stops at its maximum duration cannot send its own record. Sypnia still gets the partial record written at 20 seconds, with the calls that were in flight. See [Traces](https://docs.sypnia.com/concepts/traces).

## Visitors with ad blockers

Send through your own domain so the requests are not blocked by host name. Add a rewrite and tell the browser side to use it:

`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' });
```

The server side keeps sending straight to ingest. On a self-hosted engine use your engine's base URL as the destination.

## If the app already uses OpenTelemetry

Apps that already call `registerOTel` from `@vercel/otel` in `instrumentation.ts` should keep it and send its traces to Sypnia with the standard variables, instead of adding Sypnia's `register`:

`Vercel environment variables`

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

Keep `instrumentation-client.ts` as above. See [OpenTelemetry](https://docs.sypnia.com/sdks/opentelemetry) for what each span becomes.

## Check the whole thing

| Check                 | Where                                        | You should see                                           |
| --------------------- | -------------------------------------------- | -------------------------------------------------------- |
| The browser sends     | Network tab, filter `ingest` (or `_sy`)      | `POST …/v1/ingest/events`, `200`                         |
| The server sends      | Sypnia, **Traces**, environment `production` | Your routes, with spans                                  |
| The release is set    | Any session                                  | Release `4f2a91c`, the deployed commit                   |
| Source maps apply     | The next problem's stack                     | `src/checkout/checkout.tsx:142`, not `…-3f9c.js:1:48211` |
| Previews are separate | Environment `preview`                        | Only sessions from preview addresses                     |
