Agent skills
sentry-nextjs-sdk

Agent skill

sentry-nextjs-sdk

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.

View SKILL.md on GitHub Repository

Stars 19

Forks 2

Install this agent skill to your Project

npx add-skill https://github.com/getsentry/sentry-agent-skills/tree/main/skills/sentry-nextjs-sdk

SKILL.md

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:

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 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/ 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.

Verification

After wizard or manual setup, verify Sentry is working:

typescript

// 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

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:

bash

# 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 -3

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/
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`

Maintainer

getsentry Core maintainer

Source details

Full Name: getsentry/sentry-agent-skills
Branch: main
Path in repo: skills/sentry-nextjs-sdk
Topics: tag-production

Featured Tools

Join Our Newsletter

Create Sentry alerts using the workflow engine API. Use when asked to create alerts, set up notifications, configure issue priority alerts, or build workflow automations. Supports email, Slack, PagerDuty, Discord, and other notification actions.

19 2

Explore

Didn't find tool you were looking for?

Search AI Tools

Install this agent skill to your Project

SKILL.md

Sentry Next.js SDK

Invoke This Skill When

Phase 1: Detect

Phase 2: Recommend

Phase 3: Guide

Option 1: Wizard (Recommended)

Option 2: Manual Setup

Install

Create instrumentation-client.ts — Browser / Client Runtime

Create sentry.server.config.ts — Node.js Server Runtime

Create sentry.edge.config.ts — Edge Runtime

Create instrumentation.ts — Server-Side Registration Hook

App Router: Create app/global-error.tsx

Pages Router: Update pages/_error.tsx

Wrap next.config.ts with withSentryConfig()

Exclude Tunnel Route from Middleware

Source Maps Setup

For Each Agreed Feature

Verification

Config Reference

Sentry.init() Options

withSentryConfig() Options

Environment Variables

Phase 4: Cross-Link

Troubleshooting

Recommended Agent Skills

sentry-pr-code-review

sentry-dotnet-sdk

sentry-cocoa-sdk

sentry-svelte-sdk

sentry-setup-ai-monitoring

sentry-create-alert

Create `instrumentation-client.ts` — Browser / Client Runtime

Create `sentry.server.config.ts` — Node.js Server Runtime

Create `sentry.edge.config.ts` — Edge Runtime

Create `instrumentation.ts` — Server-Side Registration Hook

App Router: Create `app/global-error.tsx`

Pages Router: Update `pages/_error.tsx`

Wrap `next.config.ts` with `withSentryConfig()`

`Sentry.init()` Options

`withSentryConfig()` Options