ref-sentry

name	ref-sentry
description	Reference for Sentry Next.js integration (@sentry/nextjs). Covers setup, configuration, and error tracking. Consult when setting up monitoring or debugging Sentry configuration issues.

Sentry + Next.js Reference

Packages

bun add @sentry/nextjs

Setup (Wizard — Recommended)

npx @sentry/wizard@latest -i nextjs

This auto-creates all config files. Alternatively, manual setup below.

Manual Setup

1. next.config.ts

import { withSentryConfig } from "@sentry/nextjs";

const nextConfig = {
  // your Next.js config
};

export default withSentryConfig(nextConfig, {
  org: "your-org",
  project: "your-project",
  authToken: process.env.SENTRY_AUTH_TOKEN,
  tunnelRoute: "/monitoring",  // avoids ad-blockers
  silent: !process.env.CI,
});

2. sentry.client.config.ts

import * as Sentry from "@sentry/nextjs";

Sentry.init({
  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
  tracesSampleRate: 1.0,
  replaysSessionSampleRate: 0.1,
  replaysOnErrorSampleRate: 1.0,
});

3. sentry.server.config.ts

import * as Sentry from "@sentry/nextjs";

Sentry.init({
  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
  tracesSampleRate: 1.0,
});

4. sentry.edge.config.ts

import * as Sentry from "@sentry/nextjs";

Sentry.init({
  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
  tracesSampleRate: 1.0,
});

5. instrumentation.ts (App Router)

export async function register() {
  if (process.env.NEXT_RUNTIME === "nodejs") {
    await import("./sentry.server.config");
  }
  if (process.env.NEXT_RUNTIME === "edge") {
    await import("./sentry.edge.config");
  }
}

Environment Variables

NEXT_PUBLIC_SENTRY_DSN=https://[e-mail]/456
SENTRY_AUTH_TOKEN=sntrys_xxx  # for source map uploads
SENTRY_ORG=your-org
SENTRY_PROJECT=your-project

Key Features

• AI Agent Monitoring — Sentry can monitor AI agents built with Vercel AI SDK
• Error tracking — automatic capture of unhandled errors
• Session Replay — replay user sessions that hit errors
• Performance tracing — track route handler and API latency
• tunnelRoute — routes Sentry traffic through your server to bypass ad-blockers

Gotchas

• Use the wizard (npx @sentry/wizard) — it's much faster than manual setup
• tunnelRoute: "/monitoring" — important for production, avoids ad-blockers
• authToken — needed for source map uploads, set in Vercel env vars
• Hackathon credits — sign up at sentry.io/signup/?code=ZTA26 for free credits
• withSentryConfig wraps nextConfig — must be the outermost wrapper