Docs▸Browser SDK

Next.js quickstart

To monitor a Next.js app, install @vigilon/nextjs: requests to your pages and API routes are traced under the route Next.js resolved, such as /api/orders/[id], and errors from Server Components, route handlers, Server Actions and the browser are reported under one app. Requires Next.js 15.3 or later and Node.js 22.12 or later.

Set up with an AI agent

Using a coding agent such as Claude Code, Codex or Cursor? Paste this prompt into it from the root of your project. It installs and configures the SDK for you, and leaves the API key for you to add.

Prompt
Run `curl -fsSL https://vigilon.io/agents/install.md` and follow the instructions in that file to set up Vigilon in this project.
1

Install the SDK

One package covers both sides. It wraps the Node.js SDK on the server and the React SDK in the browser.

shell
npm install @vigilon/nextjs
2

Create two API keys

On the API Keys tab of your project's Settings page, create two keys: one of kind Server for the Node.js runtime, and one of kind Browser for the client, with your site's origins under Allowed origins. The browser key is built into your client JavaScript, where anyone can read it, so never use the server key there.

Set them where your app builds and runs:

.env
# Server: read at runtime. Keep it secret.
VIGILON_API_KEY="[YOUR_API_KEY]"
VIGILON_ENVIRONMENT="production"

# Browser: inlined into the client bundle at build time.
NEXT_PUBLIC_VIGILON_API_KEY="[YOUR_BROWSER_API_KEY]"
NEXT_PUBLIC_VIGILON_ENVIRONMENT="production"

NEXT_PUBLIC_ variables are inlined when you build, so set them where next build runs and rebuild after changing them.

Running without a key

Without VIGILON_API_KEY, the server stops with an error naming the variable, so pages it renders fail. For local development, start with VIGILON_DISABLED=1 to turn the server SDK off for that run.

3

Wrap your Next.js config

next.config.ts
import { withVigilon } from "@vigilon/nextjs/config";

export default withVigilon({
  // your Next.js config
});

withVigilon() keeps the SDK and its OpenTelemetry dependencies out of the server bundle, and renders the trace ID of the request into each server-rendered page, so a browser error on that page carries it. The error links to that trace when Vigilon kept it: every trace with an error and every slow one is kept, but only a sample of fast, successful ones, so most errors on healthy pages show no trace (see How Vigilon keeps traces in the OpenTelemetry guide).

4

Register the server SDK

instrumentation.ts
export async function register() {
  if (process.env.NEXT_RUNTIME === "nodejs") {
    const { register } = await import("@vigilon/nextjs/server");
    register({ appName: "storefront", appVersion: process.env.VIGILON_APP_VERSION });
  }
}

register() takes the same options as the Node.js SDK and reads anything you leave out from the environment, such as VIGILON_API_KEY and VIGILON_ENVIRONMENT. Request spans are labelled with the route Next.js resolved, such as /api/orders/[id], and on Vercel telemetry is flushed at the end of every request. The SDK cannot run in the Edge runtime, so check NEXT_RUNTIME and import it dynamically as shown.

Next.js records errors from Server Components, route handlers, and Server Actions on its request spans, so they reach Vigilon with no extra hook. recordException and withJobMonitor are exported from @vigilon/nextjs/server.

5

Start the browser SDK

instrumentation-client.ts
import { init } from "@vigilon/nextjs";

init({
  apiKey: process.env.NEXT_PUBLIC_VIGILON_API_KEY!,
  appName: "storefront",
  environment: process.env.NEXT_PUBLIC_VIGILON_ENVIRONMENT!,
  appVersion: process.env.NEXT_PUBLIC_VIGILON_APP_VERSION,
});

Use the same appName as the server: Vigilon keeps server and browser errors apart by their origin. init takes every option of the browser SDK. Client-side navigations, App Router ones included, are recorded as breadcrumbs.

6

Report errors from error boundaries

Next.js creates the React root itself, so report the render errors that an error.tsx or global-error.tsx boundary catches from the boundary:

app/global-error.tsx
"use client";
import { useReportError } from "@vigilon/nextjs";

export default function GlobalError({ error }: { error: Error & { digest?: string } }) {
  useReportError(error);
  return (
    <html lang="en">
      <body>
        <h2>Something went wrong.</h2>
      </body>
    </html>
  );
}

Do the same in each error.tsx. An error thrown on the server reaches these boundaries with its message redacted and a digest; Next.js has already recorded it on the server, so useReportError skips it rather than report the redacted copy. Inside your own client components, use ErrorBoundary from @vigilon/nextjs.

7

Upload source maps

Create an upload token on the Source Maps tab of your project's Settings page, and set it as VIGILON_SOURCE_MAP_TOKEN where next build runs, such as a CI secret. Never give it a NEXT_PUBLIC_ name: anyone with it can replace your source maps.

With the token, withVigilon() builds browser source maps, gives every script a debug ID, uploads the scripts and maps once Next.js has compiled, and deletes the maps so none is deployed. It needs Next.js 15.4 or later, with Turbopack or webpack.

shell
VIGILON_SOURCE_MAP_TOKEN=vg_sm_... next build

A failed upload fails the build. To log a warning instead, pass withVigilon(nextConfig, { onUploadError: "warn" }). On Next.js 15.3, set productionBrowserSourceMaps: true and run the CLI on .next/static after the build, as the Source maps guide shows.

8

Check that errors arrive

Deploy, then make a few requests to a normal route: server traces appear in the project within a minute. For browser errors, throw a test error from the browser's developer console on one of your pages:

console
setTimeout(() => {
  throw new Error("Vigilon test error");
});

The setTimeout makes it an uncaught error of the page, which the SDK reports. Browsers do not pass an error thrown directly at the console prompt to the page.

Open the project in Vigilon. The error appears on the Errors page, usually within a minute, as an error group with origin browser. Its sample shows the stack trace and the breadcrumbs recorded before the error.

If nothing arrives

Add debug: true to init to log what the SDK does. In the browser's network panel, a request to /v1/browser/events answered with HTTP 403 carries the reason in its response: a server key used instead of a browser key, or a page origin missing from the key's allowed origins. The SDK does not retry a 403.

Next steps