From 2079727adecc1af0db0ac241c2f360260d2c9838 Mon Sep 17 00:00:00 2001 From: Abdelrahman Awad Date: Tue, 2 Dec 2025 15:33:32 +0100 Subject: [PATCH 1/6] docs: rename webpack-related configurations to be under the webpack namespace --- .../nextjs/configuration/build/index.mdx | 98 +++++++++---------- 1 file changed, 48 insertions(+), 50 deletions(-) diff --git a/docs/platforms/javascript/guides/nextjs/configuration/build/index.mdx b/docs/platforms/javascript/guides/nextjs/configuration/build/index.mdx index 64d59a2ae90132..5715f424d336a2 100644 --- a/docs/platforms/javascript/guides/nextjs/configuration/build/index.mdx +++ b/docs/platforms/javascript/guides/nextjs/configuration/build/index.mdx @@ -182,25 +182,50 @@ Note: Enabling this option can lead to longer build times. - + + +This feature requires **Next.js version 11+** and doesn't currently work with self-hosted Sentry instances. + + +Tunnel Sentry requests through this route on your Next.js server to prevent ad-blockers from blocking Sentry events from being sent. + +This option can be set to: + +- `true` for auto-generated routes, which are unpredictable and change with each deployment. +- A custom static string path like `/error-monitoring`. + +Learn more about tunneling in the troubleshooting section. + + + 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. + + + + + Automatically instrument Next.js data fetching methods and Next.js API routes with error and performance monitoring. - + Automatically instrument Next.js middleware with error and performance monitoring. - + Automatically instrument components in the `app` directory with error monitoring. - + Exclude specific server-side API routes or pages from automatic Sentry instrumentation during build time. This option takes an array of strings or regular expressions and affects pages in the `pages` and `app` directories. @@ -226,35 +251,25 @@ excludeServerRoutes: [ - - -This feature requires **Next.js version 11+** and doesn't currently work with self-hosted Sentry instances. - - -Tunnel Sentry requests through this route on your Next.js server to prevent ad-blockers from blocking Sentry events from being sent. - -This option can be set to: - -- `true` for auto-generated routes, which are unpredictable and change with each deployment. -- A custom static string path like `/error-monitoring`. - -Learn more about tunneling in the troubleshooting section. + - - 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. - +Automatically create cron monitors in Sentry for your Vercel Cron Jobs if configured via `vercel.json`. - - -Automatically create cron monitors in Sentry for your Vercel Cron Jobs if configured via `vercel.json`. - + + 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. + @@ -272,13 +287,13 @@ The route manifest is a build-time generated mapping of your Next.js App Router - + 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. @@ -287,8 +302,8 @@ A list of React component names to exclude from component annotation. - You can use this option with Next.js version 15.4.1 and later. - + You can use this option with Next.js version 15.4.1 and later. + Enables the use of the [`runAfterProductionCompile` hook from Next.js](https://nextjs.org/docs/architecture/nextjs-compiler#runafterproductioncompile) to upload sourcemaps after the build is completed. @@ -297,21 +312,4 @@ Enables the use of the [`runAfterProductionCompile` hook from Next.js](https://n **Important:** Enabling this option will mutate your Next.js build output by injecting [Debug IDs](/platforms/javascript/guides/nextjs/sourcemaps/troubleshooting_js/debug-ids/) via the Sentry CLI. If you are relying on any sort of integrity hashes for your build artifacts, you will need to disable this option. - - - - - - 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. - From 02ebe14f869278c140bcdaf7ca689d371c394475 Mon Sep 17 00:00:00 2001 From: Abdelrahman Awad Date: Tue, 2 Dec 2025 15:45:50 +0100 Subject: [PATCH 2/6] docs: sectioning --- .../nextjs/configuration/build/index.mdx | 37 +++++++++++-------- 1 file changed, 22 insertions(+), 15 deletions(-) diff --git a/docs/platforms/javascript/guides/nextjs/configuration/build/index.mdx b/docs/platforms/javascript/guides/nextjs/configuration/build/index.mdx index 5715f424d336a2..62fb581a760767 100644 --- a/docs/platforms/javascript/guides/nextjs/configuration/build/index.mdx +++ b/docs/platforms/javascript/guides/nextjs/configuration/build/index.mdx @@ -207,6 +207,28 @@ Learn more about tunneling in the + + + You can use this option with Next.js version 15.4.1 and later. + + +Enables the use of the [`runAfterProductionCompile` hook from Next.js](https://nextjs.org/docs/architecture/nextjs-compiler#runafterproductioncompile) to upload sourcemaps after the build is completed. + +- This option is set to `true` by default for Turbopack as there are no alternative ways to upload sourcemaps here. +- This option is set to `false` for Webpack as the default behavior is to upload sourcemaps during the build process using the [Sentry Webpack Plugin](https://github.com/getsentry/sentry-javascript-bundler-plugins). + +**Important:** Enabling this option will mutate your Next.js build output by injecting [Debug IDs](/platforms/javascript/guides/nextjs/sourcemaps/troubleshooting_js/debug-ids/) via the Sentry CLI. If you are relying on any sort of integrity hashes for your build artifacts, you will need to disable this option. + + + +## Next.js Webpack Options + + + These options only take effect if you are using Webpack. If you are using + Turbopack, these options will have no effect. + + Automatically instrument Next.js data fetching methods and Next.js API routes with error and performance monitoring. @@ -298,18 +320,3 @@ Enables React component name tracking. When enabled, it annotates React componen A list of React component names to exclude from component annotation. - - - - - You can use this option with Next.js version 15.4.1 and later. - - -Enables the use of the [`runAfterProductionCompile` hook from Next.js](https://nextjs.org/docs/architecture/nextjs-compiler#runafterproductioncompile) to upload sourcemaps after the build is completed. - -- This option is set to `true` by default for Turbopack as there are no alternative ways to upload sourcemaps here. -- This option is set to `false` for Webpack as the default behavior is to upload sourcemaps during the build process using the [Sentry Webpack Plugin](https://github.com/getsentry/sentry-javascript-bundler-plugins). - -**Important:** Enabling this option will mutate your Next.js build output by injecting [Debug IDs](/platforms/javascript/guides/nextjs/sourcemaps/troubleshooting_js/debug-ids/) via the Sentry CLI. If you are relying on any sort of integrity hashes for your build artifacts, you will need to disable this option. - - From 9b595a7d9b92d58bd88a4c3a3ba25129eda35d0d Mon Sep 17 00:00:00 2001 From: Abdelrahman Awad Date: Thu, 4 Dec 2025 15:02:15 +0100 Subject: [PATCH 3/6] Update docs/platforms/javascript/guides/nextjs/configuration/build/index.mdx Co-authored-by: Sarah Mischinger --- .../javascript/guides/nextjs/configuration/build/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/javascript/guides/nextjs/configuration/build/index.mdx b/docs/platforms/javascript/guides/nextjs/configuration/build/index.mdx index 62fb581a760767..62bc8e04c24a32 100644 --- a/docs/platforms/javascript/guides/nextjs/configuration/build/index.mdx +++ b/docs/platforms/javascript/guides/nextjs/configuration/build/index.mdx @@ -225,7 +225,7 @@ Enables the use of the [`runAfterProductionCompile` hook from Next.js](https://n ## Next.js Webpack Options - These options only take effect if you are using Webpack. If you are using + These options only take effect if you're using Webpack. If you're using Turbopack, these options will have no effect. From 9074117143d9342e1bef96783659e207264773b4 Mon Sep 17 00:00:00 2001 From: Abdelrahman Awad Date: Wed, 10 Dec 2025 11:30:48 +0200 Subject: [PATCH 4/6] docs: remove uneeded alert --- .../javascript/guides/nextjs/configuration/build/index.mdx | 6 ------ 1 file changed, 6 deletions(-) diff --git a/docs/platforms/javascript/guides/nextjs/configuration/build/index.mdx b/docs/platforms/javascript/guides/nextjs/configuration/build/index.mdx index 62bc8e04c24a32..185072396f2dff 100644 --- a/docs/platforms/javascript/guides/nextjs/configuration/build/index.mdx +++ b/docs/platforms/javascript/guides/nextjs/configuration/build/index.mdx @@ -265,12 +265,6 @@ excludeServerRoutes: [ ]; ``` - - If you're building your Next.js application with Turbopack, this option will - have no effect. The Sentry SDK will no longer apply build-time instrumentation - and will rely purely on Next.js telemetry features. - - From 96c1a845610eb852df3afb9404daa3ebf5c43a32 Mon Sep 17 00:00:00 2001 From: Abdelrahman Awad Date: Thu, 11 Dec 2025 12:32:15 +0200 Subject: [PATCH 5/6] fix: config path --- .../javascript/guides/nextjs/configuration/build/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/javascript/guides/nextjs/configuration/build/index.mdx b/docs/platforms/javascript/guides/nextjs/configuration/build/index.mdx index 185072396f2dff..59fdf8435eebcc 100644 --- a/docs/platforms/javascript/guides/nextjs/configuration/build/index.mdx +++ b/docs/platforms/javascript/guides/nextjs/configuration/build/index.mdx @@ -257,7 +257,7 @@ When defining routes, note the following: - Make sure that any provided string matches the route exactly, has a leading slash, and doesn't have a trailing slash. ```javascript -excludeServerRoutes: [ +webpack.excludeServerRoutes: [ "/some/excluded/route", "/excluded/route/with/[parameter]", /^\/route\/beginning\/with\/some\/prefix/, From 29452f293711e685420ba0f103f03504a5ab1136 Mon Sep 17 00:00:00 2001 From: Abdelrahman Awad Date: Thu, 11 Dec 2025 12:52:53 +0200 Subject: [PATCH 6/6] fix: move the non webpack option outside of the section --- .../nextjs/configuration/build/index.mdx | 30 +++++++++---------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/docs/platforms/javascript/guides/nextjs/configuration/build/index.mdx b/docs/platforms/javascript/guides/nextjs/configuration/build/index.mdx index 59fdf8435eebcc..ee94a816e83c28 100644 --- a/docs/platforms/javascript/guides/nextjs/configuration/build/index.mdx +++ b/docs/platforms/javascript/guides/nextjs/configuration/build/index.mdx @@ -222,6 +222,21 @@ Enables the use of the [`runAfterProductionCompile` hook from Next.js](https://n + + +Disables automatic injection of the route manifest into the client bundle. + +The route manifest is a build-time generated mapping of your Next.js App Router routes that enables Sentry to group transactions by parameterized route names (e.g., `/users/:id` instead of `/users/123`, `/users/456`, etc.). + +**Disable this option if:** + +- You want to minimize client bundle size +- You're experiencing build issues related to route scanning +- You prefer raw URLs in transaction names +- You're only using the Pages Router (this feature is only supported in the App Router) + + + ## Next.js Webpack Options @@ -288,21 +303,6 @@ Automatically create cron monitors in Sentry for your Vercel Cron Jobs if config - - -Disables automatic injection of the route manifest into the client bundle. - -The route manifest is a build-time generated mapping of your Next.js App Router routes that enables Sentry to group transactions by parameterized route names (e.g., `/users/:id` instead of `/users/123`, `/users/456`, etc.). - -**Disable this option if:** - -- You want to minimize client bundle size -- You're experiencing build issues related to route scanning -- You prefer raw URLs in transaction names -- You're only using the Pages Router (this feature is only supported in the App Router) - - - 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.