---

name: sentry-nextjs-sdk description: Full Sentry SDK setup for Next.js. Use when asked to "add Sentry to Next.js", "install @sentry/nextjs", or configure error monitoring, tracing, session replay, logging, profiling, AI monitoring, or crons for Next.js applications. Supports Next.js 13+ with App Router and Pages Router. license: Apache-2.0 category: sdk-setup parent: sentry-sdk-setup disable-model-invocation: true

All Skills > SDK Setup > Next.js SDK

Sentry Next.js SDK

Opinionated wizard that scans your Next.js project and guides you through complete Sentry setup across all three runtimes: browser, Node.js server, and Edge.

Invoke This Skill When

• User asks to "add Sentry to Next.js" or "set up Sentry" in a Next.js app
• User wants to install or configure @sentry/nextjs
• User wants error monitoring, tracing, session replay, logging, or profiling for Next.js
• User asks about instrumentation.ts, withSentryConfig(), or global-error.tsx
• User wants to capture server actions, server component errors, or edge runtime errors

Note: SDK versions and APIs below reflect current Sentry docs at time of writing (@sentry/nextjs ≥8.28.0). Always verify against docs.sentry.io/platforms/javascript/guides/nextjs/ before implementing.

---

Phase 1: Detect

Run these commands to understand the project before making any recommendations:

# Detect Next.js version and existing Sentry
cat package.json | grep -E '"next"|"@sentry/'

# Detect router type (App Router vs Pages Router)
ls src/app app src/pages pages 2>/dev/null

# Check for existing Sentry config files
ls instrumentation.ts instrumentation-client.ts sentry.server.config.ts sentry.edge.config.ts 2>/dev/null
ls src/instrumentation.ts src/instrumentation-client.ts 2>/dev/null

# Check next.config
ls next.config.ts next.config.js next.config.mjs 2>/dev/null

# Check for existing error boundaries
find . -name "global-error.tsx" -o -name "_error.tsx" 2>/dev/null | grep -v node_modules

# Check build tool
cat package.json | grep -E '"turbopack"|"webpack"'

# Check for logging libraries
cat package.json | grep -E '"pino"|"winston"|"bunyan"'

# Check for companion backend
ls ../backend ../server ../api 2>/dev/null
cat ../go.mod ../requirements.txt ../Gemfile 2>/dev/null | head -3

What to determine:

| Question | Impact | |----------|--------| | Next.js version? | 13+ required; 15+ needed for Turbopack support | | App Router or Pages Router? | Determines error boundary files needed (global-error.tsx vs _error.tsx) | | @sentry/nextjs already present? | Skip install, go to feature config | | Existing instrumentation.ts? | Merge Sentry into it rather than replace | | Turbopack in use? | Tree-shaking in withSentryConfig is webpack-only | | Logging library detected? | Recommend Sentry Logs integration | | Backend directory found? | Trigger Phase 4 cross-link suggestion |

---

Phase 2: Recommend

Present a concrete recommendation based on what you found. Don't ask open-ended questions — lead with a proposal:

Recommended (core coverage):

• ✅ Error Monitoring — always; captures server errors, client errors, server actions, and unhandled promise rejections
• ✅ Tracing — server-side request tracing + client-side navigation spans across all runtimes
• ✅ Session Replay — recommended for user-facing apps; records sessions around errors

Optional (enhanced observability):

• ⚡ Logging — structured logs via Sentry.logger.*; recommend when pino/winston or log search is needed
• ⚡ Profiling — continuous profiling; requires Document-Policy: js-profiling header
• ⚡ AI Monitoring — OpenAI, Vercel AI SDK, Anthropic; recommend when AI/LLM calls detected
• ⚡ Crons — detect missed/failed scheduled jobs; recommend when cron patterns detected
• ⚡ Metrics — custom metrics via Sentry.metrics.*; recommend when custom KPIs or business metrics needed

Recommendation logic:

| Feature | Recommend when... | |---------|------------------| | Error Monitoring | Always — non-negotiable baseline | | Tracing | Always for Next.js — server route tracing + client navigation are high-value | | Session Replay | User-facing app, login flows, or checkout pages | | Logging | App uses structured logging or needs log-to-trace correlation | | Profiling | Performance-critical app; client sets Document-Policy: js-profiling | | AI Monitoring | App makes OpenAI, Vercel AI SDK, or Anthropic calls | | Crons | App has Vercel Cron jobs, scheduled API routes, or node-cron usage | | Metrics | App needs custom counters, gauges, or histograms via Sentry.metrics.* |

Propose: "I recommend setting up Error Monitoring + Tracing + Session Replay. Want me to also add Logging or Profiling?"

---

Phase 3: Guide

Option 1: Wizard (Recommended)

You need to run this yourself — the wizard opens a browser for login and requires interactive input that the agent can't handle. Copy-paste into your terminal:

npx @sentry/wizard@latest -i nextjs

It handles login, org/project selection, SDK installation, config files (instrumentation-client.ts, sentry.server.config.ts, sentry.edge.config.ts, instrumentation.ts), next.config.ts wrapping, source map upload, and adds a /sentry-example-page.

Once it finishes, come back and skip to Verification.

If the user skips the wizard, proceed with Option 2 (Manual Setup) below.

---

Option 2: Manual Setup

Install

npm install @sentry/nextjs --save

Create instrumentation-client.ts — Browser / Client Runtime

Older docs used sentry.client.config.ts — the current pattern is instrumentation-client.ts.

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

Sentry.init({
  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN ?? "___PUBLIC_DSN___",

  sendDefaultPii: true,

  // 100% in dev, 10% in production
  tracesSampleRate: process.env.NODE_ENV === "development" ? 1.0 : 0.1,

  // Session Replay: 10% of all sessions, 100% of sessions with errors
  replaysSessionSampleRate: 0.1,
  replaysOnErrorSampleRate: 1.0,

  enableLogs: true,

  integrations: [
    Sentry.replayIntegration(),
    // Optional: user feedback widget
    // Sentry.feedbackIntegration({ colorScheme: "system" }),
  ],
});

// Hook into App Router navigation transitions (App Router only)
export const onRouterTransitionStart = Sentry.captureRouterTransitionStart;

Create sentry.server.config.ts — Node.js Server Runtime

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

Sentry.init({
  dsn: process.env.SENTRY_DSN ?? "___DSN___",

  sendDefaultPii: true,
  tracesSampleRate: process.env.NODE_ENV === "development" ? 1.0 : 0.1,

  // Attach local variable values to stack frames
  includeLocalVariables: true,

  enableLogs: true,
});

Create sentry.edge.config.ts — Edge Runtime

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

Sentry.init({
  dsn: process.env.SENTRY_DSN ?? "___DSN___",

  sendDefaultPii: true,
  tracesSampleRate: process.env.NODE_ENV === "development" ? 1.0 : 0.1,

  enableLogs: true,
});

Create instrumentation.ts — Server-Side Registration Hook

Requires experimental.instrumentationHook: true in next.config for Next.js < 14.0.4. It's stable in 14.0.4+.

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

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");
  }
}

// Automatically captures all unhandled server-side request errors
// Requires @sentry/nextjs >= 8.28.0
export const onRequestError = Sentry.captureRequestError;

Runtime dispatch:

| NEXT_RUNTIME | Config file loaded | |---|---| | "nodejs" | sentry.server.config.ts | | "edge" | sentry.edge.config.ts | | (client bundle) | instrumentation-client.ts (Next.js handles this directly) |

App Router: Create app/global-error.tsx

This catches errors in the root layout and React render errors:

"use client";

import * as Sentry from "@sentry/nextjs";
import NextError from "next/error";
import { useEffect } from "react";

export default function GlobalError({
  error,
}: {
  error: Error & { digest?: string };
}) {
  useEffect(() => {
    Sentry.captureException(error);
  }, [error]);

  return (
    <html>
      <body>
        <NextError statusCode={0} />
      </body>
    </html>
  );
}

Pages Router: Update pages/_error.tsx

import * as Sentry from "@sentry/nextjs";
import type { NextPageContext } from "next";
import NextErrorComponent from "next/error";

type ErrorProps = { statusCode: number };

export default function CustomError({ statusCode }: ErrorProps) {
  return <NextErrorComponent statusCode={statusCode} />;
}

CustomError.getInitialProps = async (ctx: NextPageContext) => {
  await Sentry.captureUnderscoreErrorException(ctx);
  return NextErrorComponent.getInitialProps(ctx);
};

Wrap next.config.ts with withSentryConfig()

import type { NextConfig } from "next";
import { withSentryConfig } from "@sentry/nextjs";

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

export default withSentryConfig(nextConfig, {
  org: "___ORG_SLUG___",
  project: "___PROJECT_SLUG___",

  // Source map upload auth token (see Source Maps section below)
  authToken: process.env.SENTRY_AUTH_TOKEN,

  // Upload wider set of client source files for better stack trace resolution
  widenClientFileUpload: true,

  // Create a proxy API route to bypass ad-blockers
  tunnelRoute: "/monitoring",

  // Suppress non-CI output
  silent: !process.env.CI,
});

Exclude Tunnel Route from Middleware

If you have middleware.ts, exclude the tunnel path from auth or redirect logic:

// middleware.ts
export const config = {
  matcher: [
    // Exclude monitoring route, Next.js internals, and static files
    "/((?!monitoring|_next/static|_next/image|favicon.ico).*)",
  ],
};

---

Source Maps Setup

Source maps make production stack traces readable — without them, you see minified code. This is non-negotiable for production apps.

Step 1: Generate a Sentry auth token

Go to sentry.io/settings/auth-tokens/ and create a token with project:releases and org:read scopes.

Step 2: Set environment variables

# .env.sentry-build-plugin  (gitignore this file)
SENTRY_AUTH_TOKEN=sntrys_eyJ...

Or set in CI secrets:

SENTRY_AUTH_TOKEN=sntrys_eyJ...
SENTRY_ORG=my-org        # optional if set in next.config
SENTRY_PROJECT=my-project # optional if set in next.config

Step 3: Add to .gitignore

.env.sentry-build-plugin

Step 4: Verify authToken is wired in next.config.ts

withSentryConfig(nextConfig, {
  org: "my-org",
  project: "my-project",
  authToken: process.env.SENTRY_AUTH_TOKEN, // reads from .env.sentry-build-plugin or CI env
  widenClientFileUpload: true,
});

Source maps are uploaded automatically on every next build.

---

For Each Agreed Feature

Load the corresponding reference file and follow its steps:

| Feature | Reference file | Load when... | |---------|---------------|-------------| | Error Monitoring | references/error-monitoring.md | Always (baseline) — App Router error boundaries, Pages Router _error.tsx, server action wrapping | | Tracing | references/tracing.md | Server-side request tracing, client navigation, distributed tracing, tracePropagationTargets | | Session Replay | references/session-replay.md | User-facing app; privacy masking, canvas recording, network capture | | Logging | references/logging.md | Structured logs, Sentry.logger.*, log-to-trace correlation | | Profiling | references/profiling.md | Continuous profiling, Document-Policy header, nodeProfilingIntegration | | AI Monitoring | references/ai-monitoring.md | App uses OpenAI, Vercel AI SDK, or Anthropic | | Crons | references/crons.md | Vercel Cron, scheduled API routes, node-cron |

For each feature: read the reference file, follow its steps exactly, and verify before moving on.

---

Verification

After wizard or manual setup, verify Sentry is working:

// Add temporarily to a server action or API route, then remove
import * as Sentry from "@sentry/nextjs";

throw new Error("Sentry test error — delete me");
// or
Sentry.captureException(new Error("Sentry test error — delete me"));

Then check your Sentry Issues dashboard — the error should appear within ~30 seconds.

Verification checklist:

| Check | How | |-------|-----| | Client errors captured | Throw in a client component, verify in Sentry | | Server errors captured | Throw in a server action or API route | | Edge errors captured | Throw in middleware or edge route handler | | Source maps working | Check stack trace shows readable file names | | Session Replay working | Check Replays tab in Sentry dashboard |

---

Config Reference

Sentry.init() Options

| Option | Type | Default | Notes | |--------|------|---------|-------| | dsn | string | — | Required. Use NEXT_PUBLIC_SENTRY_DSN for client, SENTRY_DSN for server | | tracesSampleRate | number | — | 0–1; 1.0 in dev, 0.1 in prod recommended | | replaysSessionSampleRate | number | 0.1 | Fraction of all sessions recorded | | replaysOnErrorSampleRate | number | 1.0 | Fraction of error sessions recorded | | sendDefaultPii | boolean | false | Include IP, request headers in events | | includeLocalVariables | boolean | false | Attach local variable values to stack frames (server only) | | enableLogs | boolean | false | Enable Sentry Logs product | | environment | string | auto | "production", "staging", etc. | | release | string | auto | Set to commit SHA or version tag | | debug | boolean | false | Log SDK activity to console |

withSentryConfig() Options

| Option | Type | Notes | |--------|------|-------| | org | string | Sentry organization slug | | project | string | Sentry project slug | | authToken | string | Source map upload token (SENTRY_AUTH_TOKEN) | | widenClientFileUpload | boolean | Upload more client files for better stack traces | | tunnelRoute | string | API route path for ad-blocker bypass (e.g. "/monitoring") | | silent | boolean | Suppress build output (!process.env.CI recommended) | | webpack.treeshake.* | object | Tree-shake SDK features (webpack only, not Turbopack) |

Environment Variables

| Variable | Runtime | Purpose | |----------|---------|---------| | NEXT_PUBLIC_SENTRY_DSN | Client | DSN for browser Sentry init (public) | | SENTRY_DSN | Server / Edge | DSN for server/edge Sentry init | | SENTRY_AUTH_TOKEN | Build | Source map upload auth token (secret) | | SENTRY_ORG | Build | Org slug (alternative to org in config) | | SENTRY_PROJECT | Build | Project slug (alternative to project in config) | | SENTRY_RELEASE | Server | Release version string (auto-detected from git) | | NEXT_RUNTIME | Server / Edge | "nodejs" or "edge" (set by Next.js internally) |

---

Phase 4: Cross-Link

After completing Next.js setup, check for companion services:

# Check for backend services in adjacent directories
ls ../backend ../server ../api ../services 2>/dev/null

# Check for backend language indicators
cat ../go.mod 2>/dev/null | head -3
cat ../requirements.txt ../pyproject.toml 2>/dev/null | head -3
cat ../Gemfile 2>/dev/null | head -3
cat ../pom.xml ../build.gradle 2>/dev/null | head -3

If a backend is found, suggest the matching SDK skill:

| Backend detected | Suggest skill | |-----------------|--------------| | Go (go.mod) | sentry-go-sdk | | Python (requirements.txt, pyproject.toml) | sentry-python-sdk | | Ruby (Gemfile) | sentry-ruby-sdk | | Java/Kotlin (pom.xml, build.gradle) | See docs.sentry.io/platforms/java/ | | Node.js (Express, Fastify, Hapi) | @sentry/node — see docs.sentry.io/platforms/javascript/guides/express/ |

Connecting frontend and backend with the same DSN or linked projects enables distributed tracing — stack traces that span your browser, Next.js server, and backend API in a single trace view.

---

Troubleshooting

| Issue | Cause | Solution | |-------|-------|----------| | Events not appearing | DSN misconfigured or debug: false hiding errors | Set debug: true temporarily; check browser network tab for requests to sentry.io | | Stack traces show minified code | Source maps not uploading | Check SENTRY_AUTH_TOKEN is set; run next build and look for "Source Maps" in build output | | onRequestError not firing | SDK version < 8.28.0 | Upgrade: npm install @sentry/nextjs@latest | | Edge runtime errors missing | sentry.edge.config.ts not loaded | Verify instrumentation.ts imports it when NEXT_RUNTIME === "edge" | | Tunnel route returns 404 | tunnelRoute set but Next.js route missing | The plugin creates it automatically; check you ran next build after adding tunnelRoute | | withSentryConfig tree-shaking breaks build | Turbopack in use | Tree-shaking options only work with webpack; remove webpack.treeshake options when using Turbopack | | global-error.tsx not catching errors | Missing "use client" directive | Add "use client" as the very first line of global-error.tsx | | Session Replay not recording | replayIntegration() missing from client init | Add Sentry.replayIntegration() to integrations in instrumentation-client.ts |