Next.js

Learn how to set up and configure Sentry in your Next.js application using the installation wizard, capture your first errors, logs and traces and view them in Sentry.

Sentry Agent Skills

Install Sentry's agent skills to teach your AI coding assistant how to set up and use Sentry in your Next.js application.

Copied
npx @sentry/dotagents add getsentry/sentry-agent-skills --all

See the full list of available skills and installation docs for more details.

You need:

Run the Sentry wizard to automatically configure Sentry in your Next.js application:

Copied
npx @sentry/wizard@latest -i nextjs

The wizard will prompt you to select features. Choose the ones you want to enable:

Prefer to set things up yourself? Check out the Manual Setup guide.

The wizard configured Sentry for all Next.js runtime environments and created files to test your setup.

Next.js runs code in different environments. The wizard creates separate initialization files for each:

  • Client (instrumentation-client.ts) — Runs in the browser
  • Server (sentry.server.config.ts) — Runs in Node.js
  • Edge (sentry.edge.config.ts) — Runs in edge runtimes
instrumentation-client.ts
Copied
import * as Sentry from "@sentry/nextjs";

Sentry.init({
  dsn: "___PUBLIC_DSN___",

  // Adds request headers and IP for users
  sendDefaultPii: true,
  // ___PRODUCT_OPTION_START___ performance
  tracesSampleRate: process.env.NODE_ENV === "development" ? 1.0 : 0.1,
  // ___PRODUCT_OPTION_END___ performance
  // ___PRODUCT_OPTION_START___ session-replay
  replaysSessionSampleRate: 0.1,
  replaysOnErrorSampleRate: 1.0,
  // ___PRODUCT_OPTION_END___ session-replay
  // ___PRODUCT_OPTION_START___ logs
  enableLogs: true,
  // ___PRODUCT_OPTION_END___ logs
    // ___PRODUCT_OPTION_START___ session-replay
    Sentry.replayIntegration(),
    // ___PRODUCT_OPTION_END___ session-replay
});

The instrumentation.ts file registers your server and edge configurations with Next.js.

instrumentation.ts
Copied
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;

Your next.config.ts is wrapped with withSentryConfig to enable source map uploads, tunneling (to avoid ad-blockers), and other build-time features.

next.config.ts
Copied
import { withSentryConfig } from "@sentry/nextjs";

export default withSentryConfig(nextConfig, {
  org: "___ORG_SLUG___",
  project: "___PROJECT_SLUG___",

  // Upload source maps for readable stack traces
  authToken: process.env.SENTRY_AUTH_TOKEN,

  // Route Sentry requests through your server (avoids ad-blockers)
  tunnelRoute: "/monitoring",

  silent: !process.env.CI,
});

The wizard creates app/global-error.tsx to capture React rendering errors in your App Router application.

app/global-error.tsx
Copied
"use client";

import * as Sentry from "@sentry/nextjs";
import { useEffect } from "react";

export default function GlobalError({
  error,
}: {
  error: Error & { digest?: string };
}) {
  useEffect(() => {
    Sentry.captureException(error);
  }, [error]);

  return (
    <html>
      <body>
        <h1>Something went wrong!</h1>
      </body>
    </html>
  );
}

The wizard creates .env.sentry-build-plugin with your auth token for source map uploads. This file is automatically added to .gitignore.

For CI/CD, set the SENTRY_AUTH_TOKEN environment variable in your build system.

.env.sentry-build-plugin
Copied
SENTRY_AUTH_TOKEN=sntrys_eyJ...

The wizard creates /sentry-example-page with a button that triggers a test error. Use this to verify your setup.

Copied
app/
├── sentry-example-page/
│   └── page.tsx       # Test page with error button
└── api/
    └── sentry-example-api/
        └── route.ts   # Test API route

The example page tests all your enabled features with a single action:

  1. Start your dev server:
Copied
npm run dev

  1. Visit localhost:3000/sentry-example-page

  2. Click "Throw Sample Error"

Errors — Open Issues

You should see "This is a test error" with a full stack trace pointing to your source code.

Tracing — Open Traces

You should see the page load trace and the button click span. Learn more about custom spans.

Session Replay — Open Replays

Watch a video-like recording of your session, including the moment the error occurred. Learn more about Session Replay configuration.

Logs — Open Logs NEW

See structured log entries from your application. You can send logs from anywhere:

Copied
Sentry.logger.info("User action", { userId: "123" });
Sentry.logger.warn("Slow response", { duration: 5000 });
Sentry.logger.error("Operation failed", { reason: "timeout" });

Learn more about Logs configuration.

Are you having problems setting up the SDK?

You've successfully integrated Sentry into your Next.js application! Here's what to explore next:

Previous
Welcome to Sentry
Next
Manual Setup
Was this helpful?
Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").