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:
cat package.json | grep -E '"next"|"@sentry/'
ls src/app app src/pages pages 2>/dev/null
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
ls next.config.ts next.config.js next.config.mjs 2>/dev/null
find . -name "global-error.tsx" -o -name "_error.tsx" 2>/dev/null | grep -v node_modules
cat package.json | grep -E '"turbopack"|"webpack"'
cat package.json | grep -E '"pino"|"winston"|"bunyan"'
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)
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 after running the wizard.
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,
tracesSampleRate: process.env.NODE_ENV === "development" ? 1.0 : 0.1,
replaysSessionSampleRate: 0.1,
replaysOnErrorSampleRate: 1.0,
enableLogs: true,
integrations: [
Sentry.replayIntegration(),
],
});
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,
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");
}
}
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,
