sentry-nextjs-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) ```bash npx @sentry/wizard@latest -i nextjs ``` The wizard walks you through login, org/project selection, and auth token setup interactively — no manual token creation needed. It then installs the SDK, creates all necessary config files (`instrumentation-client.ts`, `sentry.server.config.ts`, `sentry.edge.config.ts`, `instrumentation.ts`), wraps `next.config.ts` with `withSentryConfig()`, configures source map upload, and adds a `/sentry-example-page` for verification. **Skip to [Verification](#verification) after running the wizard.** --- ### 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___", 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 ```typescript 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 ```typescript 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+. ```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 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/](https://sentry.io/settings/auth-tokens/) and create a token with `project:releases` and `org:read` scopes. **Step 2: Set environment variables** ```bash # .env.sentry-build-plugin (gitignore this file) SENTRY_AUTH_TOKEN=sntrys_eyJ... ``` Or set in CI secrets: ```bash 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`** ```typescript 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.