Skip to content

docs(js): Update nextjs docs on tunnelRoute option #14066

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.

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
Jul 8, 2025
Merged
Show file tree
Hide file tree
Changes from 2 commits
Commits
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
Original file line number Diff line number Diff line change
Expand Up @@ -208,20 +208,24 @@ excludeServerRoutes: [

</SdkOption>

<SdkOption name="tunnelRoute" type="string">
<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 route should be a path, like `/error-monitoring`, as it adds an API endpoint within your application.

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="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 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>
Expand Down
8 changes: 5 additions & 3 deletions docs/platforms/javascript/guides/nextjs/manual-setup.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -449,14 +449,16 @@ Make sure to keep your auth token secret and out of version control.

You can prevent ad blockers from blocking Sentry events using tunneling. Use the `tunnelRoute` option to add an API endpoint in your application that forwards Sentry events to Sentry servers.

Update `withSentryConfig` in your `next.config.(js|mjs)` file with the following options:
For better ad-blocker evasion, you can either:
- Set `tunnelRoute: true` to automatically generate a random tunnel route for each build, making it harder for ad-blockers to detect and block monitoring requests
- Set `tunnelRoute: "/my-tunnel-route"` to use a static route of your choosing

```javascript {tabTitle:ESM} {filename:next.config.mjs}
export default withSentryConfig(nextConfig, {
// Route browser requests to Sentry through a Next.js rewrite to circumvent ad-blockers.
// This can increase your server load as well as your hosting bill.
// Note: Check that the configured route will not match with your Next.js middleware, otherwise reporting of client-side errors will fail.
tunnelRoute: "/monitoring",
tunnelRoute: true, // Generates a random route for each build (recommended)
});
```

Expand All @@ -465,7 +467,7 @@ module.exports = withSentryConfig(nextConfig, {
// Route browser requests to Sentry through a Next.js rewrite to circumvent ad-blockers.
// This can increase your server load as well as your hosting bill.
// Note: Check that the configured route will not match with your Next.js middleware, otherwise reporting of client-side errors will fail.
tunnelRoute: "/monitoring",
tunnelRoute: true, // Generates a random route for each build (recommended)
});
```

Expand Down