sentry-nextjs-sdk

by sentry

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,… npx skills add https://github.com/getsentry/sentry-for-ai --skill sentry-nextjs-sdk Download ZIPGitHub232

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(), 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:

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

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 nextjs

It handles login, org/project selection, SDK installation, config files (instrumentation-client.ts, sentry.server.config.ts, sentry.edge.config.ts, instrumentation.ts), next.config.ts wrapping, 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 --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___",

 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: 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");
 }
}

// 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 (
 
 
 
 
 
 );
}

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 ;
}

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.

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