From d6aeaded26317295e81ea4320c0b2f5aeb1e3263 Mon Sep 17 00:00:00 2001 From: Charly Gomez Date: Fri, 13 Mar 2026 10:33:51 +0100 Subject: [PATCH] document experimental turbopack options --- .../common/configuration/filtering.mdx | 5 +- .../nextjs/configuration/build/index.mdx | 83 +++++++++++++++++++ .../nextjs/manual-setup/webpack-setup.mdx | 8 +- .../javascript.nextjs.mdx | 12 +++ 4 files changed, 103 insertions(+), 5 deletions(-) diff --git a/docs/platforms/javascript/common/configuration/filtering.mdx b/docs/platforms/javascript/common/configuration/filtering.mdx index 9bbd33dd47ca4..a84dab6aed903 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). +**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. @@ -157,7 +157,8 @@ See beforeBreadcrumb Hints are available in two places: -1. / +1. / + 2. Event processors added via `Sentry.addEventProcessor()` Event and breadcrumb `hints` are objects containing various types of information used to put together an event or a breadcrumb. Typically `hints` hold the original exception so that additional data can be extracted or grouping can be affected. diff --git a/docs/platforms/javascript/guides/nextjs/configuration/build/index.mdx b/docs/platforms/javascript/guides/nextjs/configuration/build/index.mdx index 2761ed05078b1..a12e9e574e949 100644 --- a/docs/platforms/javascript/guides/nextjs/configuration/build/index.mdx +++ b/docs/platforms/javascript/guides/nextjs/configuration/build/index.mdx @@ -375,3 +375,86 @@ 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 + + + These options are experimental and require **Next.js 16+**. 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, + }, + }, +}); +``` + + + + + +A list of React component names to exclude from annotation in Turbopack builds. + +```javascript {filename:next.config.ts} +import { withSentryConfig } from "@sentry/nextjs"; + +export default withSentryConfig(nextConfig, { + _experimental: { + turbopackReactComponentAnnotation: { + enabled: true, + ignoredComponents: ["SensitiveForm", "InternalDebugPanel"], + }, + }, +}); +``` + + + + + + + +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 {filename:next.config.ts} +import { withSentryConfig } from "@sentry/nextjs"; + +export default withSentryConfig(nextConfig, { + _experimental: { + turbopackApplicationKey: "my-nextjs-app", + }, +}); +``` + +```javascript {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/manual-setup/webpack-setup.mdx b/docs/platforms/javascript/guides/nextjs/manual-setup/webpack-setup.mdx index 0f68432e59543..3d8ef70aaabbf 100644 --- a/docs/platforms/javascript/guides/nextjs/manual-setup/webpack-setup.mdx +++ b/docs/platforms/javascript/guides/nextjs/manual-setup/webpack-setup.mdx @@ -22,7 +22,7 @@ For a complete reference of all build configuration options, see the [Build Conf | 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` | +| React component annotation | Experimental (Next.js 16+) | Supported via `webpack.reactComponentAnnotation` | | Logger tree-shaking | Not supported | Supported via `webpack.treeshake.removeDebugLogging` | ## Auto-Instrumentation Options @@ -268,8 +268,10 @@ export async function submitForm(formData: FormData) { 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. + 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. diff --git a/platform-includes/configuration/filter-application-key/javascript.nextjs.mdx b/platform-includes/configuration/filter-application-key/javascript.nextjs.mdx index 0252e242417a0..5eca495abeaf2 100644 --- a/platform-includes/configuration/filter-application-key/javascript.nextjs.mdx +++ b/platform-includes/configuration/filter-application-key/javascript.nextjs.mdx @@ -1,3 +1,5 @@ +**Webpack:** + ```javascript {tabTitle:CJS} {filename:next.config.js} {3} module.exports = withSentryConfig(nextConfig, { unstable_sentryWebpackPluginOptions: { @@ -13,3 +15,13 @@ export default withSentryConfig(nextConfig, { }, }); ``` + +**Turbopack (Next.js 16+, experimental):** + +```javascript {filename:next.config.ts} {3} +export default withSentryConfig(nextConfig, { + _experimental: { + turbopackApplicationKey: "your-custom-application-key", + }, +}); +```