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.
This page is for whoever runs a Next.js app. @sypnia/next is the browser SDK and the Node SDK 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
npm install @sypnia/nextpnpm
pnpm add @sypnia/nextyarn
yarn add @sypnia/nextbun
bun add @sypnia/nextSet 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.
Wrap your Next.js config
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', });Self-hosted
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_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2ewithSypniareads 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.Switch on the browser
instrumentation-client.ts import { init } from '@sypnia/next/client'; init(); export { onRouterTransitionStart } from '@sypnia/next/client';init()takes its values fromwithSypnia. It also accepts any browser option, for exampleinit({ maskAllText: true }).
What you get
| Side | Covered | Notes |
|---|---|---|
| Browser | Everything the browser SDK 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. | 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, 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.
'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:
'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.
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 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:
- Turns on source maps for the browser bundles.
- Registers the release, with the commit when git can tell it.
- Uploads every source map for that release.
- Deletes the
.mapfiles from the build output, so they are never published.
SYPNIA_PROJECT_KEY=spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e
SYPNIA_API_TOKEN=sps_4Kq9Zt2MxV7bN1cR5wY8pL3dF6hJ0sA2gE4uT9iOThe 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_.
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
- Variables, preview deployments and source maps on Vercel.
- What never leaves the browser.
- Nothing arrives, ad blockers, source maps that do not apply.