Docs

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 EngineCloud At launch

View as Markdown
On this page
  1. Install
  2. Set it up
  3. Wrap your Next.js config
  4. Switch on the server
  5. Switch on the browser
  6. Run it and look
  7. What you get
  8. Errors shown by an error boundary
  9. Identifying people
  10. withSypnia(nextConfig, options)
  11. Source maps at build
  12. Next

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/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
    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',
    });
    .env.local
    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
    export { register, onRequestError } from '@sypnia/next/server';
  3. Switch on the browser

    instrumentation-client.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, 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

SideCoveredNotes
BrowserEverything 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 RouterPage and layout renders, Route Handlers, Server Actions.One server_request each, with the route as Next.js names it (/orders/[id]).
Server, Pages RouterPages with getServerSideProps, API routes under pages/api.The same.
Outgoing callsfetch, http, pg, Supabase and PostgREST, as in the Node SDK.Spans under the request.
Server errorsEvery error Next.js catches on the server, through onRequestError.With the digest Next.js gives it.
TraceThe 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.

app/error.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
'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)

OptionTypeDefaultWhat it does
projectstringprocess.env.SYPNIA_PROJECT_KEYThe ingest key, spk_…. Without it the build prints one warning and Sypnia stays off.
endpointstringprocess.env.SYPNIA_ENDPOINT, else 'https://ingest.sypnia.com'Where to send. A self-hosted engine’s base URL.
servicestringprocess.env.SYPNIA_SERVICE, else 'next'The name of the server side in traces.
environmentstringprocess.env.SYPNIA_ENVIRONMENT, else process.env.VERCEL_ENV, else 'development' under next dev and 'production' otherwiseThe environment, the same for both sides.
releasestringprocess.env.SYPNIA_RELEASE, else the first 7 characters of process.env.VERCEL_GIT_COMMIT_SHA, else git rev-parse --short HEAD, else noneThe release, the same for both sides and for the source maps.
debugbooleanfalsePrints every event, in the browser console and in the server’s output.
sourceMapsbooleantrueUploads source maps when you build. See below.
apiUrlstringprocess.env.SYPNIA_BASE_URL, else 'https://api.sypnia.com'Where source maps are uploaded. A self-hosted engine’s base URL.
serverNode 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:

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

Sections

Start hereWhat Sypnia is, how it works, what is open source and what is the paid cloud, and the two ways to get your first problem in plain words.ConceptsThe ten ideas Sypnia is made of, each defined precisely, from a project and its keys to problems, traces and alerts.SDKsHow your app sends data to Sypnia. One SDK for the browser, one for Node, one for Next.js, and the OpenTelemetry intake for every other backend.The agentHow Sypnia analyses a problem, what it writes, what it sends to a model and what it never does.MCP and skillsConnect your coding agent to Sypnia so it can ask what is failing in production, read what it needs to fix it, and set Sypnia up for you.API referenceThe Sypnia HTTP API: one API for the open-source engine and for Sypnia Cloud, with every endpoint, parameter, response and error.CLI referenceThe sypnia command: how to install it, the variables it reads, what its exit codes mean, and where each command is documented.Self-hostingWhat you run when you host the Sypnia engine yourself, what you need, what it costs, and what you do not get compared with Sypnia Cloud.How the engine is builtThe whole Sypnia engine on one page, from a click in your app to the sentence your coding agent reads, with the design rules and the code that holds them.Sypnia CloudHow the paid service works, from organizations and roles to plans, limits, billing, where your data lives, the GitHub App and support.Privacy and securityWhat Sypnia collects from your app and its users, what it never collects, how masking works, how to delete data, and how the service is protected.LicensingWhich licence covers each part of Sypnia, what you may do with it, how the name may be used, and the terms of a contribution.GuidesStep-by-step recipes for the common ways to use Sypnia, from apps made with AI builders and Next.js on Vercel to Supabase, source maps in CI, alert e-mails from your own engine, and moving from Sentry.ReferenceThe pages you look things up in, from the event schema and the glossary to what is planned, the changelog and the common questions.
↑↓ to move↵ to openEsc to close