Docs

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

View as Markdown
On this page
  1. Add the package and the three files
  2. Set the variables in Vercel
  3. Deploy and read the build log
  4. Open the deployment
  5. What Vercel gives Sypnia by itself
  6. Functions
  7. Visitors with ad blockers
  8. If the app already uses OpenTelemetry
  9. Check the whole thing

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

    Terminal
    npm install @sypnia/next
    next.config.ts
    import type { NextConfig } from 'next';
    import { withSypnia } from '@sypnia/next';
    
    const nextConfig: NextConfig = {};
    
    export default withSypnia(nextConfig, { service: 'shop-web' });
    instrumentation.ts
    export { register, onRequestError } from '@sypnia/next/server';
    instrumentation-client.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:

    VariableValueEnvironmentsSensitive
    SYPNIA_PROJECT_KEYYour ingest key, spk_…Production, Preview, DevelopmentNo. It is public.
    SYPNIA_API_TOKENAn API token with admin, sps_…Production (and Preview, if you want source maps there)Yes. Mark it as sensitive.
    SYPNIA_ENDPOINTYour engine’s base URLAllSelf-hosted only.
    SYPNIA_BASE_URLYour engine’s base URLThe same as the tokenSelf-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:

SypniaComes fromResult
environmentVERCEL_ENVproduction for the production deployment, preview for every preview deployment, development under next dev and vercel dev.
releaseVERCEL_GIT_COMMIT_SHA, first 7 charactersThe 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.

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
const nextConfig: NextConfig = {
  async rewrites() {
    return [{ source: '/_sy/:path*', destination: 'https://ingest.sypnia.com/:path*' }];
  },
};
instrumentation-client.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
OTEL_EXPORTER_OTLP_ENDPOINT=https://ingest.sypnia.com/v1/otlp
OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e
instrumentation.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 for what each span becomes.

Check the whole thing

CheckWhereYou should see
The browser sendsNetwork tab, filter ingest (or _sy)POST …/v1/ingest/events, 200
The server sendsSypnia, Traces, environment productionYour routes, with spans
The release is setAny sessionRelease 4f2a91c, the deployed commit
Source maps applyThe next problem’s stacksrc/checkout/checkout.tsx:142, not …-3f9c.js:1:48211
Previews are separateEnvironment previewOnly sessions from preview addresses

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