sentry-nextjs-sdk

$2b

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](#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___",

  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

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

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

  }

}

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

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

# .env.sentry-build-plugin  (gitignore this file)

SENTRY_AUTH_TOKEN=sntrys_eyJ...

Or set in CI secrets:

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

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

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

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:

# 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