diff --git a/docs/platforms/javascript/guides/nextjs/configuration/build/index.mdx b/docs/platforms/javascript/guides/nextjs/configuration/build/index.mdx
index ee94a816e83c28..aad7e00f1e30bc 100644
--- a/docs/platforms/javascript/guides/nextjs/configuration/build/index.mdx
+++ b/docs/platforms/javascript/guides/nextjs/configuration/build/index.mdx
@@ -16,7 +16,7 @@ keywords:
]
---
-The Sentry Next.js SDK supports automatic code injection and source map upload during your app's build process using the `withSentryConfig` wrapper in your Next.js configuration file (`next.config.js` or `next.config.mjs`). For information on updating the configuration, see [Extend Next.js Configuration](../../manual-setup/#extend-your-nextjs-configuration).
+The Sentry Next.js SDK supports automatic code injection and source map upload during your app's build process using the `withSentryConfig` wrapper in your Next.js configuration file (`next.config.js` or `next.config.mjs`). For information on updating the configuration, see the [Manual Setup guide](/platforms/javascript/guides/nextjs/manual-setup/#configure).
## Available Options
diff --git a/docs/platforms/javascript/guides/nextjs/index.mdx b/docs/platforms/javascript/guides/nextjs/index.mdx
index ecbbfc013d52bb..b36cdc3411c5fa 100644
--- a/docs/platforms/javascript/guides/nextjs/index.mdx
+++ b/docs/platforms/javascript/guides/nextjs/index.mdx
@@ -1,6 +1,6 @@
---
title: "Next.js"
-description: Learn how to set up and configure Sentry in your Next.js application using the installation wizard, capture your first errors, and view them in Sentry.
+description: 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.
sdk: sentry.javascript.nextjs
categories:
- javascript
@@ -17,120 +17,134 @@ categories:
## Install
-
-
-
-
-To install Sentry using the installation wizard, run the command on the right within your project directory.
-
-The wizard guides you through the setup process, asking you to enable additional (optional) Sentry features for your application beyond error monitoring.
-
-This guide assumes that you enable all features and allow the wizard to create an example page and route. You can add or remove features at any time, but setting them up now will save you the effort of configuring them manually later.
-
-
-
-- Creates config files with the default `Sentry.init()` calls for all runtimes (Node.js, Browser, and Edge)
-- Adds a Next.js instrumentation hook to your project (`instrumentation.ts`)
-- Creates or updates your Next.js config with the default Sentry settings
-- Creates error handling components (`global-error.(jsx|tsx)` and `_error.jsx` for the Pages Router) if they don't already exist
-- Creates `.sentryclirc` with an auth token to upload source maps (this file is automatically added to `.gitignore`)
-- Adds an example page and route to your application to help verify your Sentry setup
-
-
-
-
-
+Run the Sentry wizard to automatically configure Sentry in your Next.js application:
```bash
npx @sentry/wizard@latest -i nextjs
```
-
-
-
-
-## Configure
-
-If you prefer to configure Sentry manually, here are the configuration files the wizard would create:
-
-In addition to capturing errors, you can monitor interactions between multiple services or applications by [enabling tracing](/concepts/key-terms/tracing/). You can also get to the root of an error or performance issue faster, by watching a video-like reproduction of a user session with [session replay](/product/explore/session-replay/web/getting-started/).
-
-Select which Sentry features you'd like to install in addition to Error Monitoring to get the corresponding installation and configuration instructions below.
+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](/platforms/javascript/guides/nextjs/manual-setup/) guide.
+
+## What the Wizard Created
+
+The wizard configured Sentry for all Next.js runtime environments and created files to test your setup.
+
-### Client-Side Configuration
+### SDK Initialization
-The wizard creates a client configuration file that initializes the Sentry SDK in your browser.
+Next.js runs code in different environments. The wizard creates separate initialization files for each:
-The configuration includes your DSN (Data Source Name), which connects your app to your Sentry project, and enables the features you selected during installation.
+- **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
-```javascript {tabTitle:Client} {filename:instrumentation-client.(js|ts)}
+```typescript {tabTitle:Client} {filename:instrumentation-client.ts}
import * as Sentry from "@sentry/nextjs";
Sentry.init({
dsn: "___PUBLIC_DSN___",
- // Adds request headers and IP for users, for more info visit:
- // https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/options/#sendDefaultPii
+ // 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
integrations: [
// ___PRODUCT_OPTION_START___ session-replay
- // Replay may only be enabled for the client-side
Sentry.replayIntegration(),
// ___PRODUCT_OPTION_END___ session-replay
- // ___PRODUCT_OPTION_START___ user-feedback
- Sentry.feedbackIntegration({
- // Additional SDK configuration goes in here, for example:
- colorScheme: "system",
- }),
- // ___PRODUCT_OPTION_END___ user-feedback
],
- // ___PRODUCT_OPTION_START___ logs
+});
+```
+
+```typescript {tabTitle:Server} {filename:sentry.server.config.ts}
+import * as Sentry from "@sentry/nextjs";
- // Enable logs to be sent to Sentry
+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___ logs
enableLogs: true,
// ___PRODUCT_OPTION_END___ logs
+});
+```
+```typescript {tabTitle:Edge} {filename:sentry.edge.config.ts}
+import * as Sentry from "@sentry/nextjs";
+
+Sentry.init({
+ dsn: "___PUBLIC_DSN___",
+
+ // Adds request headers and IP for users
+ sendDefaultPii: true,
// ___PRODUCT_OPTION_START___ performance
- // Set tracesSampleRate to 1.0 to capture 100%
- // of transactions for tracing.
- // We recommend adjusting this value in production
- // Learn more at
- // https://docs.sentry.io/platforms/javascript/configuration/options/#traces-sample-rate
- tracesSampleRate: 1.0,
+ tracesSampleRate: process.env.NODE_ENV === "development" ? 1.0 : 0.1,
// ___PRODUCT_OPTION_END___ performance
- // ___PRODUCT_OPTION_START___ session-replay
- // Capture Replay for 10% of all
- // plus for 100% of sessions with an error
- // Learn more at
- // https://docs.sentry.io/platforms/javascript/session-replay/configuration/#general-integration-configuration
- replaysSessionSampleRate: 0.1,
- replaysOnErrorSampleRate: 1.0,
- // ___PRODUCT_OPTION_END___ session-replay
});
+```
+
+
+
+The example above samples 100% of traces in development and 10% in production. Monitor your [usage stats](https://sentry.io/orgredirect/organizations/:orgslug/settings/stats/?dataCategory=spans) and adjust `tracesSampleRate` based on your traffic volume. Learn more about [sampling configuration](/platforms/javascript/guides/nextjs/configuration/sampling/).
+
+
+
+
+
+
+
+
+
+### Server-Side Registration
+
+The `instrumentation.ts` file registers your server and edge configurations with Next.js.
+
+
+
+
+```typescript {filename:instrumentation.ts}
+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");
+ }
+}
-// ___PRODUCT_OPTION_START___ performance
-export const onRouterTransitionStart = Sentry.captureRouterTransitionStart;
-// ___PRODUCT_OPTION_END___ performance
+export const onRequestError = Sentry.captureRequestError;
```
@@ -139,92 +153,189 @@ export const onRouterTransitionStart = Sentry.captureRouterTransitionStart;
-### Server-Side Configuration
+### Next.js Configuration
+
+Your `next.config.ts` is wrapped with `withSentryConfig` to enable source map uploads, tunneling (to avoid ad-blockers), and other build-time features.
+
+
+
+
+```typescript {filename:next.config.ts}
+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 also creates a server configuration file for Node.js and Edge runtimes.
+### Error Handling
-For more advanced configuration options or to set up Sentry manually, check out our [manual setup guide](/platforms/javascript/guides/nextjs/manual-setup/).
+The wizard creates `app/global-error.tsx` to capture React rendering errors in your App Router application.
-```javascript {tabTitle:Server} {filename:sentry.server.config.(js|ts)}
+```tsx {filename:app/global-error.tsx}
+"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 (
+
+
+
Something went wrong!
+
+
+ );
+}
+```
-Sentry.init({
- dsn: "___PUBLIC_DSN___",
+
+
- // Adds request headers and IP for users, for more info visit:
- // https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/options/#sendDefaultPii
- sendDefaultPii: true,
- // ___PRODUCT_OPTION_START___ logs
+
+
- // Enable logs to be sent to Sentry
- enableLogs: true,
- // ___PRODUCT_OPTION_END___ logs
+### Source Maps
- // ___PRODUCT_OPTION_START___ performance
- // Set tracesSampleRate to 1.0 to capture 100%
- // of transactions for tracing.
- // We recommend adjusting this value in production
- // Learn more at
- // https://docs.sentry.io/platforms/javascript/configuration/options/#traces-sample-rate
- tracesSampleRate: 1.0,
- // ___PRODUCT_OPTION_END___ performance
-});
+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.
+
+
+
+
+```bash {tabTitle:Local Development} {filename:.env.sentry-build-plugin}
+SENTRY_AUTH_TOKEN=sntrys_eyJ...
+```
+
+```bash {tabTitle:CI/CD}
+# Set as environment variable in your CI/CD system
+SENTRY_AUTH_TOKEN=sntrys_eyJ...
```
+
+
+
+
+### Example Page
+
+The wizard creates `/sentry-example-page` with a button that triggers a test error. Use this to verify your setup.
+
+
+
+
+```
+app/
+├── sentry-example-page/
+│ └── page.tsx # Test page with error button
+└── api/
+ └── sentry-example-api/
+ └── route.ts # Test API route
+```
+
+
+
+
## Verify Your Setup
-
+
-If you haven't tested your Sentry configuration yet, let's do it now. You can confirm that Sentry is working properly and sending data to your Sentry project by using the example page and route created by the installation wizard:
+The example page tests all your enabled features with a single action:
-1. Open the example page `/sentry-example-page` in your browser. For most Next.js applications, this will be at localhost.
-2. Click the "Throw error" button. This triggers two errors:
+1. Start your dev server:
-- a frontend error
-- an error within the API route
+```bash
+npm run dev
+```
-Sentry captures both of these errors for you. Additionally, the button click starts a performance trace to measure the time it takes for the API request to complete.
+2. Visit [localhost:3000/sentry-example-page](http://localhost:3000/sentry-example-page)
-
+3. Click **"Throw Sample Error"**
-Don't forget to explore the example files' code in your project to understand what's happening after your button click.
+### Check Your Data in Sentry
-
+**Errors** — [Open Issues](https://sentry.io/orgredirect/organizations/:orgslug/issues/)
-### View Captured Data in Sentry
+You should see "This is a test error" with a full stack trace pointing to your source code.
-Now, head over to your project on [Sentry.io](https://sentry.io) to view the collected data (it takes a couple of moments for the data to appear).
+
-
+**Tracing** — [Open Traces](https://sentry.io/orgredirect/organizations/:orgslug/explore/traces/)
-
+You should see the page load trace and the button click span. Learn more about [custom spans](/platforms/javascript/guides/nextjs/tracing/instrumentation/custom-instrumentation/).
-## Next Steps
+
+
+
+
+**Session Replay** — [Open Replays](https://sentry.io/orgredirect/organizations/:orgslug/replays/)
+
+Watch a video-like recording of your session, including the moment the error occurred. Learn more about [Session Replay configuration](/platforms/javascript/guides/nextjs/session-replay/).
-At this point, you should have integrated Sentry into your Next.js application and should already be sending error and performance data to your Sentry project.
+
-Now's a good time to customize your setup and look into more advanced topics.
-Our next recommended steps for you are:
+
-- Learn about [instrumenting Next.js server actions](/platforms/javascript/guides/nextjs/apis/#server-actions)
-- Learn how to [manually capture errors](/platforms/javascript/guides/nextjs/usage/)
-- Continue to [customize your configuration](/platforms/javascript/guides/nextjs/configuration/)
-- Get familiar with [Sentry's product features](/product) like tracing, insights, and alerts
-- Learn how to [set up Sentry for Vercel's micro frontends](/platforms/javascript/guides/nextjs/best-practices/micro-frontends/)
-- Learn more about our [Vercel integration](/organization/integrations/deployment/vercel/)
+**Logs** — [Open Logs](https://sentry.io/orgredirect/organizations/:orgslug/explore/logs/)
-
+See structured log entries from your application. You can send logs from anywhere:
+
+```typescript
+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](/platforms/javascript/guides/nextjs/logs/).
+
+
+
+
- If you encountered issues with our installation wizard, try [setting up Sentry manually](/platforms/javascript/guides/nextjs/manual-setup/)
-- [Get support](https://sentry.zendesk.com/hc/en-us/)
+- Check [Troubleshooting](/platforms/javascript/guides/nextjs/troubleshooting/) for common issues
+- [Get support](https://sentry.io/support/)
+## Next Steps
+
+You've successfully integrated Sentry into your Next.js application! Here's what to explore next:
+
+- [Logs Integrations](/platforms/javascript/guides/nextjs/logs/#integrations) - Connect popular logging libraries like Pino, Winston, and Bunyan
+- [Distributed Tracing](/platforms/javascript/guides/nextjs/tracing/distributed-tracing/) - Trace requests across services and microservices
+- [AI Agent Monitoring](/platforms/javascript/guides/nextjs/tracing/instrumentation/ai-agents-module/) - Monitor AI agents built with Vercel AI SDK, LangChain, and more
+- [Connect GitHub + Seer](/organization/integrations/source-code-mgmt/github/#installing-github) - Enable AI-powered [root cause analysis](/product/ai-in-sentry/seer/) by connecting your GitHub repository
+- [Configuration Options](/platforms/javascript/guides/nextjs/configuration/) - Explore extended SDK configuration options
+
diff --git a/docs/platforms/javascript/guides/nextjs/manual-setup.mdx b/docs/platforms/javascript/guides/nextjs/manual-setup.mdx
deleted file mode 100644
index 3e949a48199d19..00000000000000
--- a/docs/platforms/javascript/guides/nextjs/manual-setup.mdx
+++ /dev/null
@@ -1,637 +0,0 @@
----
-title: "Manual Setup"
-sidebar_order: 1
-description: "Learn how to manually set up Sentry in your Next.js app and capture your first errors."
----
-
-
- For the fastest setup, we recommend using the [wizard
- installer](/platforms/javascript/guides/nextjs).
-
-
-
-
-## Step 1: Install
-
-### Install the Sentry SDK
-
-Run the command for your preferred package manager to add the Sentry SDK to your application:
-
-```bash {tabTitle:npm}
-npm install @sentry/nextjs --save
-```
-
-```bash {tabTitle:yarn}
-yarn add @sentry/nextjs
-```
-
-```bash {tabTitle:pnpm}
-pnpm add @sentry/nextjs
-```
-
-## Step 2: Configure
-
-Choose the features you want to configure, and this guide will show you how:
-
-
-
-
-
-### Apply Instrumentation to Your App
-
-Extend your app's default Next.js options by adding `withSentryConfig` into your `next.config.(js|mjs)` file:
-
-```JavaScript {tabTitle:CJS} {filename:next.config.js}
-const { withSentryConfig } = require("@sentry/nextjs");
-
-const nextConfig = {
- // Your existing Next.js configuration
-};
-
-// Make sure adding Sentry options is the last code to run before exporting
-module.exports = withSentryConfig(nextConfig, {
- org: "___ORG_SLUG___",
- project: "___PROJECT_SLUG___",
-
- // Only print logs for uploading source maps in CI
- // Set to `true` to suppress logs
- silent: !process.env.CI,
-
- // Automatically tree-shake Sentry logger statements to reduce bundle size
- disableLogger: true,
-});
-```
-
-```JavaScript {tabTitle:ESM} {filename:next.config.mjs}
-import { withSentryConfig } from "@sentry/nextjs";
-
-const nextConfig = {
- // Your existing Next.js configuration
-};
-
-// Make sure adding Sentry options is the last code to run before exporting
-export default withSentryConfig(nextConfig, {
- org: "___ORG_SLUG___",
- project: "___PROJECT_SLUG___",
-
- // Only print logs for uploading source maps in CI
- // Set to `true` to suppress logs
- silent: !process.env.CI,
-
- // Automatically tree-shake Sentry logger statements to reduce bundle size
- disableLogger: true,
-});
-```
-
-
-
-### Initialize Sentry Client-Side and Server-Side SDKs
-
-Create three files in your application's root directory:
-
-- `sentry.server.config.(js|ts)`
-- `sentry.edge.config.(js|ts)`
-- `instrumentation-client.(js|ts)`
- - If you previously had a file called `sentry.client.config.(js|ts)`, you can safely rename this to `instrumentation-client.(js|ts)` for all Next.js versions.
-
-Add the following initialization code into each respective file:
-
-
- These files run in different environments (browser, server, edge) and are
- slightly different, so copy them carefully.
-
-
-```javascript {tabTitle:Client} {filename:instrumentation-client.(js|ts)}
-import * as Sentry from "@sentry/nextjs";
-
-Sentry.init({
- dsn: "___PUBLIC_DSN___",
-
- // Adds request headers and IP for users, for more info visit:
- // https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/options/#sendDefaultPii
- sendDefaultPii: true,
- // ___PRODUCT_OPTION_START___ performance
-
- // Set tracesSampleRate to 1.0 to capture 100%
- // of transactions for tracing.
- // We recommend adjusting this value in production
- // Learn more at
- // https://docs.sentry.io/platforms/javascript/configuration/options/#traces-sample-rate
- tracesSampleRate: 1.0,
- // ___PRODUCT_OPTION_END___ performance
- integrations: [
- // ___PRODUCT_OPTION_START___ session-replay
- // Replay may only be enabled for the client-side
- Sentry.replayIntegration(),
- // ___PRODUCT_OPTION_END___ session-replay
- // ___PRODUCT_OPTION_START___ user-feedback
- Sentry.feedbackIntegration({
- // Additional SDK configuration goes in here, for example:
- colorScheme: "system",
- }),
- // ___PRODUCT_OPTION_END___ user-feedback
- ],
- // ___PRODUCT_OPTION_START___ session-replay
-
- // Capture Replay for 10% of all sessions,
- // plus for 100% of sessions with an error
- // Learn more at
- // https://docs.sentry.io/platforms/javascript/session-replay/configuration/#general-integration-configuration
- replaysSessionSampleRate: 0.1,
- replaysOnErrorSampleRate: 1.0,
- // ___PRODUCT_OPTION_END___ session-replay
- // ___PRODUCT_OPTION_START___ logs
-
- // Enable logs to be sent to Sentry
- enableLogs: true,
- // ___PRODUCT_OPTION_END___ logs
- // Note: if you want to override the automatic release value, do not set a
- // `release` value here - use the environment variable `SENTRY_RELEASE`, so
- // that it will also get attached to your source maps
-});
-
-// This export will instrument router navigations, and is only relevant if you enable tracing.
-// `captureRouterTransitionStart` is available from SDK version 9.12.0 onwards
-export const onRouterTransitionStart = Sentry.captureRouterTransitionStart;
-```
-
-```javascript {tabTitle:Server} {filename:sentry.server.config.(js|ts)}
-import * as Sentry from "@sentry/nextjs";
-
-Sentry.init({
- dsn: "___PUBLIC_DSN___",
-
- // Adds request headers and IP for users, for more info visit:
- // https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/options/#sendDefaultPii
- sendDefaultPii: true,
- // ___PRODUCT_OPTION_START___ performance
-
- // Set tracesSampleRate to 1.0 to capture 100%
- // of transactions for tracing.
- // We recommend adjusting this value in production
- // Learn more at
- // https://docs.sentry.io/platforms/javascript/configuration/options/#traces-sample-rate
- tracesSampleRate: 1.0,
- // ___PRODUCT_OPTION_END___ performance
- // ___PRODUCT_OPTION_START___ logs
-
- // Enable logs to be sent to Sentry
- enableLogs: true,
- // ___PRODUCT_OPTION_END___ logs
-
- // ...
-
- // Note: if you want to override the automatic release value, do not set a
- // `release` value here - use the environment variable `SENTRY_RELEASE`, so
- // that it will also get attached to your source maps
-});
-```
-
-```javascript {tabTitle:Edge} {filename:sentry.edge.config.(js|ts)}
-import * as Sentry from "@sentry/nextjs";
-
-Sentry.init({
- dsn: "___PUBLIC_DSN___",
-
- // Adds request headers and IP for users, for more info visit:
- // https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/options/#sendDefaultPii
- sendDefaultPii: true,
- // ___PRODUCT_OPTION_START___ performance
-
- // Set tracesSampleRate to 1.0 to capture 100%
- // of transactions for tracing.
- // We recommend adjusting this value in production
- // Learn more at
- // https://docs.sentry.io/platforms/javascript/configuration/options/#traces-sample-rate
- tracesSampleRate: 1.0,
- // ___PRODUCT_OPTION_END___ performance
- // ___PRODUCT_OPTION_START___ logs
-
- // Enable logs to be sent to Sentry
- enableLogs: true,
- // ___PRODUCT_OPTION_END___ logs
-
- // ...
-
- // Note: if you want to override the automatic release value, do not set a
- // `release` value here - use the environment variable `SENTRY_RELEASE`, so
- // that it will also get attached to your source maps
-});
-```
-
-
- Include your DSN directly in these files, or use a _public_ environment
- variable like `NEXT_PUBLIC_SENTRY_DSN`.
-
-
-### Register Sentry Server-Side SDK Initialization
-
-Create a [Next.js Instrumentation file](https://nextjs.org/docs/app/building-your-application/optimizing/instrumentation) named `instrumentation.(js|ts)` in your project root or inside the `src` folder if you have one. Import your server and edge configurations, making sure that the imports point to your specific files:
-
-```javascript {filename:instrumentation.(js|ts)}
-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");
- }
-}
-```
-
-
- If you want the Sentry SDK to be available on the server side and not on the
- client side, simply delete `instrumentation-client.(js|ts)`. This will prevent
- webpack from pulling in the Sentry-related files when generating the browser
- bundle. Similarly, if you want to opt out of server-side SDK bundling, delete
- the `sentry.server.config.js` and `sentry.edge.config.js` files. Make sure to
- remove any imports of these files from `instrumentation.ts`.
-
-
-## Step 3: Capture React Render Errors
-
-To capture React render errors, you need to add error components for the App Router and the Pages Router.
-
-### App Router
-
-Create or update the `global-error.(tsx|jsx)` file to define a [custom Next.js GlobalError component](https://nextjs.org/docs/app/building-your-application/routing/error-handling):
-
-```tsx {filename:global-error.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 (
-
-
- {/* `NextError` is the default Next.js error page component. Its type
- definition requires a `statusCode` prop. However, since the App Router
- does not expose status codes for errors, we simply pass 0 to render a
- generic error message. */}
-
-
-
- );
-}
-```
-
-```jsx {filename:global-error.jsx}
-"use client";
-
-import * as Sentry from "@sentry/nextjs";
-import NextError from "next/error";
-import { useEffect } from "react";
-
-export default function GlobalError({ error }) {
- useEffect(() => {
- Sentry.captureException(error);
- }, [error]);
-
- return (
-
-
- {/* This is the default Next.js error component. */}
-
-
-
- );
-}
-```
-
-#### Errors from Nested React Server Components
-
-
- Requires `@sentry/nextjs` version `8.28.0` or higher and Next.js 15.
-
-
-To capture errors from nested React Server Components, use the [`onRequestError`](https://nextjs.org/docs/app/api-reference/file-conventions/instrumentation#onrequesterror-optional) hook in `instrumentation.(js|ts)` and pass all arguments to the `captureRequestError` function:
-
-```TypeScript {filename:instrumentation.ts}
-import * as Sentry from "@sentry/nextjs";
-
-export const onRequestError = Sentry.captureRequestError;
-```
-
-```JavaScript {filename:instrumentation.js}
-import * as Sentry from "@sentry/nextjs";
-
-export const onRequestError = Sentry.captureRequestError;
-```
-
-
-You can call `captureRequestError` with all arguments passed to `onRequestError`:
-
-```TypeScript {filename:instrumentation.ts}
-import * as Sentry from "@sentry/nextjs";
-import type { Instrumentation } from "next";
-
-export const onRequestError: Instrumentation.onRequestError = (...args) => {
- Sentry.captureRequestError(...args);
-
- // ... additional logic here
-};
-```
-
-```JavaScript {filename:instrumentation.js}
-import * as Sentry from "@sentry/nextjs";
-
-export const onRequestError = (...args) => {
- Sentry.captureRequestError(...args);
-
- // ... additional logic here
-};
-```
-
-
-
-### Pages Router
-
-Create or update the `_error.(tsx|jsx)` file to define a [custom Next.js error page](https://nextjs.org/docs/pages/building-your-application/routing/custom-error) for the Pages Router like so:
-
-```tsx {filename:_error.tsx}
-import * as Sentry from "@sentry/nextjs";
-import type { NextPage } from "next";
-import type { ErrorProps } from "next/error";
-import Error from "next/error";
-
-const CustomErrorComponent: NextPage = (props) => {
- return ;
-};
-
-CustomErrorComponent.getInitialProps = async (contextData) => {
- // In case this is running in a serverless function, await this in order to give Sentry
- // time to send the error before the lambda exits
- await Sentry.captureUnderscoreErrorException(contextData);
-
- // This will contain the status code of the response
- return Error.getInitialProps(contextData);
-};
-
-export default CustomErrorComponent;
-```
-
-```jsx {filename:_error.jsx}
-import * as Sentry from "@sentry/nextjs";
-import type { NextPage } from "next";
-import type { ErrorProps } from "next/error";
-import Error from "next/error";
-
-const CustomErrorComponent: NextPage = (props) => {
- return ;
-};
-
-CustomErrorComponent.getInitialProps = async (contextData) => {
- // In case this is running in a serverless function, await this in order to give Sentry
- // time to send the error before the lambda exits
- await Sentry.captureUnderscoreErrorException(contextData);
-
- // This will contain the status code of the response
- return Error.getInitialProps(contextData);
-};
-
-export default CustomErrorComponent;
-```
-
-## Step 4: Add Readable Stack Traces With Source Maps (Optional)
-
-Sentry can automatically provide readable stack traces for errors using source maps, requiring a Sentry auth token.
-
-Update your `next.config.(js|mjs)` file with the following options:
-
-```javascript {tabTitle:ESM} {filename:next.config.mjs}
-export default withSentryConfig(nextConfig, {
- org: "___ORG_SLUG___",
- project: "___PROJECT_SLUG___",
-
- // Pass the auth token
- authToken: process.env.SENTRY_AUTH_TOKEN,
- // Upload a larger set of source maps for prettier stack traces (increases build time)
- widenClientFileUpload: true,
-});
-```
-
-```javascript {tabTitle:CJS} {filename:next.config.js}
-module.exports = withSentryConfig(nextConfig, {
- org: "___ORG_SLUG___",
- project: "___PROJECT_SLUG___",
-
- // Pass the auth token
- authToken: process.env.SENTRY_AUTH_TOKEN,
- // Upload a larger set of source maps for prettier stack traces (increases build time)
- widenClientFileUpload: true,
-});
-```
-
-Set the `SENTRY_AUTH_TOKEN` environment variable in your `.env` file:
-
-```sh {filename:.env}
-SENTRY_AUTH_TOKEN=___ORG_AUTH_TOKEN___
-```
-
-
-
-Make sure to keep your auth token secret and out of version control.
-
-
-
-## Step 5: Avoid Ad Blockers With Tunneling (Optional)
-
-You can prevent ad blockers from blocking Sentry events using tunneling. Use the `tunnelRoute` option to add an API endpoint in your application that forwards Sentry events to Sentry servers.
-
-For better ad-blocker evasion, you can either:
-
-- Set `tunnelRoute: true` to automatically generate a random tunnel route for each build, making it harder for ad-blockers to detect and block monitoring requests
-- Set `tunnelRoute: "/my-tunnel-route"` to use a static route of your choosing
-
-```javascript {tabTitle:ESM} {filename:next.config.mjs}
-export default withSentryConfig(nextConfig, {
- // Route browser requests to Sentry through a Next.js rewrite to circumvent ad-blockers.
- // This can increase your server load as well as your hosting bill.
- // Note: Check that the configured route will not match with your Next.js middleware, otherwise reporting of client-side errors will fail.
- tunnelRoute: true, // Generates a random route for each build (recommended)
-});
-```
-
-```javascript {tabTitle:CJS} {filename:next.config.js}
-module.exports = withSentryConfig(nextConfig, {
- // Route browser requests to Sentry through a Next.js rewrite to circumvent ad-blockers.
- // This can increase your server load as well as your hosting bill.
- // Note: Check that the configured route will not match with your Next.js middleware, otherwise reporting of client-side errors will fail.
- tunnelRoute: true, // Generates a random route for each build (recommended)
-});
-```
-
-
- If you're using Turbopack, client-side event recording will fail if your
- Next.js middleware intercepts the configured tunnel route. To fix this, set
- the route to a fixed string (like `/error-monitoring`) and add a negative
- matcher like `(?!error-monitoring)` in your middleware to exclude the tunnel
- route. If you're not using Turbopack, Sentry will automatically skip the
- tunnel route in your middleware.
-
-
-## Step 6: Instrument Vercel Cron Jobs (Optional)
-
-You can automatically create [Cron Monitors](/product/crons/) in Sentry if you have configured [Vercel cron jobs](https://vercel.com/docs/cron-jobs).
-
-Update `withSentryConfig` in your `next.config.(js|mjs)` file with the following option:
-
-```javascript {tabTitle:ESM} {filename:next.config.mjs}
-export default withSentryConfig(nextConfig, {
- automaticVercelMonitors: true,
-});
-```
-
-```javascript {tabTitle:CJS} {filename:next.config.js}
-module.exports = withSentryConfig(nextConfig, {
- automaticVercelMonitors: true,
-});
-```
-
-
-
-Automatic Vercel cron jobs instrumentation currently only supports the Pages Router. App Router route handlers are not yet supported.
-
-
-
-## Step 7: Capture React Component Names (Optional)
-
-You can capture React component names to see which component a user clicked on in Sentry features like Session Replay.
-Update `withSentryConfig` in your `next.config.(js|mjs)` file with the following option:
-
-```javascript {tabTitle:ESM} {filename:next.config.mjs}
-export default withSentryConfig(nextConfig, {
- reactComponentAnnotation: {
- enabled: true,
- },
-});
-```
-
-```javascript {tabTitle:CJS} {filename:next.config.js}
-module.exports = withSentryConfig(nextConfig, {
- reactComponentAnnotation: {
- enabled: true,
- },
-});
-```
-
-## Step 8: Verify
-
-
-
-Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project.
-
-### Issues
-
-To verify that Sentry captures errors and creates issues in your Sentry project, add a test button to an existing page or create a new one:
-
-```jsx
-
-```
-
-
- Open the page in a browser (for most Next.js applications, this will be at
- localhost) and click the button to trigger a frontend error.
-
-
-
-
-
-### Tracing
-
-To test tracing, create a test API route like `/api/sentry-example-api`:
-
-```javascript
-import { NextResponse } from "next/server";
-export const dynamic = "force-dynamic";
-
-// A faulty API route to test Sentry's error monitoring
-export function GET() {
- throw new Error("Sentry Example API Route Error");
- return NextResponse.json({ data: "Testing Sentry Error..." });
-}
-```
-
-Next, update your test button to call this route and throw an error if the response isn't `ok`:
-
-```jsx
-;
-```
-
-Open the page in a browser (for most Next.js applications, this will be at localhost) and click the button to trigger two errors:
-
-- a frontend error
-- an error within the API route
-
-Additionally, this starts a performance trace to measure the time it takes for the API request to complete.
-
-
-
-### View Captured Data in Sentry
-
-Now, head over to your project on [Sentry.io](https://sentry.io) to view the collected data (it takes a couple of moments for the data to appear).
-
-
-
-## Next Steps
-
-At this point, you should have integrated Sentry into your Next.js application and should already be sending data to your Sentry project.
-
-Now's a good time to customize your setup and look into more advanced topics.
-Our next recommended steps for you are:
-
-- Learn about [instrumenting Next.js server actions](/platforms/javascript/guides/nextjs/apis/#server-actions)
-- Configure [server-side auto-instrumentation](/platforms/javascript/guides/nextjs/configuration/build/#nextjs-specific-options)
-- Learn how to [manually capture errors](/platforms/javascript/guides/nextjs/usage/)
-- Continue to [customize your configuration](/platforms/javascript/guides/nextjs/configuration/)
-- Learn more about our [Vercel integration](/organization/integrations/deployment/vercel/)
-- Learn how to [configure Next.js with Sentry for Cloudflare Workers](/platforms/javascript/guides/nextjs/best-practices/deploying-on-cloudflare/)
-
-
-
-- If you encountered issues with setting up Sentry manually, [try our installation wizard](/platforms/javascript/guides/nextjs/)
-- [Get support](https://sentry.zendesk.com/hc/en-us/)
-
-
diff --git a/docs/platforms/javascript/guides/nextjs/manual-setup/index.mdx b/docs/platforms/javascript/guides/nextjs/manual-setup/index.mdx
new file mode 100644
index 00000000000000..8ffd367b7f41cb
--- /dev/null
+++ b/docs/platforms/javascript/guides/nextjs/manual-setup/index.mdx
@@ -0,0 +1,607 @@
+---
+title: "Manual Setup"
+sidebar_order: 1
+description: "Learn how to set up and configure Sentry in your Next.js application, capture your first errors, logs and traces and view them in Sentry."
+sdk: sentry.javascript.nextjs
+categories:
+ - javascript
+ - browser
+ - server
+ - server-node
+---
+
+
+ For the fastest setup, we recommend using the [wizard
+ installer](/platforms/javascript/guides/nextjs).
+
+
+This guide covers manual setup for **Next.js 15+ with Turbopack and App Router**. For other setups, see:
+
+- [Pages Router Setup](/platforms/javascript/guides/nextjs/manual-setup/pages-router/) - For applications using the Pages Router
+- [Webpack Setup](/platforms/javascript/guides/nextjs/manual-setup/webpack-setup/) - For applications not using Turbopack
+
+
+
+Choose the features you want to configure:
+
+
+
+**How this guide works:**
+
+1. **Install** - Add the Sentry SDK to your project
+2. **Configure** - Set up SDK initialization files and Next.js configuration
+3. **Verify** - Test error monitoring and any additional features you enabled
+
+
+
+## Install
+
+
+
+
+
+
+### Install the Sentry SDK
+
+Run the command for your preferred package manager to add the Sentry SDK to your application.
+
+
+
+
+```bash {tabTitle:npm}
+npm install @sentry/nextjs --save
+```
+
+```bash {tabTitle:yarn}
+yarn add @sentry/nextjs
+```
+
+```bash {tabTitle:pnpm}
+pnpm add @sentry/nextjs
+```
+
+
+
+
+
+
+## Configure
+
+
+
+
+
+
+### Apply Instrumentation to Your App
+
+Extend your app's default Next.js options by adding `withSentryConfig` into your `next.config.ts` file.
+
+
+
+
+```typescript {filename:next.config.ts}
+import type { NextConfig } from "next";
+import { withSentryConfig } from "@sentry/nextjs";
+
+const nextConfig: NextConfig = {
+ // Your existing Next.js configuration
+};
+
+export default withSentryConfig(nextConfig, {
+ org: "___ORG_SLUG___",
+ project: "___PROJECT_SLUG___",
+
+ // Only print logs for uploading source maps in CI
+ silent: !process.env.CI,
+});
+```
+
+
+
+
+
+
+
+### Initialize Sentry SDKs
+
+Create the following files in your application's root directory (or `src` folder if you have one):
+
+- `instrumentation-client.ts` - Client-side SDK initialization
+- `sentry.server.config.ts` - Server-side SDK initialization
+- `sentry.edge.config.ts` - Edge runtime SDK initialization
+
+
+ Include your DSN directly in these files, or use a _public_ environment
+ variable like `NEXT_PUBLIC_SENTRY_DSN`.
+
+
+
+
+
+```typescript {tabTitle:Client} {filename:instrumentation-client.ts}
+import * as Sentry from "@sentry/nextjs";
+
+Sentry.init({
+ dsn: "___PUBLIC_DSN___",
+
+ // Adds request headers and IP for users
+ sendDefaultPii: true,
+ // ___PRODUCT_OPTION_START___ performance
+
+ // Capture 100% in dev, 10% in production
+ // Adjust based on your traffic volume
+ tracesSampleRate: process.env.NODE_ENV === "development" ? 1.0 : 0.1,
+ // ___PRODUCT_OPTION_END___ performance
+ integrations: [
+ // ___PRODUCT_OPTION_START___ session-replay
+ Sentry.replayIntegration(),
+ // ___PRODUCT_OPTION_END___ session-replay
+ // ___PRODUCT_OPTION_START___ user-feedback
+ Sentry.feedbackIntegration({
+ colorScheme: "system",
+ }),
+ // ___PRODUCT_OPTION_END___ user-feedback
+ ],
+ // ___PRODUCT_OPTION_START___ session-replay
+
+ // Capture Replay for 10% of all sessions,
+ // plus for 100% of sessions with an error
+ replaysSessionSampleRate: 0.1,
+ replaysOnErrorSampleRate: 1.0,
+ // ___PRODUCT_OPTION_END___ session-replay
+ // ___PRODUCT_OPTION_START___ logs
+
+ // Enable logs to be sent to Sentry
+ enableLogs: true,
+ // ___PRODUCT_OPTION_END___ logs
+});
+
+// ___PRODUCT_OPTION_START___ performance
+// This export will instrument router navigations
+export const onRouterTransitionStart = Sentry.captureRouterTransitionStart;
+// ___PRODUCT_OPTION_END___ performance
+```
+
+```typescript {tabTitle:Server} {filename:sentry.server.config.ts}
+import * as Sentry from "@sentry/nextjs";
+
+Sentry.init({
+ dsn: "___PUBLIC_DSN___",
+
+ // Adds request headers and IP for users
+ sendDefaultPii: true,
+ // ___PRODUCT_OPTION_START___ performance
+
+ // Capture 100% in dev, 10% in production
+ // Adjust based on your traffic volume
+ tracesSampleRate: process.env.NODE_ENV === "development" ? 1.0 : 0.1,
+ // ___PRODUCT_OPTION_END___ performance
+ // ___PRODUCT_OPTION_START___ logs
+
+ // Enable logs to be sent to Sentry
+ enableLogs: true,
+ // ___PRODUCT_OPTION_END___ logs
+});
+```
+
+```typescript {tabTitle:Edge} {filename:sentry.edge.config.ts}
+import * as Sentry from "@sentry/nextjs";
+
+Sentry.init({
+ dsn: "___PUBLIC_DSN___",
+
+ // Adds request headers and IP for users
+ sendDefaultPii: true,
+ // ___PRODUCT_OPTION_START___ performance
+
+ // Capture 100% in dev, 10% in production
+ // Adjust based on your traffic volume
+ tracesSampleRate: process.env.NODE_ENV === "development" ? 1.0 : 0.1,
+ // ___PRODUCT_OPTION_END___ performance
+ // ___PRODUCT_OPTION_START___ logs
+
+ // Enable logs to be sent to Sentry
+ enableLogs: true,
+ // ___PRODUCT_OPTION_END___ logs
+});
+```
+
+
+
+The example above samples 100% of traces in development and 10% in production. Monitor your [usage stats](https://sentry.io/orgredirect/organizations/:orgslug/settings/stats/?dataCategory=spans) and adjust `tracesSampleRate` based on your traffic volume. Learn more about [sampling configuration](/platforms/javascript/guides/nextjs/configuration/sampling/).
+
+
+
+
+
+
+
+
+
+### Register Server-Side SDK
+
+Create a [Next.js Instrumentation file](https://nextjs.org/docs/app/building-your-application/optimizing/instrumentation) named `instrumentation.ts` in your project root (or `src` folder). This file imports your server and edge configurations and exports `onRequestError` to capture server-side errors.
+
+
+ The `onRequestError` hook requires `@sentry/nextjs` version `8.28.0` or higher
+ and Next.js 15.
+
+
+
+
+
+```typescript {filename:instrumentation.ts}
+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");
+ }
+}
+
+// Capture errors from Server Components, middleware, and proxies
+export const onRequestError = Sentry.captureRequestError;
+```
+
+
+
+
+
+
+
+### Capture React Render Errors
+
+Create `app/global-error.tsx` to capture errors that occur anywhere in your App Router application.
+
+
+
+
+
+
+
+
+
+
+
+
+### Server Actions
+
+Wrap your Server Actions with `Sentry.withServerActionInstrumentation()`.
+
+
+
+
+```typescript {filename:app/actions.ts}
+"use server";
+import * as Sentry from "@sentry/nextjs";
+
+export async function submitForm(formData: FormData) {
+ return Sentry.withServerActionInstrumentation(
+ "submitForm", // Action name for Sentry
+ {
+ recordResponse: true, // Include response data
+ },
+ async () => {
+ // Your server action logic
+ const result = await processForm(formData);
+ return { success: true, data: result };
+ }
+ );
+}
+```
+
+
+
+
+
+
+
+### Source Maps (Optional)
+
+Add the `authToken` option to your `next.config.ts` to enable readable stack traces. Set the `SENTRY_AUTH_TOKEN` environment variable in your CI/CD.
+
+
+ Keep your auth token secret and out of version control.
+
+
+
+
+
+```typescript {filename:next.config.ts}
+export default withSentryConfig(nextConfig, {
+ org: "___ORG_SLUG___",
+ project: "___PROJECT_SLUG___",
+
+ // Pass the auth token
+ authToken: process.env.SENTRY_AUTH_TOKEN,
+
+ // Upload a larger set of source maps for prettier stack traces
+ widenClientFileUpload: true,
+});
+```
+
+```sh {filename:.env.local}
+SENTRY_AUTH_TOKEN=___ORG_AUTH_TOKEN___
+```
+
+
+
+
+
+
+
+### Tunneling (Optional)
+
+Prevent ad blockers from blocking Sentry events by routing them through your Next.js server.
+
+
+ This increases server load. Consider the trade-off for your application.
+
+
+
+
+If you're using Next.js middleware (`middleware.ts`) that intercepts requests, exclude the tunnel route:
+
+```typescript {filename:middleware.ts}
+export const config = {
+ matcher: ["/((?!monitoring|_next/static|_next/image|favicon.ico).*)"],
+};
+```
+
+
+
+
+
+
+```typescript {filename:next.config.ts}
+export default withSentryConfig(nextConfig, {
+ // Use a fixed route (recommended)
+ tunnelRoute: "/monitoring",
+});
+```
+
+
+
+
+
+
+## Error Monitoring
+
+Test your error monitoring setup by throwing an error and viewing it in Sentry.
+
+
+
+
+
+
+### Throw a Test Error
+
+Add this button to any page and click it to trigger a test error.
+
+
+
+
+
+
+```jsx
+
+```
+
+
+
+
+
+
+### Verify
+
+Open [**Issues**](https://sentry.io/orgredirect/organizations/:orgslug/issues/) in Sentry to see your test error. [Learn more about capturing errors](/platforms/javascript/guides/nextjs/usage/).
+
+## Verify Additional Features
+
+Based on the features you selected above, verify each one is working correctly.
+
+
+
+
+
+
+
+
+### Session Replay
+
+Session Replay captures video-like reproductions of user sessions. It's configured with `replayIntegration()` in your client config.
+
+By default, Sentry masks all text, inputs, and media. You can customize this in [Privacy Configuration](/platforms/javascript/guides/nextjs/session-replay/privacy/).
+
+**Verify:** Trigger an error or navigate your app, then check [**Replays**](https://sentry.io/orgredirect/organizations/:orgslug/replays/) in Sentry.
+
+
+
+
+```typescript {filename:instrumentation-client.ts}
+Sentry.init({
+ dsn: "___PUBLIC_DSN___",
+
+ integrations: [
+ Sentry.replayIntegration({
+ maskAllText: true,
+ maskAllInputs: true,
+ blockAllMedia: true,
+ }),
+ ],
+
+ replaysSessionSampleRate: 0.1,
+ replaysOnErrorSampleRate: 1.0,
+});
+```
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+### Tracing
+
+Tracing is configured with `tracesSampleRate` in your SDK init files. Next.js routes and API calls are automatically instrumented.
+
+Add [custom spans](/platforms/javascript/guides/nextjs/tracing/instrumentation/custom-instrumentation/) to trace specific operations in your code.
+
+**Verify:** Navigate to any page, then check [**Traces**](https://sentry.io/orgredirect/organizations/:orgslug/explore/traces/) in Sentry.
+
+
+
+
+```typescript
+import * as Sentry from "@sentry/nextjs";
+
+// Wrap operations with spans
+const result = await Sentry.startSpan(
+ { name: "expensive-operation", op: "function" },
+ async () => {
+ return await fetchDataFromAPI();
+ }
+);
+```
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+### Logs
+
+Logs are enabled with `enableLogs: true` in your SDK config. Use the Sentry logger to send structured logs from anywhere in your application.
+
+Connect popular logging libraries via [Integrations](/platforms/javascript/guides/nextjs/logs/#integrations).
+
+**Verify:** Add a log statement, trigger it, then check [**Logs**](https://sentry.io/orgredirect/organizations/:orgslug/explore/logs/) in Sentry.
+
+
+
+
+```typescript
+import * as Sentry from "@sentry/nextjs";
+
+Sentry.logger.info("User clicked checkout button");
+
+Sentry.logger.info("Order completed", {
+ orderId: "12345",
+ total: 99.99,
+});
+
+Sentry.logger.warn("Warning message");
+Sentry.logger.error("Error occurred");
+```
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+### User Feedback
+
+User Feedback adds an embeddable widget via `feedbackIntegration()` that lets users report bugs directly from your app.
+
+**Verify:** Look for the feedback button (bottom-right corner), submit test feedback, then check [**User Feedback**](https://sentry.io/orgredirect/organizations/:orgslug/feedback/) in Sentry.
+
+[Learn more about User Feedback](/platforms/javascript/guides/nextjs/user-feedback/)
+
+
+
+
+```typescript {filename:instrumentation-client.ts}
+Sentry.init({
+ dsn: "___PUBLIC_DSN___",
+
+ integrations: [
+ Sentry.feedbackIntegration({
+ colorScheme: "system",
+ }),
+ ],
+});
+```
+
+
+
+
+
+
+
+
+
Hybrid Apps (App Router + Pages Router)
+
+If your application uses both the App Router and Pages Router:
+
+1. Follow this guide for App Router components
+2. Add a `pages/_error.tsx` file for Pages Router error handling (see [Pages Router Setup](/platforms/javascript/guides/nextjs/manual-setup/pages-router/))
+3. Both routers share the same Sentry configuration files
+
+
+ The Sentry SDK automatically detects which router is being used and applies
+ the appropriate instrumentation.
+
+
+
Next Steps
+
+You've successfully integrated Sentry into your Next.js application! Here's what to explore next:
+
+- [Logs Integrations](/platforms/javascript/guides/nextjs/logs/#integrations) - Connect popular logging libraries like Pino, Winston, and Bunyan
+- [Distributed Tracing](/platforms/javascript/guides/nextjs/tracing/distributed-tracing/) - Trace requests across services and microservices
+- [AI Agent Monitoring](/platforms/javascript/guides/nextjs/tracing/instrumentation/ai-agents-module/) - Monitor AI agents built with Vercel AI SDK, LangChain, and more
+- [Connect GitHub + Seer](/organization/integrations/source-code-mgmt/github/#installing-github) - Enable AI-powered [root cause analysis](/product/ai-in-sentry/seer/) by connecting your GitHub repository
+- [Configuration Options](/platforms/javascript/guides/nextjs/configuration/) - Explore extended SDK configuration options
+
+
+
+- Try the [installation wizard](/platforms/javascript/guides/nextjs/) for automatic setup
+- [Get support](https://sentry.zendesk.com/hc/en-us/)
+
+
+
+
diff --git a/docs/platforms/javascript/guides/nextjs/manual-setup/pages-router.mdx b/docs/platforms/javascript/guides/nextjs/manual-setup/pages-router.mdx
new file mode 100644
index 00000000000000..093126bef27234
--- /dev/null
+++ b/docs/platforms/javascript/guides/nextjs/manual-setup/pages-router.mdx
@@ -0,0 +1,490 @@
+---
+title: "Pages Router Setup"
+sidebar_order: 2
+description: "Manual setup for Next.js applications using the Pages Router."
+---
+
+
+ For the fastest setup, we recommend using the [wizard
+ installer](/platforms/javascript/guides/nextjs).
+
+
+This guide covers manual setup for **Next.js applications using the Pages Router**. For other setups, see:
+
+- [App Router Setup](/platforms/javascript/guides/nextjs/manual-setup/) - For applications using the App Router (Next.js 15+)
+- [Webpack Setup](/platforms/javascript/guides/nextjs/manual-setup/webpack-setup/) - For applications not using Turbopack
+
+
+
+Choose the features you want to configure:
+
+
+
+
+
+## Install
+
+
+
+
+
+
+### Install the Sentry SDK
+
+Run the command for your preferred package manager to add the Sentry SDK to your application.
+
+
+
+
+```bash {tabTitle:npm}
+npm install @sentry/nextjs --save
+```
+
+```bash {tabTitle:yarn}
+yarn add @sentry/nextjs
+```
+
+```bash {tabTitle:pnpm}
+pnpm add @sentry/nextjs
+```
+
+
+
+
+
+
+## Configure
+
+
+
+
+
+
+### Apply Instrumentation to Your App
+
+Extend your app's default Next.js options by adding `withSentryConfig` into your `next.config.ts` (or `next.config.js`) file.
+
+
+ Pages Router applications typically use Webpack. The Webpack configuration
+ includes auto-instrumentation options that automatically wrap your API routes
+ and page data fetching methods.
+
+
+
+
+
+```typescript {tabTitle:Webpack} {filename:next.config.ts}
+import type { NextConfig } from "next";
+import { withSentryConfig } from "@sentry/nextjs";
+
+const nextConfig: NextConfig = {
+ // Your existing Next.js configuration
+};
+
+export default withSentryConfig(nextConfig, {
+ org: "___ORG_SLUG___",
+ project: "___PROJECT_SLUG___",
+
+ // Only print logs for uploading source maps in CI
+ silent: !process.env.CI,
+
+ // Webpack-specific options for Pages Router
+ webpack: {
+ // Auto-instrument API routes and data fetching methods (default: true)
+ autoInstrumentServerFunctions: true,
+
+ // Auto-instrument middleware (default: true)
+ autoInstrumentMiddleware: true,
+
+ // Tree-shake Sentry logger statements to reduce bundle size
+ treeshake: {
+ removeDebugLogging: true,
+ },
+ },
+});
+```
+
+```typescript {tabTitle:Turbopack} {filename:next.config.ts}
+import type { NextConfig } from "next";
+import { withSentryConfig } from "@sentry/nextjs";
+
+const nextConfig: NextConfig = {
+ // Your existing Next.js configuration
+};
+
+export default withSentryConfig(nextConfig, {
+ org: "___ORG_SLUG___",
+ project: "___PROJECT_SLUG___",
+
+ // Only print logs for uploading source maps in CI
+ silent: !process.env.CI,
+});
+```
+
+
+
+
+
+
+
+### Initialize Sentry SDKs
+
+Create the following files in your application's root directory (or `src` folder if you have one):
+
+- `sentry.client.config.ts` - Client-side SDK initialization
+- `sentry.server.config.ts` - Server-side SDK initialization
+- `sentry.edge.config.ts` - Edge runtime SDK initialization (if using edge routes)
+
+
+ Include your DSN directly in these files, or use a _public_ environment
+ variable like `NEXT_PUBLIC_SENTRY_DSN`.
+
+
+
+
+
+```typescript {tabTitle:Client} {filename:sentry.client.config.ts}
+import * as Sentry from "@sentry/nextjs";
+
+Sentry.init({
+ dsn: "___PUBLIC_DSN___",
+
+ // Adds request headers and IP for users
+ sendDefaultPii: true,
+ // ___PRODUCT_OPTION_START___ performance
+
+ // Capture 100% in dev, 10% in production
+ // Adjust based on your traffic volume
+ tracesSampleRate: process.env.NODE_ENV === "development" ? 1.0 : 0.1,
+ // ___PRODUCT_OPTION_END___ performance
+ integrations: [
+ // ___PRODUCT_OPTION_START___ session-replay
+ Sentry.replayIntegration(),
+ // ___PRODUCT_OPTION_END___ session-replay
+ ],
+ // ___PRODUCT_OPTION_START___ session-replay
+
+ // Capture Replay for 10% of all sessions,
+ // plus for 100% of sessions with an error
+ replaysSessionSampleRate: 0.1,
+ replaysOnErrorSampleRate: 1.0,
+ // ___PRODUCT_OPTION_END___ session-replay
+ // ___PRODUCT_OPTION_START___ logs
+
+ // Enable logs to be sent to Sentry
+ enableLogs: true,
+ // ___PRODUCT_OPTION_END___ logs
+});
+```
+
+```typescript {tabTitle:Server} {filename:sentry.server.config.ts}
+import * as Sentry from "@sentry/nextjs";
+
+Sentry.init({
+ dsn: "___PUBLIC_DSN___",
+
+ // Adds request headers and IP for users
+ sendDefaultPii: true,
+ // ___PRODUCT_OPTION_START___ performance
+
+ // Capture 100% in dev, 10% in production
+ // Adjust based on your traffic volume
+ tracesSampleRate: process.env.NODE_ENV === "development" ? 1.0 : 0.1,
+ // ___PRODUCT_OPTION_END___ performance
+ // ___PRODUCT_OPTION_START___ logs
+
+ // Enable logs to be sent to Sentry
+ enableLogs: true,
+ // ___PRODUCT_OPTION_END___ logs
+});
+```
+
+```typescript {tabTitle:Edge} {filename:sentry.edge.config.ts}
+import * as Sentry from "@sentry/nextjs";
+
+Sentry.init({
+ dsn: "___PUBLIC_DSN___",
+
+ // Adds request headers and IP for users
+ sendDefaultPii: true,
+ // ___PRODUCT_OPTION_START___ performance
+
+ // Capture 100% in dev, 10% in production
+ // Adjust based on your traffic volume
+ tracesSampleRate: process.env.NODE_ENV === "development" ? 1.0 : 0.1,
+ // ___PRODUCT_OPTION_END___ performance
+ // ___PRODUCT_OPTION_START___ logs
+
+ // Enable logs to be sent to Sentry
+ enableLogs: true,
+ // ___PRODUCT_OPTION_END___ logs
+});
+```
+
+
+
+Monitor your [usage stats](https://sentry.io/orgredirect/organizations/:orgslug/settings/stats/?dataCategory=spans) and adjust `tracesSampleRate` based on your traffic volume. Learn more about [sampling configuration](/platforms/javascript/guides/nextjs/configuration/sampling/).
+
+
+
+
+
+
+
+
+
+### Capture Pages Router Errors
+
+Create or update `pages/_error.tsx` to capture errors that occur during server-side rendering or in page components.
+
+The `getInitialProps` method captures the error asynchronously, ensuring Sentry has time to send the error before serverless functions terminate.
+
+
+
+
+
+
+
+
+
+
+
+
+### Source Maps (Optional)
+
+Add the `authToken` option to your `next.config.ts` to enable readable stack traces. Set the `SENTRY_AUTH_TOKEN` environment variable in your CI/CD.
+
+
+ Keep your auth token secret and out of version control.
+
+
+
+
+
+```typescript {filename:next.config.ts}
+export default withSentryConfig(nextConfig, {
+ org: "___ORG_SLUG___",
+ project: "___PROJECT_SLUG___",
+
+ // Pass the auth token
+ authToken: process.env.SENTRY_AUTH_TOKEN,
+
+ // Upload a larger set of source maps for prettier stack traces
+ widenClientFileUpload: true,
+});
+```
+
+```sh {filename:.env.local}
+SENTRY_AUTH_TOKEN=___ORG_AUTH_TOKEN___
+```
+
+
+
+
+
+
+## Error Monitoring
+
+Test your error monitoring setup by throwing an error and viewing it in Sentry.
+
+
+
+
+
+
+### Throw a Test Error
+
+Add this button to any page and click it to trigger a test error.
+
+
+
+
+```tsx {filename:pages/index.tsx}
+export default function Home() {
+ return (
+
+ );
+}
+```
+
+
+
+
+
+
+### Verify
+
+Open [**Issues**](https://sentry.io/orgredirect/organizations/:orgslug/issues/) in Sentry to see your test error. [Learn more about capturing errors](/platforms/javascript/guides/nextjs/usage/).
+
+## Verify Additional Features
+
+Based on the features you selected above, verify each one is working correctly.
+
+
+
+
+
+
+
+
+### Session Replay
+
+Session Replay captures video-like reproductions of user sessions. It's configured with `replayIntegration()` in your client config.
+
+**Verify:** Trigger an error or navigate your app, then check [**Replays**](https://sentry.io/orgredirect/organizations/:orgslug/replays/) in Sentry.
+
+
+
+
+```typescript {filename:sentry.client.config.ts}
+Sentry.init({
+ dsn: "___PUBLIC_DSN___",
+
+ integrations: [Sentry.replayIntegration()],
+
+ replaysSessionSampleRate: 0.1,
+ replaysOnErrorSampleRate: 1.0,
+});
+```
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+### Tracing
+
+Tracing is configured with `tracesSampleRate` in your SDK init files. Next.js routes and API calls are automatically instrumented.
+
+**Verify:** Navigate to any page, then check [**Traces**](https://sentry.io/orgredirect/organizations/:orgslug/explore/traces/) in Sentry.
+
+
+
+
+```typescript {filename:sentry.server.config.ts}
+Sentry.init({
+ dsn: "___PUBLIC_DSN___",
+
+ tracesSampleRate: process.env.NODE_ENV === "development" ? 1.0 : 0.1,
+});
+```
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+### Logs
+
+Logs are enabled with `enableLogs: true` in your SDK config. Use the Sentry logger to send structured logs.
+
+**Verify:** Add a log statement, trigger it, then check [**Logs**](https://sentry.io/orgredirect/organizations/:orgslug/explore/logs/) in Sentry.
+
+
+
+
+```typescript
+import * as Sentry from "@sentry/nextjs";
+
+Sentry.logger.info("User action", { userId: "123" });
+Sentry.logger.warn("Warning message");
+Sentry.logger.error("Error occurred");
+```
+
+
+
+
+
+
+
+
+## Vercel Cron Jobs (Optional)
+
+Automatically create [Cron Monitors](/product/crons/) in Sentry for your [Vercel cron jobs](https://vercel.com/docs/cron-jobs).
+
+
+
+
+
+
+### Enable Automatic Cron Monitoring
+
+Add the `automaticVercelMonitors` option to your `next.config.ts`.
+
+
+
+
+```typescript {filename:next.config.ts}
+import { withSentryConfig } from "@sentry/nextjs";
+
+export default withSentryConfig(nextConfig, {
+ automaticVercelMonitors: true,
+});
+```
+
+
+
+
+
+
+
Hybrid Apps (App Router + Pages Router)
+
+If your application uses both the App Router and Pages Router:
+
+1. Follow the [App Router Setup](/platforms/javascript/guides/nextjs/manual-setup/) for App Router components
+2. Add the `pages/_error.tsx` file from this guide for Pages Router error handling
+3. Both routers share the same Sentry configuration files
+
+
+ The Sentry SDK automatically detects which router is being used and applies
+ the appropriate instrumentation.
+
+
+
Next Steps
+
+- [Logs Integrations](/platforms/javascript/guides/nextjs/logs/#integrations) - Connect popular logging libraries like Pino, Winston, and Bunyan
+- [Distributed Tracing](/platforms/javascript/guides/nextjs/tracing/distributed-tracing/) - Trace requests across services and microservices
+- [AI Agent Monitoring](/platforms/javascript/guides/nextjs/tracing/instrumentation/ai-agents-module/) - Monitor AI agents built with Vercel AI SDK, LangChain, and more
+- [Connect GitHub + Seer](/organization/integrations/source-code-mgmt/github/#installing-github) - Enable AI-powered [root cause analysis](/product/ai-in-sentry/seer/)
+- [Configuration Options](/platforms/javascript/guides/nextjs/configuration/) - Explore extended SDK configuration
+
+
+
+- Try the [installation wizard](/platforms/javascript/guides/nextjs/) for automatic setup
+- [Get support](https://sentry.zendesk.com/hc/en-us/)
+
+
+
+
diff --git a/docs/platforms/javascript/guides/nextjs/manual-setup/webpack-setup.mdx b/docs/platforms/javascript/guides/nextjs/manual-setup/webpack-setup.mdx
new file mode 100644
index 00000000000000..d588ca802a5857
--- /dev/null
+++ b/docs/platforms/javascript/guides/nextjs/manual-setup/webpack-setup.mdx
@@ -0,0 +1,402 @@
+---
+title: "Webpack Setup"
+sidebar_order: 3
+description: "Additional configuration for Next.js applications using Webpack instead of Turbopack."
+---
+
+This guide covers the configuration differences for **Next.js applications using Webpack** (the default bundler before Next.js 15). Complete the [main manual setup](/platforms/javascript/guides/nextjs/manual-setup/) first, then apply these Webpack-specific configurations.
+
+For a complete reference of all build configuration options, see the [Build Configuration](/platforms/javascript/guides/nextjs/configuration/build/) documentation.
+
+
+ If you're using Next.js 15+ with Turbopack (the default), you don't need this
+ guide. See the [main manual
+ setup](/platforms/javascript/guides/nextjs/manual-setup/) instead.
+
+
+## Key Differences: Webpack vs Turbopack
+
+| Feature | Turbopack | Webpack |
+| ------------------------------- | ------------------------------- | ---------------------------------------------------- |
+| Server function instrumentation | Automatic via Next.js telemetry | Build-time code injection |
+| Middleware instrumentation | Automatic via Next.js telemetry | Build-time code injection |
+| Source map upload | Post-compile during build | During build via plugin (default) |
+| Route exclusion | Not supported | Supported via `webpack.excludeServerRoutes` |
+| React component annotation | Not supported | Supported via `webpack.reactComponentAnnotation` |
+| Logger tree-shaking | Not supported | Supported via `webpack.treeshake.removeDebugLogging` |
+
+## Auto-Instrumentation Options
+
+With Webpack, Sentry automatically instruments your server functions, middleware, and app directory components at build time. You can control this behavior:
+
+
+
+
+
+
+### Configure Auto-Instrumentation
+
+These options are enabled by default with Webpack. Disable them if you prefer manual instrumentation or experience build issues.
+
+**Note**: These options instrument Pages Router pages, API routes, and App Router components, but do NOT automatically instrument Server Actions. Server Actions require manual wrapping using `withServerActionInstrumentation()`.
+
+
+
+
+```typescript {filename:next.config.ts}
+import { withSentryConfig } from "@sentry/nextjs";
+
+export default withSentryConfig(nextConfig, {
+ webpack: {
+ // Instrument Pages Router API routes and data fetching methods (default: true)
+ autoInstrumentServerFunctions: true,
+
+ // Instrument Next.js middleware (default: true)
+ autoInstrumentMiddleware: true,
+
+ // Instrument App Router components (default: true)
+ autoInstrumentAppDirectory: true,
+
+ // Tree-shake Sentry logger statements to reduce bundle size
+ treeshake: {
+ removeDebugLogging: true,
+ },
+ },
+});
+```
+
+
+
+
+
+
+## Exclude Routes From Instrumentation
+
+With Webpack, you can exclude specific routes from automatic instrumentation. This is useful for health check endpoints or routes that shouldn't be monitored.
+
+
+ This option has no effect when using Turbopack, as Turbopack relies on Next.js
+ telemetry features instead of build-time instrumentation.
+
+
+
+
+
+
+
+### Configure Route Exclusions
+
+Specify routes as URL paths (not file system paths). Routes must have a leading slash and no trailing slash.
+
+
+
+
+```typescript {filename:next.config.ts}
+import { withSentryConfig } from "@sentry/nextjs";
+
+export default withSentryConfig(nextConfig, {
+ webpack: {
+ excludeServerRoutes: [
+ "/api/health",
+ "/api/excluded/[parameter]",
+ /^\/internal\//, // Regex for all /internal/* routes
+ ],
+ },
+});
+```
+
+
+
+
+
+
+## Source Map Upload
+
+By default, Webpack uploads source maps **during the build process** using the Sentry Webpack Plugin. This happens separately for each build (client, server, edge), which can increase build time.
+
+For faster builds, you can use the post-build upload mode (available in Next.js 15.4.1+), which uploads all source maps in a single operation after all builds complete.
+
+
+
+
+
+
+### Default: Upload During Build
+
+The Sentry Webpack Plugin runs during each webpack compilation and uploads source maps as they're generated.
+
+
+
+
+```typescript {filename:next.config.ts}
+import { withSentryConfig } from "@sentry/nextjs";
+
+export default withSentryConfig(nextConfig, {
+ org: "___ORG_SLUG___",
+ project: "___PROJECT_SLUG___",
+ authToken: process.env.SENTRY_AUTH_TOKEN,
+});
+```
+
+
+
+
+
+
+
+
+
+
+
+### Option: Upload After Build (Next.js 15.4.1+)
+
+Enable post-build upload for faster builds. All source maps are uploaded once after all webpack builds complete.
+
+
+ This option requires Next.js 15.4.1 or later. Turbopack always uses this mode.
+
+
+
+
+
+```typescript {filename:next.config.ts}
+import { withSentryConfig } from "@sentry/nextjs";
+
+export default withSentryConfig(nextConfig, {
+ org: "___ORG_SLUG___",
+ project: "___PROJECT_SLUG___",
+ authToken: process.env.SENTRY_AUTH_TOKEN,
+
+ // Upload after all builds complete (faster)
+ useRunAfterProductionCompileHook: true,
+});
+```
+
+
+
+
+
+
+
+
+
+
+
+### Advanced Webpack Plugin Options
+
+Pass options directly to the underlying Sentry Webpack Plugin for advanced configuration.
+
+
+ The `unstable_sentryWebpackPluginOptions` API may change in future releases.
+
+
+
+ These options only apply when `useRunAfterProductionCompileHook` is `false`
+ (the default).
+
+
+
+
+
+```typescript {filename:next.config.ts}
+import { withSentryConfig } from "@sentry/nextjs";
+
+export default withSentryConfig(nextConfig, {
+ org: "___ORG_SLUG___",
+ project: "___PROJECT_SLUG___",
+ authToken: process.env.SENTRY_AUTH_TOKEN,
+
+ webpack: {
+ // Advanced Webpack plugin options
+ unstable_sentryWebpackPluginOptions: {
+ sourcemaps: {
+ assets: ["./build/**/*.js", "./build/**/*.map"],
+ ignore: ["node_modules/**"],
+ },
+ },
+ },
+});
+```
+
+
+
+
+
+
+## Server Actions with Webpack
+
+Server Actions (functions marked with `"use server"`) are **not automatically instrumented** by Webpack's build-time instrumentation. You must manually wrap them for error and performance monitoring.
+
+
+
+
+
+
+### Manual Server Action Instrumentation
+
+Wrap Server Actions with `withServerActionInstrumentation()` to capture errors and performance data.
+
+
+
+
+```typescript {filename:app/actions.ts}
+"use server";
+import * as Sentry from "@sentry/nextjs";
+
+export async function submitForm(formData: FormData) {
+ return Sentry.withServerActionInstrumentation(
+ "submitForm", // Action name for Sentry
+ {
+ recordResponse: true, // Include response data
+ },
+ async () => {
+ // Your server action logic
+ const result = await processForm(formData);
+ return { success: true, data: result };
+ }
+ );
+}
+```
+
+
+
+
+
+
+## React Component Annotation
+
+With Webpack, you can enable React component name tracking. This annotates React components with `data-sentry-*` attributes that allow Sentry to identify which components users interacted with in [Session Replay](/platforms/javascript/guides/nextjs/session-replay/) and [breadcrumbs](/platforms/javascript/guides/nextjs/enriching-events/breadcrumbs/).
+
+
+ This feature is only available with Webpack. Turbopack does not support React
+ component annotation.
+
+
+
+
+
+
+
+### Enable Component Annotation
+
+Enable `reactComponentAnnotation` to track component names in your application. This is especially useful for debugging user interactions in Session Replay.
+
+
+
+
+```typescript {filename:next.config.ts}
+import { withSentryConfig } from "@sentry/nextjs";
+
+export default withSentryConfig(nextConfig, {
+ webpack: {
+ reactComponentAnnotation: {
+ enabled: true,
+ },
+ },
+});
+```
+
+
+
+
+
+
+
+
+
+
+
+### Exclude Specific Components
+
+If you have components you don't want annotated (for privacy or performance reasons), you can exclude them by name.
+
+
+
+
+```typescript {filename:next.config.ts}
+import { withSentryConfig } from "@sentry/nextjs";
+
+export default withSentryConfig(nextConfig, {
+ webpack: {
+ reactComponentAnnotation: {
+ enabled: true,
+ ignoredComponents: ["SensitiveForm", "InternalDebugPanel"],
+ },
+ },
+});
+```
+
+
+
+
+
+
+## Tunneling with Webpack
+
+Tunneling works identically for both Webpack and Turbopack. Sentry automatically filters tunnel requests from middleware spans to prevent noise in your monitoring data.
+
+
+
+
+
+
+### Configure Tunnel Route
+
+Enable tunneling to bypass ad-blockers. Use a fixed route so you can exclude it from middleware if needed.
+
+
+
+You can use `tunnelRoute: true` to auto-generate a random route. However, random routes cannot be excluded from middleware matchers since the route changes on each build. This may cause issues if you have middleware that intercepts all requests.
+
+```typescript
+tunnelRoute: true, // Auto-generated random route
+```
+
+
+
+
+
+
+```typescript {filename:next.config.ts}
+import { withSentryConfig } from "@sentry/nextjs";
+
+export default withSentryConfig(nextConfig, {
+ // Use a fixed route (recommended)
+ tunnelRoute: "/monitoring",
+});
+```
+
+
+
+
+
+
+## Migrating from Webpack to Turbopack
+
+If you're upgrading to Turbopack:
+
+1. **Remove webpack-only options** - `excludeServerRoutes` and `unstable_sentryWebpackPluginOptions` have no effect with Turbopack
+2. **Understand source map changes** - Turbopack always uses post-build upload (no plugin-based upload option)
+3. **Test auto-instrumentation** - Turbopack uses Next.js telemetry instead of build-time injection; verify your monitoring still works
+
+```typescript {filename:next.config.ts}
+// Before (Webpack)
+export default withSentryConfig(nextConfig, {
+ excludeServerRoutes: ["/api/health"],
+ tunnelRoute: "/monitoring",
+});
+
+// After (Turbopack)
+export default withSentryConfig(nextConfig, {
+ // excludeServerRoutes is not supported with Turbopack
+ tunnelRoute: "/monitoring",
+});
+```
+
+## Next Steps
+
+- [Logs Integrations](/platforms/javascript/guides/nextjs/logs/#integrations) - Connect popular logging libraries like Pino, Winston, and Bunyan
+- [Distributed Tracing](/platforms/javascript/guides/nextjs/tracing/distributed-tracing/) - Trace requests across services and microservices
+- [AI Agent Monitoring](/platforms/javascript/guides/nextjs/tracing/instrumentation/ai-agents-module/) - Monitor AI agents built with Vercel AI SDK, LangChain, and more
+- [Connect GitHub + Seer](/organization/integrations/source-code-mgmt/github/#installing-github) - Enable AI-powered [root cause analysis](/product/ai-in-sentry/seer/)
+- [Configuration Options](/platforms/javascript/guides/nextjs/configuration/) - Explore extended SDK configuration
diff --git a/platform-includes/getting-started-capture-errors/nextjs/app-router-global-error/javascript.nextjs.mdx b/platform-includes/getting-started-capture-errors/nextjs/app-router-global-error/javascript.nextjs.mdx
new file mode 100644
index 00000000000000..8a5c016e19ebe9
--- /dev/null
+++ b/platform-includes/getting-started-capture-errors/nextjs/app-router-global-error/javascript.nextjs.mdx
@@ -0,0 +1,52 @@
+```tsx {filename:global-error.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 (
+
+
+ {/* `NextError` is the default Next.js error page component. Its type
+ definition requires a `statusCode` prop. However, since the App Router
+ does not expose status codes for errors, we simply pass 0 to render a
+ generic error message. */}
+
+
+
+ );
+}
+```
+
+```jsx {filename:global-error.jsx}
+"use client";
+
+import * as Sentry from "@sentry/nextjs";
+import NextError from "next/error";
+import { useEffect } from "react";
+
+export default function GlobalError({ error }) {
+ useEffect(() => {
+ Sentry.captureException(error);
+ }, [error]);
+
+ return (
+
+
+ {/* This is the default Next.js error component. */}
+
+
+
+ );
+}
+```
diff --git a/platform-includes/getting-started-capture-errors/nextjs/nested-server-components/javascript.nextjs.mdx b/platform-includes/getting-started-capture-errors/nextjs/nested-server-components/javascript.nextjs.mdx
new file mode 100644
index 00000000000000..5e6e00a8ade380
--- /dev/null
+++ b/platform-includes/getting-started-capture-errors/nextjs/nested-server-components/javascript.nextjs.mdx
@@ -0,0 +1,31 @@
+```JavaScript {filename:instrumentation.ts|js}
+import * as Sentry from "@sentry/nextjs";
+
+export const onRequestError = Sentry.captureRequestError;
+```
+
+
+You can call `captureRequestError` with all arguments passed to `onRequestError`:
+
+```TypeScript {filename:instrumentation.ts}
+import * as Sentry from "@sentry/nextjs";
+import type { Instrumentation } from "next";
+
+export const onRequestError: Instrumentation.onRequestError = (...args) => {
+ Sentry.captureRequestError(...args);
+
+ // ... additional logic here
+};
+```
+
+```JavaScript {filename:instrumentation.js}
+import * as Sentry from "@sentry/nextjs";
+
+export const onRequestError = (...args) => {
+ Sentry.captureRequestError(...args);
+
+ // ... additional logic here
+};
+```
+
+
diff --git a/platform-includes/getting-started-capture-errors/nextjs/pages-router-error/javascript.nextjs.mdx b/platform-includes/getting-started-capture-errors/nextjs/pages-router-error/javascript.nextjs.mdx
new file mode 100644
index 00000000000000..7f2583720767b2
--- /dev/null
+++ b/platform-includes/getting-started-capture-errors/nextjs/pages-router-error/javascript.nextjs.mdx
@@ -0,0 +1,41 @@
+```tsx {filename:_error.tsx}
+import * as Sentry from "@sentry/nextjs";
+import type { NextPage } from "next";
+import type { ErrorProps } from "next/error";
+import Error from "next/error";
+
+const CustomErrorComponent: NextPage = (props) => {
+ return ;
+};
+
+CustomErrorComponent.getInitialProps = async (contextData) => {
+ // In case this is running in a serverless function, await this in order to give Sentry
+ // time to send the error before the lambda exits
+ await Sentry.captureUnderscoreErrorException(contextData);
+
+ // This will contain the status code of the response
+ return Error.getInitialProps(contextData);
+};
+
+export default CustomErrorComponent;
+```
+
+```jsx {filename:_error.jsx}
+import * as Sentry from "@sentry/nextjs";
+import Error from "next/error";
+
+const CustomErrorComponent = (props) => {
+ return ;
+};
+
+CustomErrorComponent.getInitialProps = async (contextData) => {
+ // In case this is running in a serverless function, await this in order to give Sentry
+ // time to send the error before the lambda exits
+ await Sentry.captureUnderscoreErrorException(contextData);
+
+ // This will contain the status code of the response
+ return Error.getInitialProps(contextData);
+};
+
+export default CustomErrorComponent;
+```
diff --git a/platform-includes/getting-started-prerequisites/javascript.nextjs.mdx b/platform-includes/getting-started-prerequisites/javascript.nextjs.mdx
new file mode 100644
index 00000000000000..bcb8b057801267
--- /dev/null
+++ b/platform-includes/getting-started-prerequisites/javascript.nextjs.mdx
@@ -0,0 +1,6 @@
+## Prerequisites
+
+You need:
+
+- A Next.js application
+- A Sentry [account](https://sentry.io/signup/) and [project](/product/projects/)
diff --git a/src/components/featureBadge/index.tsx b/src/components/featureBadge/index.tsx
new file mode 100644
index 00000000000000..e75b0967535263
--- /dev/null
+++ b/src/components/featureBadge/index.tsx
@@ -0,0 +1,17 @@
+import styles from './style.module.scss';
+
+type BadgeType = 'new' | 'beta';
+type BadgeSize = 'small' | 'default';
+
+interface FeatureBadgeProps {
+ type: BadgeType;
+ size?: BadgeSize;
+}
+
+export function FeatureBadge({type, size = 'default'}: FeatureBadgeProps) {
+ const label = type === 'new' ? 'NEW' : 'BETA';
+ const typeClass = type === 'new' ? styles.newBadge : styles.betaBadge;
+ const sizeClass = size === 'small' ? styles.small : '';
+
+ return {label};
+}
diff --git a/src/components/featureBadge/style.module.scss b/src/components/featureBadge/style.module.scss
new file mode 100644
index 00000000000000..46a6f65eb1ee37
--- /dev/null
+++ b/src/components/featureBadge/style.module.scss
@@ -0,0 +1,38 @@
+// Base badge styles
+.newBadge,
+.betaBadge {
+ display: inline-flex;
+ align-items: center;
+ font-weight: 600;
+ line-height: 1;
+ letter-spacing: 0.05em;
+ white-space: nowrap;
+ flex-shrink: 0;
+ vertical-align: middle;
+
+ // Default size
+ padding: 0.2rem 0.35rem;
+ font-size: 0.625rem;
+ border-radius: 0.2rem;
+ margin-left: 0.375rem;
+}
+
+// Color variants
+.newBadge {
+ color: rgb(24, 20, 35);
+ background-color: rgb(0, 242, 97);
+}
+
+.betaBadge {
+ color: rgb(24, 20, 35);
+ background-color: rgb(255, 208, 14);
+}
+
+// Small size - compound selector for higher specificity
+.newBadge.small,
+.betaBadge.small {
+ padding: 0.1rem 0.2rem;
+ font-size: 0.5rem;
+ border-radius: 0.125rem;
+ margin-left: 0.25rem;
+}
diff --git a/src/components/onboarding/index.tsx b/src/components/onboarding/index.tsx
index 7e8e00a689594f..41d440f0880c7e 100644
--- a/src/components/onboarding/index.tsx
+++ b/src/components/onboarding/index.tsx
@@ -6,6 +6,8 @@ import {QuestionMarkCircledIcon} from '@radix-ui/react-icons';
import * as Tooltip from '@radix-ui/react-tooltip';
import {Button, Checkbox, Theme} from '@radix-ui/themes';
+import {usePlausibleEvent} from 'sentry-docs/hooks/usePlausibleEvent';
+
import styles from './styles.module.scss';
import {CodeContext} from '../codeContext';
@@ -339,6 +341,7 @@ export function OnboardingOptionButtons({
options: (OnboardingOptionType | OptionId)[];
}) {
const codeContext = useContext(CodeContext);
+ const {emit} = usePlausibleEvent();
const normalizedOptions = initialOptions
.map(option => {
@@ -374,6 +377,17 @@ export function OnboardingOptionButtons({
function handleCheckedChange(clickedOption: OnboardingOptionType, checked: boolean) {
touchOptions();
+
+ // Track the toggle event in Plausible
+ emit('Onboarding Option Toggle', {
+ props: {
+ checked,
+ optionId: clickedOption.id,
+ optionName: optionDetails[clickedOption.id].name,
+ page: typeof window !== 'undefined' ? window.location.pathname : '',
+ },
+ });
+
const dependencies = optionDetails[clickedOption.id].deps ?? [];
const depenedants =
options.filter(opt => optionDetails[opt.id].deps?.includes(clickedOption.id)) ?? [];
diff --git a/src/components/sidebar/platformSidebar.tsx b/src/components/sidebar/platformSidebar.tsx
index 2867f4ef6ef07d..fb964dbf643314 100644
--- a/src/components/sidebar/platformSidebar.tsx
+++ b/src/components/sidebar/platformSidebar.tsx
@@ -47,12 +47,18 @@ export function PlatformSidebar({
? `platforms/${platformName}/guides/${guideName}`
: `platforms/${platformName}`;
+ // Use "Getting Started" for Next.js, default title for other platforms
+ const isNextJs = platformName === 'javascript' && guideName === 'nextjs';
+ const sidebarTitle = isNextJs
+ ? 'Getting Started'
+ : `Sentry for ${(guide || platform).title}`;
+
return (