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.
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.
Add the package and the three files
Terminal npm install @sypnia/nextnext.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.
Set the variables in Vercel
In your project on Vercel, open the environment variables settings and add:
Variable Value Environments Sensitive SYPNIA_PROJECT_KEYYour ingest key, spk_…Production, Preview, Development No. 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 URL All Self-hosted only. SYPNIA_BASE_URLYour engine’s base URL The same as the token Self-hosted only. Do not prefix any of them with
NEXT_PUBLIC_.withSypniapasses the public ones to the browser itself, and the token must never reach it.You should seeThe variables are listed in the project. The next deployment uses them; existing deployments do not change.Deploy and read the build log
Push a commit, or redeploy.
You should seeNear 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.
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
productiononly. A bug you see in a preview is a problem in thepreviewenvironment, separate from production. - Previews do count towards a Sypnia Cloud plan, like every environment. If you open many previews, leave
SYPNIA_PROJECT_KEYout 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:
const nextConfig: NextConfig = {
async rewrites() {
return [{ source: '/_sy/:path*', destination: 'https://ingest.sypnia.com/:path*' }];
},
};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:
OTEL_EXPORTER_OTLP_ENDPOINT=https://ingest.sypnia.com/v1/otlp
OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2eimport { 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
| 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 |