sentry-nextjs-sdk

> [All Skills](../../SKILL_TREE.md) > [SDK Setup](../sentry-sdk-setup/SKILL.md) > 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/](https://docs.sentry.io/platforms/javascript/guides/nextjs/) before implementing. --- ## Phase 1: Detect Run these commands to understand the project before making any recommendations: ```bash # 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](#verification).** If the user skips the wizard, proceed with Option 2 (Manual Setup) below. --- ### Option 2: Manual Setup #### Install ```bash 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`. ```typescript import * as Sentry from "@sentry/nextjs"; Sentry.init({ dsn: process.env.NEXT_PUBLIC_SENTRY_DSN ?? "___PUBLIC_DSN___", dataCollection: { // To disable sending user data and HTTP bodies, uncomment the lines below. For more info visit: // https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/options/#dataCollection // userInfo: false, // httpBodies: [], }, // 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 ```typescript import * as Sentry from "@sentry/nextjs"; Sentry.init({ dsn: process.env.SENTRY_DSN ?? "___DSN___", dataCollection: { // To disable sending user data and HTTP bodies, uncomment the lines below. For more info visit: // https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/options/#dataCollection // userInfo: false, // httpBodies: [], }, 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 ```typescript import * as Sentry from "@sentry/nextjs"; Sentry.init({ dsn: process.env.SENTRY_DSN ?? "___DSN___", dataCollection: { // To disable sending user data and HTTP bodies, uncomment the lines below. For more info visit: // https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/options/#dataCollection // userInfo: false, // httpBodies: [], }, 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+. ```typescript 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: ```tsx "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` ```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()` ```typescript 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: ```typescript // 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 `withSentryConfig` uploads source maps on production builds so stack traces show your original code instead of minified output. The SDK-specific wiring is the `authToken` (plus `widenClientFileUpload`, which improves client stack traces) in `next.config.ts`: ```typescript withSentryConfig(nextConfig, { org: "my-org", project: "my-project", authToken: process.env.SENTRY_AUTH_TOKEN, // from CI env or a gitignored .env.sentry-build-plugin widenClientFileUpload: true, }); ``` `SENTRY_AUTH_TOKEN` is a build-time secret, distinct from the DSN. For creating the token, wiring it into CI, and troubleshooting minified traces, see [`sentry-source-maps`](../sentry-source-maps/SKILL.md). 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` |