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

Merged
logaretm merged 6 commits into from
Dec 11, 2025
+59 −60
Merged

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

Changes from 5 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
2079727
docs: rename webpack-related configurations to be under the webpack n…
logaretm Dec 2, 2025
02ebe14
docs: sectioning
logaretm Dec 2, 2025
9b595a7
Update docs/platforms/javascript/guides/nextjs/configuration/build/in…
logaretm Dec 4, 2025
9074117
docs: remove uneeded alert
logaretm Dec 10, 2025
96c1a84
fix: config path
logaretm Dec 11, 2025
29452f2
fix: move the non webpack option outside of the section
logaretm Dec 11, 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
137 changes: 68 additions & 69 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,50 +182,6 @@ Note: Enabling this option can lead to longer build times.

</SdkOption>

<SdkOption name="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">

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

</SdkOption>

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

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

</SdkOption>

<SdkOption name="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.

When defining routes, note the following:

- Specify pages as routes and not as file system paths. For example, write `/animals` instead of `pages/animals/index.js`.
- Make sure that any provided string matches the route exactly, has a leading slash, and doesn't have a trailing slash.

```javascript
excludeServerRoutes: [
"/some/excluded/route",
"/excluded/route/with/[parameter]",
/^\/route\/beginning\/with\/some\/prefix/,
/\/routeContainingASpecificPathSegment\/?/,
];
```

<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.
Expand All @@ -251,58 +207,74 @@ Learn more about tunneling in the <PlatformLink to="/troubleshooting/#dealing-wi

</SdkOption>

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

Automatically create cron monitors in Sentry for your Vercel Cron Jobs if configured via `vercel.json`.
<Alert level="info" title="Version support">
You can use this option with Next.js version 15.4.1 and later.
</Alert>

</SdkOption>
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.

<SdkOption name="disableManifestInjection" type="boolean|undefined" defaultValue="false">
- 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).

Disables automatic injection of the route manifest into the client bundle.
**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.

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.).
</SdkOption>

**Disable this option if:**
## Next.js Webpack Options

- 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)
<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="reactComponentAnnotation.enabled" type="boolean" defaultValue="false">
<SdkOption name="webpack.autoInstrumentMiddleware" type="boolean" defaultValue="true">

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.
Automatically instrument Next.js middleware with error and performance monitoring.

</SdkOption>

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

A list of React component names to exclude from component annotation.
Automatically instrument components in the `app` directory with error monitoring.

</SdkOption>

<SdkOption name="useRunAfterProductionCompileHook" type="boolean" defaultValue="false(webpack)|true(turbopack)">
<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.

<Alert level="info" title="Version support">
You can use this option with Next.js version 15.4.1 and later.
</Alert>
When defining routes, note the following:

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.
- Specify pages as routes and not as file system paths. For example, write `/animals` instead of `pages/animals/index.js`.
- Make sure that any provided string matches the route exactly, has a leading slash, and doesn't have a trailing slash.

- 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).
```javascript
webpack.excludeServerRoutes: [
"/some/excluded/route",
"/excluded/route/with/[parameter]",
/^\/route\/beginning\/with\/some\/prefix/,
/\/routeContainingASpecificPathSegment\/?/,
];
```

**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="webpack.automaticVercelMonitors" type="boolean" defaultValue="false">

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

</SdkOption>
</SdkOption>

<SdkOption
name="unstable_sentryWebpackPluginOptions"
name="webpack.unstable_sentryWebpackPluginOptions"
type="SentryWebpackPluginOptions"
>
Pass configuration options directly to the [Sentry Webpack
Expand All @@ -315,3 +287,30 @@ Enables the use of the [`runAfterProductionCompile` hook from Next.js](https://n
in any release.
</Alert>
</SdkOption>

<SdkOption name="disableManifestInjection" type="boolean|undefined" defaultValue="false">

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)

</SdkOption>

<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="webpack.reactComponentAnnotation.ignoredComponents" type="string[] | undefined">

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

</SdkOption>
Loading