From f27f71c7651b51545af9f2bd8382726e9ebc06e6 Mon Sep 17 00:00:00 2001 From: Charly Gomez Date: Thu, 10 Sep 2026 15:30:48 +0200 Subject: [PATCH] docs(nextjs): Update getting started and manual setup for v11 Audited the Next.js getting started and manual setup pages against sentry-javascript develop (dccf25d478). withSentryConfig is no longer exported from @sentry/nextjs and moves to the @sentry/nextjs/config subpath. The Pages Router page initialized the browser SDK in sentry.client.config.ts, which Turbopack ignores silently, and never added instrumentation.ts, so following it produced an app with neither a browser nor a server SDK. Export onRouterTransitionStart unconditionally, since the SDK warns whenever it is absent rather than only when tracing is enabled. Drop build options removed in v11 and document their replacements, remove enableLogs, and state the Next.js 14 and Node 20.19.0 minimums. Also fix a dead link in the crons include and two SdkOption anchors that used slugified names instead of the verbatim option name. Refs SDK-1493 Co-Authored-By: Claude Opus 5 (1M context) --- .../common/configuration/filtering.mdx | 2 +- .../common/troubleshooting/index.mdx | 2 +- .../nextjs/configuration/build/index.mdx | 166 ++++++++---------- .../nextjs/configuration/tree-shaking.mdx | 2 +- .../javascript/guides/nextjs/index.mdx | 4 +- .../javascript/guides/nextjs/logs/index.mdx | 6 +- .../guides/nextjs/manual-setup/index.mdx | 5 +- .../nextjs/manual-setup/pages-router.mdx | 80 ++++++++- .../nextjs/manual-setup/webpack-setup.mdx | 79 ++++----- .../javascript.nextjs.mdx | 28 +-- .../crons/setup/javascript.nextjs.mdx | 6 +- .../javascript.nextjs.mdx | 3 +- .../sourcemaps/overview/javascript.nextjs.mdx | 7 +- 13 files changed, 204 insertions(+), 186 deletions(-) diff --git a/docs/platforms/javascript/common/configuration/filtering.mdx b/docs/platforms/javascript/common/configuration/filtering.mdx index 481aafa04376f4..95b4b3cfd12de0 100644 --- a/docs/platforms/javascript/common/configuration/filtering.mdx +++ b/docs/platforms/javascript/common/configuration/filtering.mdx @@ -57,7 +57,7 @@ This integration can be very helpful in reducing noise that's not related to you -**Prerequisite**: To use the `thirdPartyErrorFilterIntegration`, ensure you are using a bundler and one of [Sentry's bundler plugins](https://github.com/getsentry/sentry-javascript-bundler-plugins). For **Next.js with Turbopack**, use the [`_experimental.turbopackApplicationKey`](/platforms/javascript/guides/nextjs/configuration/build/#_experimentalturbopackapplicationkey) build option instead. +**Prerequisite**: To use the `thirdPartyErrorFilterIntegration`, ensure you are using a bundler and one of [Sentry's bundler plugins](https://github.com/getsentry/sentry-javascript-bundler-plugins). For **Next.js**, set the [`applicationKey`](/platforms/javascript/guides/nextjs/configuration/build/#applicationKey) build option, which works for both Webpack and Turbopack builds. diff --git a/docs/platforms/javascript/common/troubleshooting/index.mdx b/docs/platforms/javascript/common/troubleshooting/index.mdx index 21a367349d432b..da616577c33275 100644 --- a/docs/platforms/javascript/common/troubleshooting/index.mdx +++ b/docs/platforms/javascript/common/troubleshooting/index.mdx @@ -675,7 +675,7 @@ shamefully-hoist=true }; // The Sentry plugin should always be applied last - const { withSentryConfig } = require('@sentry/nextjs'); + const { withSentryConfig } = require('@sentry/nextjs/config'); module.exports = withSentryConfig(module.exports) ``` diff --git a/docs/platforms/javascript/guides/nextjs/configuration/build/index.mdx b/docs/platforms/javascript/guides/nextjs/configuration/build/index.mdx index 5216a58eb971fb..b243a2da237f26 100644 --- a/docs/platforms/javascript/guides/nextjs/configuration/build/index.mdx +++ b/docs/platforms/javascript/guides/nextjs/configuration/build/index.mdx @@ -292,6 +292,72 @@ Excluded routes will appear as raw URLs in transaction names instead of paramete + + +Annotates your React components with `data-sentry-component`, `data-sentry-element`, and `data-sentry-source-file` attributes at build time, so Sentry can identify which component a user interacted with in [Session Replay](/platforms/javascript/guides/nextjs/session-replay/) and [breadcrumbs](/platforms/javascript/guides/nextjs/enriching-events/breadcrumbs/). + +Disabled unless you set a value. Set `enabled: true` to turn it on, and `ignoredComponents` to skip components by name. + +This option drives both Webpack and Turbopack builds. On Turbopack it requires **Next.js 16+**; on an older version the SDK warns at build time. + +```javascript {filename:next.config.ts} +import { withSentryConfig } from "@sentry/nextjs/config"; + +export default withSentryConfig(nextConfig, { + reactComponentAnnotation: { + enabled: true, + ignoredComponents: ["SensitiveForm", "InternalDebugPanel"], + }, +}); +``` + + + The bundler-specific `webpack.reactComponentAnnotation` and + `_experimental.turbopackReactComponentAnnotation` options are deprecated in + favor of this one and will be removed in the next major version. If both a + bundler-specific option and this one are set, the bundler-specific one wins + for that bundler. + + + + + + +Application key used by [`thirdPartyErrorFilterIntegration`](/platforms/javascript/configuration/filtering/#using-thirdpartyerrorfilterintegration) to tell your code apart from third-party code, so you can drop errors coming from browser extensions, injected scripts, and third-party widgets. + +The value must match an entry in the `filterKeys` array of your `thirdPartyErrorFilterIntegration` configuration. This option works for both Webpack and Turbopack builds. + +```javascript {tabTitle:Config} {mdExpandTabs} {filename:next.config.ts} +import { withSentryConfig } from "@sentry/nextjs/config"; + +export default withSentryConfig(nextConfig, { + applicationKey: "my-nextjs-app", +}); +``` + +```javascript {tabTitle:Client} {filename:instrumentation-client.ts} +import * as Sentry from "@sentry/nextjs"; + +Sentry.init({ + integrations: [ + Sentry.thirdPartyErrorFilterIntegration({ + filterKeys: ["my-nextjs-app"], + behaviour: "drop-error-if-exclusively-contains-third-party-frames", + }), + ], +}); +``` + + + + + +Automatically instrument server-side dependencies at build time. This is what gives you tracing for libraries that can't be patched at runtime, including on platforms like Vercel and Netlify. + +Set to `false` to turn it off. Turbopack support requires **Next.js 16+**; the Webpack path works on earlier versions. + + + ## Next.js Webpack Options @@ -343,118 +409,32 @@ Automatically create cron monitors in Sentry for your Vercel Cron Jobs if config - - Pass configuration options directly to the [Sentry Webpack - Plugin](https://www.npmjs.com/package/@sentry/webpack-plugin) that ships with - the Sentry Next.js SDK. If `withSentryConfig` doesn't provide the option you - need to modify, you may override the `sentryWebpackPluginOptions` using this - option. - - This option is considered unstable, and its API may change in a breaking way - in any release. - - - - - -Enables React component name tracking. When enabled, it annotates React components with data attributes that allow Sentry to track which components users interacted with in features like Session Replay and breadcrumbs. - - - - - -A list of React component names to exclude from component annotation. - - - Configuration options for tree shaking. Refer to the [tree shaking documentation](/platforms/javascript/guides/nextjs/configuration/tree-shaking) for more details. -## Experimental Turbopack Options +## Experimental Options - These options are experimental and require **Next.js 16+**. Their API may - change in future releases. + These options are experimental. Their API may change in future releases. - - - - -Enables React component name annotation for Turbopack builds. This is the Turbopack equivalent of [`webpack.reactComponentAnnotation`](#webpackreactcomponentannotationenabled). - -When enabled, React components are annotated with `data-sentry-component`, `data-sentry-element`, and `data-sentry-source-file` attributes at build time. These attributes 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/). - -```javascript {filename:next.config.ts} -import { withSentryConfig } from "@sentry/nextjs"; - -export default withSentryConfig(nextConfig, { - _experimental: { - turbopackReactComponentAnnotation: { - enabled: true, - }, - }, -}); -``` - - + - +Automatically create [Cron Monitors](/product/monitors-and-alerts/monitors/crons/) in Sentry for the Vercel Cron Jobs configured in your `vercel.json`, by detecting cron requests and emitting check-ins from spans. -A list of React component names to exclude from annotation in Turbopack builds. +Unlike [`webpack.automaticVercelMonitors`](#webpack.automaticVercelMonitors), which wraps route handlers at build time, this works with both Webpack and Turbopack and with both the App Router and the Pages Router. If you enable both, the SDK uses this one and warns that the other is redundant. ```javascript {filename:next.config.ts} -import { withSentryConfig } from "@sentry/nextjs"; +import { withSentryConfig } from "@sentry/nextjs/config"; export default withSentryConfig(nextConfig, { _experimental: { - turbopackReactComponentAnnotation: { - enabled: true, - ignoredComponents: ["SensitiveForm", "InternalDebugPanel"], - }, + vercelCronsMonitoring: true, }, }); ``` - - - - - -Application key used by [`thirdPartyErrorFilterIntegration`](/platforms/javascript/configuration/filtering/#using-thirdpartyerrorfilterintegration) to distinguish first-party code from third-party code in Turbopack builds. This is the Turbopack equivalent of setting `applicationKey` via the Sentry Webpack Plugin. - -When set, a Turbopack loader injects `_sentryModuleMetadata` into every first-party module, enabling the `thirdPartyErrorFilterIntegration` to filter errors from browser extensions, injected scripts, and third-party widgets. - -The value must match the `filterKeys` array in your `thirdPartyErrorFilterIntegration` configuration. - -```javascript {tabTitle:Config} {filename:next.config.ts} -import { withSentryConfig } from "@sentry/nextjs"; - -export default withSentryConfig(nextConfig, { - _experimental: { - turbopackApplicationKey: "my-nextjs-app", - }, -}); -``` - -```javascript {tabTitle:Client} {filename:instrumentation-client.ts} -import * as Sentry from "@sentry/nextjs"; - -Sentry.init({ - integrations: [ - Sentry.thirdPartyErrorFilterIntegration({ - filterKeys: ["my-nextjs-app"], - behaviour: "drop-error-if-exclusively-contains-third-party-frames", - }), - ], -}); -``` - - diff --git a/docs/platforms/javascript/guides/nextjs/configuration/tree-shaking.mdx b/docs/platforms/javascript/guides/nextjs/configuration/tree-shaking.mdx index 0e1449901922c3..d8d95d4d7b7101 100644 --- a/docs/platforms/javascript/guides/nextjs/configuration/tree-shaking.mdx +++ b/docs/platforms/javascript/guides/nextjs/configuration/tree-shaking.mdx @@ -57,7 +57,7 @@ The following sections cover each available tree-shaking option and how to confi -Setting this option to true will remove all Sentry SDK debug logging code (the console logs that appear when you set `debug: true` in your SDK configuration). This doesn't affect Sentry's Logs product (controlled by the `enableLogs` option) or your app's logging. +Setting this option to true will remove all Sentry SDK debug logging code (the console logs that appear when you set `debug: true` in your SDK configuration). This doesn't affect Sentry's Logs product or your app's logging. diff --git a/docs/platforms/javascript/guides/nextjs/index.mdx b/docs/platforms/javascript/guides/nextjs/index.mdx index 0fe6573a5165fd..64e754043fb82e 100644 --- a/docs/platforms/javascript/guides/nextjs/index.mdx +++ b/docs/platforms/javascript/guides/nextjs/index.mdx @@ -74,6 +74,8 @@ Sentry.init({ // ___PRODUCT_OPTION_END___ session-replay ], }); + +export const onRouterTransitionStart = Sentry.captureRouterTransitionStart; ``` ```typescript {tabTitle:Server} {filename:sentry.server.config.ts} @@ -148,7 +150,7 @@ Your `next.config.ts` is wrapped with `withSentryConfig` to enable source map up ```typescript {filename:next.config.ts} -import { withSentryConfig } from "@sentry/nextjs"; +import { withSentryConfig } from "@sentry/nextjs/config"; export default withSentryConfig(nextConfig, { org: "___ORG_SLUG___", diff --git a/docs/platforms/javascript/guides/nextjs/logs/index.mdx b/docs/platforms/javascript/guides/nextjs/logs/index.mdx index 44dba6e642a3cc..e97bed7b8d1a32 100644 --- a/docs/platforms/javascript/guides/nextjs/logs/index.mdx +++ b/docs/platforms/javascript/guides/nextjs/logs/index.mdx @@ -26,10 +26,6 @@ Logs work across all Next.js runtimes: - **Server** — Node.js server-side logging - **Edge** — Edge runtime logging - - On SDK versions below `10.71.0`, logs are opt-in. Set `enableLogs: true` in your `Sentry.init` in all three runtime files to send them. - - @@ -386,7 +382,7 @@ Any attributes set via `Sentry.setAttribute()` / `Sentry.setAttributes()` (or di ### Logs not appearing -On SDK versions below `10.71.0`, logs are opt-in. Make sure `enableLogs: true` is set in **all** Sentry config files: +Logs are captured as soon as you call a `Sentry.logger.*` method or add a logging integration. Check that the runtime you're logging from initializes the SDK at all: - `instrumentation-client.ts` (client) - `sentry.server.config.ts` (server) diff --git a/docs/platforms/javascript/guides/nextjs/manual-setup/index.mdx b/docs/platforms/javascript/guides/nextjs/manual-setup/index.mdx index 4c1fe397b1224a..9791a682ebf3fa 100644 --- a/docs/platforms/javascript/guides/nextjs/manual-setup/index.mdx +++ b/docs/platforms/javascript/guides/nextjs/manual-setup/index.mdx @@ -88,7 +88,7 @@ Extend your app's default Next.js options by adding `withSentryConfig` into your ```typescript {filename:next.config.ts} import type { NextConfig } from "next"; -import { withSentryConfig } from "@sentry/nextjs"; +import { withSentryConfig } from "@sentry/nextjs/config"; const nextConfig: NextConfig = { // Your existing Next.js configuration @@ -156,10 +156,7 @@ Sentry.init({ // ___PRODUCT_OPTION_END___ session-replay }); -// ___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} diff --git a/docs/platforms/javascript/guides/nextjs/manual-setup/pages-router.mdx b/docs/platforms/javascript/guides/nextjs/manual-setup/pages-router.mdx index 0f413ffe91036a..efb074448b81a3 100644 --- a/docs/platforms/javascript/guides/nextjs/manual-setup/pages-router.mdx +++ b/docs/platforms/javascript/guides/nextjs/manual-setup/pages-router.mdx @@ -81,7 +81,7 @@ Extend your app's default Next.js options by adding `withSentryConfig` into your ```typescript {tabTitle:Webpack} {filename:next.config.ts} import type { NextConfig } from "next"; -import { withSentryConfig } from "@sentry/nextjs"; +import { withSentryConfig } from "@sentry/nextjs/config"; const nextConfig: NextConfig = { // Your existing Next.js configuration @@ -112,7 +112,7 @@ export default withSentryConfig(nextConfig, { ```typescript {tabTitle:Turbopack} {filename:next.config.ts} import type { NextConfig } from "next"; -import { withSentryConfig } from "@sentry/nextjs"; +import { withSentryConfig } from "@sentry/nextjs/config"; const nextConfig: NextConfig = { // Your existing Next.js configuration @@ -137,7 +137,7 @@ export default withSentryConfig(nextConfig, { 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 +- `instrumentation-client.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) @@ -146,10 +146,16 @@ Create the following files in your application's root directory (or `src` folder variable like `NEXT_PUBLIC_SENTRY_DSN`. + + +Older setups initialized the browser SDK in `sentry.client.config.ts`. That file is deprecated and is **ignored entirely by Turbopack builds**, which leaves your app with no browser SDK and no build error to tell you. Use `instrumentation-client.ts` instead — it works with both Turbopack and Webpack. + + + -```typescript {tabTitle:Client} {mdExpandTabs} {filename:sentry.client.config.ts} +```typescript {tabTitle:Client} {mdExpandTabs} {filename:instrumentation-client.ts} import * as Sentry from "@sentry/nextjs"; Sentry.init({ @@ -174,6 +180,8 @@ Sentry.init({ replaysOnErrorSampleRate: 1.0, // ___PRODUCT_OPTION_END___ session-replay }); + +export const onRouterTransitionStart = Sentry.captureRouterTransitionStart; ``` ```typescript {tabTitle:Server} {filename:sentry.server.config.ts} @@ -218,6 +226,43 @@ Monitor your [usage stats](https://sentry.io/orgredirect/organizations/:orgslug/ +### Register Server-Side SDK + +Creating `sentry.server.config.ts` isn't enough on its own — nothing imports it. 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) to load it at server startup. + +The `onRequestError` export is what captures server-side errors in the Pages Router, including errors thrown in API routes and `getServerSideProps`. + + + 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 API routes, getServerSideProps, and middleware +export const onRequestError = Sentry.captureRequestError; +``` + + + + + + + ### Capture Pages Router Errors Create or update `pages/_error.tsx` to capture errors that occur during server-side rendering or in page components. @@ -332,7 +377,7 @@ Session Replay captures video-like reproductions of user sessions. It's configur -```typescript {filename:sentry.client.config.ts} +```typescript {filename:instrumentation-client.ts} Sentry.init({ dsn: "___PUBLIC_DSN___", @@ -453,16 +498,33 @@ Automatically create [Cron Monitors](/product/monitors-and-alerts/monitors/crons ### Enable Automatic Cron Monitoring -Add the `automaticVercelMonitors` option to your `next.config.ts`. +There are two ways to do this, depending on how you build: + +- `_experimental.vercelCronsMonitoring` creates check-ins from spans. It works with both Turbopack and Webpack, and with both routers. Prefer this one. +- `webpack.automaticVercelMonitors` wraps your route handlers at build time. It only works with Webpack and the Pages Router. + +If you enable both, the SDK uses the span-based approach and logs a warning telling you to drop the other one. -```typescript {filename:next.config.ts} -import { withSentryConfig } from "@sentry/nextjs"; +```typescript {tabTitle:Span-based} {mdExpandTabs} {filename:next.config.ts} +import { withSentryConfig } from "@sentry/nextjs/config"; export default withSentryConfig(nextConfig, { - automaticVercelMonitors: true, + _experimental: { + vercelCronsMonitoring: true, + }, +}); +``` + +```typescript {tabTitle:Webpack} {filename:next.config.ts} +import { withSentryConfig } from "@sentry/nextjs/config"; + +export default withSentryConfig(nextConfig, { + webpack: { + automaticVercelMonitors: true, + }, }); ``` diff --git a/docs/platforms/javascript/guides/nextjs/manual-setup/webpack-setup.mdx b/docs/platforms/javascript/guides/nextjs/manual-setup/webpack-setup.mdx index f3cb732af68c26..e6595eb830c816 100644 --- a/docs/platforms/javascript/guides/nextjs/manual-setup/webpack-setup.mdx +++ b/docs/platforms/javascript/guides/nextjs/manual-setup/webpack-setup.mdx @@ -20,9 +20,10 @@ For a complete reference of all build configuration options, see the [Build Conf | ------------------------------- | ------------------------------- | ---------------------------------------------------- | | Server function instrumentation | Automatic via Next.js telemetry | Build-time code injection | | Middleware instrumentation | Automatic via Next.js telemetry | Build-time code injection | +| Dependency instrumentation | Next.js 16+ | Supported | | Source map upload | Post-compile during build | During build via plugin (default) | | Route exclusion | Not supported | Supported via `webpack.excludeServerRoutes` | -| React component annotation | Experimental (Next.js 16+) | Supported via `webpack.reactComponentAnnotation` | +| React component annotation | Next.js 16+ | Supported | | Logger tree-shaking | Not supported | Supported via `webpack.treeshake.removeDebugLogging` | ## Auto-Instrumentation Options @@ -44,7 +45,7 @@ These options are enabled by default with Webpack. Disable them if you prefer ma ```typescript {filename:next.config.ts} -import { withSentryConfig } from "@sentry/nextjs"; +import { withSentryConfig } from "@sentry/nextjs/config"; export default withSentryConfig(nextConfig, { webpack: { @@ -92,7 +93,7 @@ Specify routes as URL paths (not file system paths). Routes must have a leading ```typescript {filename:next.config.ts} -import { withSentryConfig } from "@sentry/nextjs"; +import { withSentryConfig } from "@sentry/nextjs/config"; export default withSentryConfig(nextConfig, { webpack: { @@ -129,7 +130,7 @@ The Sentry Webpack Plugin runs during each webpack compilation and uploads sourc ```typescript {filename:next.config.ts} -import { withSentryConfig } from "@sentry/nextjs"; +import { withSentryConfig } from "@sentry/nextjs/config"; export default withSentryConfig(nextConfig, { org: "___ORG_SLUG___", @@ -160,7 +161,7 @@ Enable post-build upload for faster builds. All source maps are uploaded once af ```typescript {filename:next.config.ts} -import { withSentryConfig } from "@sentry/nextjs"; +import { withSentryConfig } from "@sentry/nextjs/config"; export default withSentryConfig(nextConfig, { org: "___ORG_SLUG___", @@ -182,38 +183,32 @@ export default withSentryConfig(nextConfig, { -### Advanced Webpack Plugin Options +### Control Which Files Are Uploaded -Pass options directly to the underlying Sentry Webpack Plugin for advanced configuration. - - - The `unstable_sentryWebpackPluginOptions` API may change in future releases. - +If the defaults pick up too much or too little, narrow the upload with the `sourcemaps` options. These are top-level options and apply to both Webpack and Turbopack builds. - These options only apply when `useRunAfterProductionCompileHook` is `false` - (the default). + Earlier versions reached these settings through + `unstable_sentryWebpackPluginOptions`. That escape hatch was removed — every + option it exposed is now a first-class build option. See [Build + Configuration](/platforms/javascript/guides/nextjs/configuration/build/) for + the full list. ```typescript {filename:next.config.ts} -import { withSentryConfig } from "@sentry/nextjs"; +import { withSentryConfig } from "@sentry/nextjs/config"; 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/**"], - }, - }, + sourcemaps: { + assets: [".next/**/*.js", ".next/**/*.map"], + ignore: ["**/node_modules/**"], }, }); ``` @@ -265,13 +260,15 @@ export async function submitForm(formData: FormData) { ## 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/). +Component annotation adds `data-sentry-*` attributes to your React components at build time, so Sentry can tell you which component a user interacted with in [Session Replay](/platforms/javascript/guides/nextjs/session-replay/) and [breadcrumbs](/platforms/javascript/guides/nextjs/enriching-events/breadcrumbs/). - For Turbopack builds, component annotation is available as an experimental - feature requiring Next.js 16+. See - [`_experimental.turbopackReactComponentAnnotation`](/platforms/javascript/guides/nextjs/configuration/build/#_experimentalturbopackreactcomponentannotationenabled) - in the build options reference. + `reactComponentAnnotation` is a top-level option and drives both Webpack and + Turbopack builds. On Turbopack it requires Next.js 16 or higher — enable it on + an older version and the SDK warns at build time. The bundler-specific + `webpack.reactComponentAnnotation` and + `_experimental.turbopackReactComponentAnnotation` options still work but are + deprecated, and will be removed in the next major version. @@ -287,13 +284,11 @@ Enable `reactComponentAnnotation` to track component names in your application. ```typescript {filename:next.config.ts} -import { withSentryConfig } from "@sentry/nextjs"; +import { withSentryConfig } from "@sentry/nextjs/config"; export default withSentryConfig(nextConfig, { - webpack: { - reactComponentAnnotation: { - enabled: true, - }, + reactComponentAnnotation: { + enabled: true, }, }); ``` @@ -316,14 +311,12 @@ If you have components you don't want annotated (for privacy or performance reas ```typescript {filename:next.config.ts} -import { withSentryConfig } from "@sentry/nextjs"; +import { withSentryConfig } from "@sentry/nextjs/config"; export default withSentryConfig(nextConfig, { - webpack: { - reactComponentAnnotation: { - enabled: true, - ignoredComponents: ["SensitiveForm", "InternalDebugPanel"], - }, + reactComponentAnnotation: { + enabled: true, + ignoredComponents: ["SensitiveForm", "InternalDebugPanel"], }, }); ``` @@ -360,7 +353,7 @@ tunnelRoute: true, // Auto-generated random route ```typescript {filename:next.config.ts} -import { withSentryConfig } from "@sentry/nextjs"; +import { withSentryConfig } from "@sentry/nextjs/config"; export default withSentryConfig(nextConfig, { // Use a fixed route (recommended) @@ -377,20 +370,22 @@ export default withSentryConfig(nextConfig, { If you're upgrading to Turbopack: -1. **Remove webpack-only options** - `excludeServerRoutes` and `unstable_sentryWebpackPluginOptions` have no effect with Turbopack +1. **Drop webpack-only options** - anything under `webpack` has no effect with Turbopack, including `excludeServerRoutes` and `treeshake` 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"], + webpack: { + excludeServerRoutes: ["/api/health"], + }, tunnelRoute: "/sentry-tunnel", }); // After (Turbopack) export default withSentryConfig(nextConfig, { - // excludeServerRoutes is not supported with Turbopack + // webpack.excludeServerRoutes is not supported with Turbopack tunnelRoute: "/sentry-tunnel", }); ``` diff --git a/platform-includes/configuration/filter-application-key/javascript.nextjs.mdx b/platform-includes/configuration/filter-application-key/javascript.nextjs.mdx index 5eca495abeaf22..9641067ed53c81 100644 --- a/platform-includes/configuration/filter-application-key/javascript.nextjs.mdx +++ b/platform-includes/configuration/filter-application-key/javascript.nextjs.mdx @@ -1,27 +1,13 @@ -**Webpack:** - -```javascript {tabTitle:CJS} {filename:next.config.js} {3} -module.exports = withSentryConfig(nextConfig, { - unstable_sentryWebpackPluginOptions: { - applicationKey: "your-custom-application-key", - }, -}); -``` - -```javascript {tabTitle:ESM} {filename:next.config.mjs} {3} +```javascript {tabTitle:ESM} {filename:next.config.mjs} {2} export default withSentryConfig(nextConfig, { - unstable_sentryWebpackPluginOptions: { - applicationKey: "your-custom-application-key", - }, + applicationKey: "your-custom-application-key", }); ``` -**Turbopack (Next.js 16+, experimental):** - -```javascript {filename:next.config.ts} {3} -export default withSentryConfig(nextConfig, { - _experimental: { - turbopackApplicationKey: "your-custom-application-key", - }, +```javascript {tabTitle:CJS} {filename:next.config.js} {2} +module.exports = withSentryConfig(nextConfig, { + applicationKey: "your-custom-application-key", }); ``` + +This works for both Webpack and Turbopack builds. diff --git a/platform-includes/crons/setup/javascript.nextjs.mdx b/platform-includes/crons/setup/javascript.nextjs.mdx index 0f6442a455cb3d..1032edf4a9242f 100644 --- a/platform-includes/crons/setup/javascript.nextjs.mdx +++ b/platform-includes/crons/setup/javascript.nextjs.mdx @@ -5,10 +5,12 @@ Cron monitoring is only supported in Server and Edge runtimes for Next.js If you are hosting your Next.js application on Vercel and you are using [Vercel's Cron Jobs feature](https://vercel.com/docs/cron-jobs), you can configure the Next.js SDK to automatically create Check-Ins for you. Instrumented cron jobs are decided at runtime by examining the `crons` field in your `vercel.json` file. -Set the `automaticVercelMonitors` option to `true` in your Sentry settings in `next.config.js`. See Manual Setup for more details. +Set `_experimental.vercelCronsMonitoring` to `true` in your Sentry settings in `next.config.js`. See Manual Setup for more details. -Automatic instrumentation of Vercel cron jobs currently only works for the Pages Router. App Router route handlers are not yet supported. + The older `webpack.automaticVercelMonitors` option only works with Webpack and + the Pages Router. `_experimental.vercelCronsMonitoring` works with both + bundlers and both routers. ## Automatic Crons Instrumentation diff --git a/platform-includes/getting-started-prerequisites/javascript.nextjs.mdx b/platform-includes/getting-started-prerequisites/javascript.nextjs.mdx index bcb8b057801267..5b4b58a004bbcb 100644 --- a/platform-includes/getting-started-prerequisites/javascript.nextjs.mdx +++ b/platform-includes/getting-started-prerequisites/javascript.nextjs.mdx @@ -2,5 +2,6 @@ You need: -- A Next.js application +- A Next.js application on version 14 or higher +- Node.js 20.19.0 or higher - A Sentry [account](https://sentry.io/signup/) and [project](/product/projects/) diff --git a/platform-includes/sourcemaps/overview/javascript.nextjs.mdx b/platform-includes/sourcemaps/overview/javascript.nextjs.mdx index b03d030a4751a6..c8fd38841a7a77 100644 --- a/platform-includes/sourcemaps/overview/javascript.nextjs.mdx +++ b/platform-includes/sourcemaps/overview/javascript.nextjs.mdx @@ -41,7 +41,7 @@ With **Turbopack** (Next.js 15+ default), source maps upload after the build com ```typescript {filename:next.config.ts} import type { NextConfig } from "next"; -import { withSentryConfig } from "@sentry/nextjs"; +import { withSentryConfig } from "@sentry/nextjs/config"; const nextConfig: NextConfig = { // your existing Next.js config @@ -70,10 +70,7 @@ See Build OptionsWebpack Setup for complete Webpack configuration.