From a065eb07b9f8b9d640ffd545e65eabcad883eb8d Mon Sep 17 00:00:00 2001
From: Charly Gomez <charly.gomez@sentry.io>
Date: Wed, 18 Jun 2025 12:35:55 +0200
Subject: [PATCH 1/3] update next docs on tunneling option

---
 .../guides/nextjs/configuration/build/index.mdx        | 10 ++++++++--
 .../javascript/guides/nextjs/manual-setup.mdx          |  8 +++++---
 2 files changed, 13 insertions(+), 5 deletions(-)

diff --git a/docs/platforms/javascript/guides/nextjs/configuration/build/index.mdx b/docs/platforms/javascript/guides/nextjs/configuration/build/index.mdx
index d0826b91ef6703..569168132f6216 100644
--- a/docs/platforms/javascript/guides/nextjs/configuration/build/index.mdx
+++ b/docs/platforms/javascript/guides/nextjs/configuration/build/index.mdx
@@ -208,13 +208,17 @@ 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>.
 
@@ -222,6 +226,8 @@ Learn more about tunneling in the <PlatformLink to="/troubleshooting/#dealing-wi
   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>
diff --git a/docs/platforms/javascript/guides/nextjs/manual-setup.mdx b/docs/platforms/javascript/guides/nextjs/manual-setup.mdx
index b83a6d23d19a3a..551cd858e27193 100644
--- a/docs/platforms/javascript/guides/nextjs/manual-setup.mdx
+++ b/docs/platforms/javascript/guides/nextjs/manual-setup.mdx
@@ -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)
 });
 ```
 
@@ -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)
 });
 ```
 

From eeefe88313ec50b3ec17f71dd40a14a02dcd162a Mon Sep 17 00:00:00 2001
From: Charly Gomez <charly.gomez@sentry.io>
Date: Tue, 8 Jul 2025 09:04:38 +0200
Subject: [PATCH 2/3] update middleware note

---
 .../guides/nextjs/configuration/build/index.mdx           | 8 +++-----
 1 file changed, 3 insertions(+), 5 deletions(-)

diff --git a/docs/platforms/javascript/guides/nextjs/configuration/build/index.mdx b/docs/platforms/javascript/guides/nextjs/configuration/build/index.mdx
index 569168132f6216..7ec0aff39f6bbb 100644
--- a/docs/platforms/javascript/guides/nextjs/configuration/build/index.mdx
+++ b/docs/platforms/javascript/guides/nextjs/configuration/build/index.mdx
@@ -222,12 +222,10 @@ This option can be set to:
 
 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.
   
-  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.
+  If you're not using Turbopack, Sentry will automatically skip the tunnel route in your middleware.
 </Expandable>
 
 </SdkOption>

From 658364c7ae27a381f118ee7c98cbb2f13e5bacee Mon Sep 17 00:00:00 2001
From: Charly Gomez <charly.gomez@sentry.io>
Date: Tue, 8 Jul 2025 09:52:18 +0200
Subject: [PATCH 3/3] beepboop

---
 .../javascript/guides/nextjs/manual-setup.mdx          | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/docs/platforms/javascript/guides/nextjs/manual-setup.mdx b/docs/platforms/javascript/guides/nextjs/manual-setup.mdx
index 551cd858e27193..8af7ad484a9633 100644
--- a/docs/platforms/javascript/guides/nextjs/manual-setup.mdx
+++ b/docs/platforms/javascript/guides/nextjs/manual-setup.mdx
@@ -471,11 +471,11 @@ module.exports = withSentryConfig(nextConfig, {
 });
 ```
 
-<Alert 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)`.
-</Alert>
+<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>
 
 ## Step 6: Instrument Vercel Cron Jobs (Optional)