sentry-nextjs-sdk
Skill19 starsChanged 58 days agoMITView on GitHub
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.
- Reads credentials
- Installs packages
4 other projects use a version of this, 1 of them edited.
Adopted by
Most recently taken up by
- patinaproject/skillsword for word, first seen Oct 15, 2026
- getsentry/sentry-for-aiword for word, first seen Oct 13, 2026
- gerald-donkor/poli-intelword for word, first seen Oct 11, 2026
- getsentry/sentry-agent-skillsedited, first seen Feb 28, 2026
Other versions4 projects use a version of this.
Word for word · 3
- getsentry/sentry-for-ai★ 276100% same
- gerald-donkor/poli-intel★ 1100% same
- patinaproject/skills★ 1100% same
Edited · 1
- getsentry/sentry-agent-skills★ 2189% same
Wrote their own version · 0
None found.
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository87 other files it gives its agents.
- .agents/skills/vercel-optimize/AGENTS.mdAGENTS.md
- block-kitSkill
- cloudflare-deploySkill
- connect-recommendSkill
- connect-required-verification-informationSkill
- create-slack-appSkill
- deploy-to-vercelSkill
- gws-calendar-agendaSkill
- gws-calendar-insertSkill
- gws-calendarSkill
- gws-chat-sendSkill
- gws-chatSkill
- gws-docsSkill
- gws-docs-writeSkill
- gws-driveSkill
- gws-drive-uploadSkill
- gws-gmail-forwardSkill
- gws-gmail-readSkill
- gws-gmail-reply-allSkill
- gws-gmail-replySkill
- gws-gmail-sendSkill
- gws-gmailSkill
- gws-gmail-triageSkill
- gws-gmail-watchSkill
- gws-peopleSkill
- gws-sharedSkill
- gws-sheets-appendSkill
- gws-sheets-readSkill
- gws-sheetsSkill
- gws-tasksSkill
- gws-workflow-email-to-taskSkill
- gws-workflow-file-announceSkill
- gws-workflow-meeting-prepSkill
- gws-workflowSkill
- gws-workflow-standup-reportSkill
- gws-workflow-weekly-digestSkill
- linearSkill
- netlify-deploySkill
- notion-knowledge-captureSkill
- notion-meeting-intelligenceSkill
- notion-research-documentationSkill
- notion-spec-to-implementationSkill
- rampSkill
- render-deploySkill
- sentry-android-sdkSkill
- sentry-browser-sdkSkill
- sentry-cloudflare-sdkSkill
- sentry-cocoa-sdkSkill
- sentry-create-alertSkill
- sentry-debug-issueSkill
- sentry-dotnet-sdkSkill
- sentry-elixir-sdkSkill
- sentry-fix-issuesSkill
- sentry-flutter-sdkSkill
- sentry-get-startedSkill
- sentry-go-sdkSkill
- sentry-nestjs-sdkSkill
- sentry-node-sdkSkill
- sentry-php-sdkSkill
- sentry-python-sdkSkill
- The first 60 shown.
The file
We split this skill into the rules it gives an agent
6 rules. About 0 are common, 4 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 31
Run these commands to understand the project before making any recommendations:
- Distinctive: line 122
If the user skips the wizard, proceed with Option 2 (Manual Setup) below.
- Very specific: line 323
If you have middleware.ts, exclude the tunnel path from auth or redirect logic:
- Distinctive: line 420
After wizard or manual setup, verify Sentry is working:
- Very specific: line 447
After completing Next.js setup, check for companion services:
- Distinctive: line 460
If a backend is found, suggest the matching SDK skill:
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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(), orglobal-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 -3What 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 whenpino/winstonor log search is needed - ⚡ Profiling — continuous profiling; requires
Document-Policy: js-profilingheader - ⚡ 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 nextjsIt handles login, org/project selection, SDK installation, config files (
instrumentation-client.ts,sentry.server.config.ts,sentry.edge.config.ts,instrumentation.ts),next.config.tswrapping, 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 --saveCreate instrumentation-client.ts — Browser / Client Runtime
Older docs used
sentry.client.config.ts— the current pattern isinstrumentation-client.ts.
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
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
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: trueinnext.configfor 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
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:
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.
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 |
| Metrics | references/metrics.md | Custom counters, gauges, distributions via Sentry.metrics.* |
For each feature: read the reference file, follow its steps exactly, and verify before moving on.
Configuration 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 |
dataCollection | object | conservative unless set | Fine-grained control over auto-collected categories (userInfo, cookies, httpHeaders, httpBodies, queryParams, genAI). When omitted, the SDK falls back to sendDefaultPii (default false). Passing the object — even {} — flips unset categories to their permissive defaults; opt out per category. |
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) |
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 |
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 -3If 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 |
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

