Skip to content

Update Next.js Build Options with content from Manual Setup page #12852

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
merged 3 commits into from
Feb 28, 2025
Merged

Update Next.js Build Options with content from Manual Setup page #12852

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
89691a4
fix formatting
inventarSarah Feb 26, 2025
46d0c19
Merge branch 'master' of github.com:getsentry/sentry-docs into smi/ne…
inventarSarah Feb 26, 2025
e52a7fe
move option position
inventarSarah Feb 26, 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
55 changes: 53 additions & 2 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 @@ -146,6 +146,21 @@ If set to `true`, the Sentry SDK will attempt to tree-shake code related to trac

## Next.js Specific Options

<SdkOption
Copy link
Member

Choose a reason for hiding this comment

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

Let's maybe move this out of Next.js specific options so it is at the same level but on the end of the page!

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

Moved this to the end of the section as discussed 👍

name="unstable_sentryWebpackPluginOptions"
type="SentryWebpackPluginOptions"
>
Pass configuration options directly to the Sentry Webpack Plugin
[`@sentry/webpack-plugin`](https://www.npmjs.com/package/@sentry/webpack-plugin)
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
Pass configuration options directly to the Sentry Webpack Plugin
[`@sentry/webpack-plugin`](https://www.npmjs.com/package/@sentry/webpack-plugin)
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="widenClientFileUpload" type="boolean" defaultValue="false">

Include Next.js-internal code and code from dependencies when uploading source maps.
Expand Down Expand Up @@ -182,11 +197,47 @@ 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">
<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 the Next.js server, to circumvent ad-blockers blocking Sentry events from being sent. This option should be a path (for example: '/error-monitoring').
Tunnel Sentry requests through this route on your Next.js server to prevent ad-blockers from blocking Sentry events from being sent.
This route should be a path, like `/error-monitoring`, as it adds an API endpoint within your application.

Note: This feature only works with Next.js 11+
Learn more about tunneling in the <PlatformLink to="/troubleshooting/#dealing-with-ad-blockers">troubleshooting section</PlatformLink>.

<Expandable level="warning" title="Complications with Next.js middleware">
Client-side event recording will fail if your Next.js middleware intercepts
the configured route. To prevent this, exclude the tunnel route by adding a
negative matcher to your middleware like `(?!monitoring-tunnel)`.
</Expandable>

</SdkOption>

Expand Down