Skip to content

docs(nextjs): Move webpack build config under webpack namespace #15691

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
logaretm wants to merge 3 commits into
base: master
Choose a base branch
from
Draft

docs(nextjs): Move webpack build config under webpack namespace #15691

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
0122bf6
docs: rename webpack-related configurations to be under the webpack n…
logaretm Dec 2, 2025
5e388fb
docs: sectioning
logaretm Dec 2, 2025
86dcd1a
Update docs/platforms/javascript/guides/nextjs/configuration/build/in…
logaretm Dec 4, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
131 changes: 68 additions & 63 deletions docs/platforms/javascript/guides/nextjs/configuration/build/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -182,25 +182,72 @@ Note: Enabling this option can lead to longer build times.

</SdkOption>

<SdkOption name="autoInstrumentServerFunctions" type="boolean" defaultValue="true">
<SdkOption name="tunnelRoute" type="string | boolean">
<Alert level="info">
This feature requires **Next.js version 11+** and doesn't currently work with self-hosted Sentry instances.
</Alert>

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 <PlatformLink to="/troubleshooting/#dealing-with-ad-blockers">troubleshooting section</PlatformLink>.

<Expandable level="warning" title="Using Next.js middleware on Turbopack">
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.
</Expandable>

</SdkOption>

<SdkOption name="useRunAfterProductionCompileHook" type="boolean" defaultValue="false(webpack)|true(turbopack)">

<Alert level="info" title="Version support">
You can use this option with Next.js version 15.4.1 and later.
</Alert>

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.

</SdkOption>

## Next.js Webpack Options

<Alert level="info">
These options only take effect if you're using Webpack. If you're using
Turbopack, these options will have no effect.
</Alert>

<SdkOption name="webpack.autoInstrumentServerFunctions" type="boolean" defaultValue="true">

Automatically instrument Next.js data fetching methods and Next.js API routes with error and performance monitoring.

</SdkOption>

<SdkOption name="autoInstrumentMiddleware" type="boolean" defaultValue="true">
<SdkOption name="webpack.autoInstrumentMiddleware" type="boolean" defaultValue="true">

Automatically instrument Next.js middleware with error and performance monitoring.

</SdkOption>

<SdkOption name="autoInstrumentAppDirectory" type="boolean" defaultValue="true">
<SdkOption name="webpack.autoInstrumentAppDirectory" type="boolean" defaultValue="true">

Automatically instrument components in the `app` directory with error monitoring.

</SdkOption>

<SdkOption name="excludeServerRoutes" type="Array<RegExp | string>">
<SdkOption name="webpack.excludeServerRoutes" type="Array<RegExp | string>">
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.

Expand All @@ -226,35 +273,25 @@ excludeServerRoutes: [

Copy link
Collaborator

@inventarSarah inventarSarah Dec 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we can remove the alert about Turbopack in the lines above. wdyt?

This one:

<Alert level="info">
  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.
</Alert>

</SdkOption>

<SdkOption name="tunnelRoute" type="string | boolean">
<Alert level="info">
This feature requires **Next.js version 11+** and doesn't currently work with self-hosted Sentry instances.
</Alert>

Tunnel Sentry requests through this route on your Next.js server to prevent ad-blockers from blocking Sentry events from being sent.
<SdkOption name="webpack.automaticVercelMonitors" type="boolean" defaultValue="false">

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 <PlatformLink to="/troubleshooting/#dealing-with-ad-blockers">troubleshooting section</PlatformLink>.

<Expandable level="warning" title="Using Next.js middleware on Turbopack">
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.
</Expandable>
Automatically create cron monitors in Sentry for your Vercel Cron Jobs if configured via `vercel.json`.

</SdkOption>

<SdkOption name="automaticVercelMonitors" type="boolean" defaultValue="false">

Automatically create cron monitors in Sentry for your Vercel Cron Jobs if configured via `vercel.json`.

<SdkOption
name="webpack.unstable_sentryWebpackPluginOptions"
type="SentryWebpackPluginOptions"
>
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.
<Alert level="warning" title="Important">
This option is considered unstable, and its API may change in a breaking way
in any release.
</Alert>
</SdkOption>

<SdkOption name="disableManifestInjection" type="boolean|undefined" defaultValue="false">
Expand All @@ -272,46 +309,14 @@ The route manifest is a build-time generated mapping of your Next.js App Router

</SdkOption>

<SdkOption name="reactComponentAnnotation.enabled" type="boolean" defaultValue="false">
<SdkOption name="webpack.reactComponentAnnotation.enabled" type="boolean" defaultValue="false">

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.

</SdkOption>

<SdkOption name="reactComponentAnnotation.ignoredComponents" type="string[] | undefined">
<SdkOption name="webpack.reactComponentAnnotation.ignoredComponents" type="string[] | undefined">

A list of React component names to exclude from component annotation.

</SdkOption>

<SdkOption name="useRunAfterProductionCompileHook" type="boolean" defaultValue="false(webpack)|true(turbopack)">

<Alert level="info" title="Version support">
You can use this option with Next.js version 15.4.1 and later.
</Alert>

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.



</SdkOption>

<SdkOption
name="unstable_sentryWebpackPluginOptions"
type="SentryWebpackPluginOptions"
>
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.
<Alert level="warning" title="Important">
This option is considered unstable, and its API may change in a breaking way
in any release.
</Alert>
</SdkOption>
Loading