# Next.js

> One setup of @sypnia/next covers the browser and the server of a Next.js app, in the App Router and the Pages Router, and uploads source maps when you build.

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

This page is for whoever runs a Next.js app. `@sypnia/next` is the [browser SDK](https://docs.sypnia.com/sdks/browser) and the [Node SDK](https://docs.sypnia.com/sdks/node) set up together, plus what is specific to Next.js: navigation in the App Router, errors thrown on the server, and source maps. It is MIT-licensed and identical for the open-source engine and for Sypnia Cloud.

**At the end you will have:** sessions, replays and page performance from the browser, every server request traced, server errors linked to the page that showed them, and stacks that point at your own files.

**You need:** Next.js 15.3 or newer.

## Install

**npm**

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

**pnpm**

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

**yarn**

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

**bun**

```bash
bun add @sypnia/next
```

## Set it up

Three small files. The configuration lives in the first one; the other two only switch Sypnia on, in the server and in the browser. Put the two instrumentation files next to `app/` or `pages/`: in the project root, or in `src/` if you use it.

### 1. Wrap your Next.js config

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

**Self-hosted**

`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` reads these values when Next.js builds and gives them to both sides of your app, so you write them once. The ingest key is public: it is meant to end up in the browser bundle.

### 2. Switch on the server

`instrumentation.ts`

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

### 3. Switch on the browser

`instrumentation-client.ts`

```ts
import { init } from '@sypnia/next/client';

init();

export { onRouterTransitionStart } from '@sypnia/next/client';
```

`init()` takes its values from `withSypnia`. It also accepts any [browser option](https://docs.sypnia.com/sdks/browser#initoptions), for example `init({ maskAllText: true })`.

### 4. Run it and look

Run `next dev`, open a page and click a link. In the browser's Network tab, filter by `ingest`.

**You should see:**A `POST` to `…/v1/ingest/events` answered `200`, within 10 seconds. With `debug: true` in `withSypnia`, the terminal also prints one `server_request` for each request the server handled.

## What you get

| Side                 | Covered                                                                                                                                 | Notes                                                                                                                                                                      |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Browser              | Everything the [browser SDK](https://docs.sypnia.com/sdks/browser#what-is-captured-without-any-code) captures.                          | Navigations of the App Router are reported by Next.js itself through `onRouterTransitionStart`; the Pages Router is followed through the History API. Both are page views. |
| Server, App Router   | Page and layout renders, Route Handlers, Server Actions.                                                                                | One `server_request` each, with the route as Next.js names it (`/orders/[id]`).                                                                                            |
| Server, Pages Router | Pages with `getServerSideProps`, API routes under `pages/api`.                                                                          | The same.                                                                                                                                                                  |
| Outgoing calls       | `fetch`, `http`, `pg`, Supabase and PostgREST, as in the [Node SDK](https://docs.sypnia.com/sdks/node#what-is-traced-without-any-code). | Spans under the request.                                                                                                                                                   |
| Server errors        | Every error Next.js catches on the server, through `onRequestError`.                                                                    | With the digest Next.js gives it.                                                                                                                                          |
| Trace                | The browser's call and the server's request share one trace id.                                                                         | Nothing to configure for calls to your own app.                                                                                                                            |

**Not covered at launch:** code that runs on the Edge runtime (routes with `export const runtime = 'edge'`, and middleware). It is neither traced nor are its errors reported. **\[Planned]**

If your app already registers OpenTelemetry in `instrumentation.ts` (for example with `@vercel/otel`), do not add `register` from Sypnia on top. Keep your setup, point its exporter at the [OTLP intake](https://docs.sypnia.com/sdks/opentelemetry), and use `@sypnia/next` for the browser side and for `onRequestError`.

## Errors shown by an error boundary

When a Server Component throws, Next.js shows your `error.tsx` and hides the real message from the browser. It gives both sides the same `digest`. Report the error from the boundary with that digest, and Sypnia joins the page the person saw to the server error with its stack.

`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>Something went wrong.</p>
      <button onClick={reset}>Try again</button>
    </div>
  );
}
```

Do the same in `app/global-error.tsx` if you have one. In the Pages Router there is nothing to add: errors while rendering in the browser reach the window and are reported.

## Identifying people

In the browser, from a Client Component that knows the signed-in person:

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

Render it in your root layout when someone is signed in. On the server you do not need to identify requests that come from that browser. See [Identifying people](https://docs.sypnia.com/sdks/identifying-people).

## `withSypnia(nextConfig, options)`

| Option        | Type             | Default                                                                                                                                        | What it does                                                                                                                                        |
| ------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `project`     | `string`         | `process.env.SYPNIA_PROJECT_KEY`                                                                                                               | The ingest key, `spk_…`. Without it the build prints one warning and Sypnia stays off.                                                              |
| `endpoint`    | `string`         | `process.env.SYPNIA_ENDPOINT`, else `'https://ingest.sypnia.com'`                                                                              | Where to send. A self-hosted engine's base URL.                                                                                                     |
| `service`     | `string`         | `process.env.SYPNIA_SERVICE`, else `'next'`                                                                                                    | The name of the server side in traces.                                                                                                              |
| `environment` | `string`         | `process.env.SYPNIA_ENVIRONMENT`, else `process.env.VERCEL_ENV`, else `'development'` under `next dev` and `'production'` otherwise            | The environment, the same for both sides.                                                                                                           |
| `release`     | `string`         | `process.env.SYPNIA_RELEASE`, else the first 7 characters of `process.env.VERCEL_GIT_COMMIT_SHA`, else `git rev-parse --short HEAD`, else none | The release, the same for both sides and for the source maps.                                                                                       |
| `debug`       | `boolean`        | `false`                                                                                                                                        | Prints every event, in the browser console and in the server's output.                                                                              |
| `sourceMaps`  | `boolean`        | `true`                                                                                                                                         | Uploads source maps when you build. See below.                                                                                                      |
| `apiUrl`      | `string`         | `process.env.SYPNIA_BASE_URL`, else `'https://api.sypnia.com'`                                                                                 | Where source maps are uploaded. A self-hosted engine's base URL.                                                                                    |
| `server`      | Node SDK options | `{}`                                                                                                                                           | Any option of the [Node SDK](https://docs.sypnia.com/sdks/node#initoptions) except the ones above, for example `{ ignoreRoutes: ['/api/health'] }`. |

Browser-only options go to `init()` in `instrumentation-client.ts`.

## Source maps at build

A production build with `SYPNIA_API_TOKEN` in its environment does four things, in order:

1. Turns on source maps for the browser bundles.
2. Registers the release, with the commit when git can tell it.
3. Uploads every source map for that release.
4. Deletes the `.map` files from the build output, so they are never published.

`Build environment`

```bash
SYPNIA_PROJECT_KEY=spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e
SYPNIA_API_TOKEN=sps_4Kq9Zt2MxV7bN1cR5wY8pL3dF6hJ0sA2gE4uT9iO
```

The token is an API token with the `admin` scope. It is a secret: set it in your CI or your host's build settings, never in the code and never in a variable that starts with `NEXT_PUBLIC_`.

**You should see:**At the end of `next build`: `Sypnia: release 4f2a91c registered, 312 source maps uploaded, 312 removed from the build output.`

The upload never fails your build. Without the token it prints `Sypnia: source maps not uploaded (SYPNIA_API_TOKEN is not set)` and goes on; if the upload fails it says why and goes on. Under `next dev` nothing is uploaded.

Source maps of the server bundles are **\[Planned]**: at launch a server error's stack shows the built file. Its route, its trace and the page that showed it are there either way.

## Next
