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.

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: 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) 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 Create instrumentation client.ts — Browser / Client Runtime Older docs used sentry.client.config.ts — the current pattern is instrumentation client.ts . Create sentry.server.config.ts — Node.js Server Runtime Create sentry.edge.config.ts — Edge Runtime 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+. 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: Pages Router: Update pages/ error.tsx Wrap next.config.ts with withSentryConfig() Exclude Tunnel Route from Middleware If you have middleware.ts , exclude the tunnel path from auth or redirect logic: 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 Or set in CI secrets: Step 3: Add to .gitignore Step 4: Verify authToken is wired in next.config.ts 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: Then check your [Sentry Issues dashboard](https://sentry.io/issues/) — 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: 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/](https://docs.sentry.io/platforms/java/) Node.js (Express, Fastify, Hapi) @sentry/node — see [docs.sentry.io/platforms/javascript/guides/express/](https://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

sentry-nextjs-sdk