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

Draft
wants to merge 1 commit into
base: master
Choose a base branch
from
Draft
Show file tree
Hide file tree
Changes from all 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,26 @@ 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)`.

In the case of auto-generated routes, the route is unpredictable and changes with each deployment. Instead of using a negative matcher, you can add an allowlist of matchers for the routes you want your middleware to handle or fallback to a custom static path.
</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