ref: better DX with config wrapping instead of property wrapping

Author: logaretm

packages/nextjs/src/common/index.ts

@@ -12,4 +12,4 @@ export { wrapPageComponentWithSentry } from './pages-router-instrumentation/wrap
 export { wrapGenerationFunctionWithSentry } from './wrapGenerationFunctionWithSentry';
 export { withServerActionInstrumentation } from './withServerActionInstrumentation';
 export { captureRequestError } from './captureRequestError';
-export { withSentryTunnelExclusion } from './withSentryTunnelExclusion';
+export { withSentryMiddlewareConfig, withSentryProxyConfig } from './withSentryMiddlewareConfig';

packages/nextjs/src/common/withSentryMiddlewareConfig.ts

@@ -0,0 +1,78 @@
+import { GLOBAL_OBJ } from '@sentry/core';
+
+const globalWithInjectedValues = GLOBAL_OBJ as typeof GLOBAL_OBJ & {
+  _sentryRewritesTunnelPath?: string;
+};
+
+/**
+ * Middleware config type for Next.js
+ */
+type MiddlewareConfig = {
+  [key: string]: unknown;
+  matcher?: string | string[];
+};
+
+/**
+ * Configures middleware/proxy settings with Sentry-specific adjustments.
+ * Automatically excludes the Sentry tunnel route from the matcher to prevent interference.
+ *
+ * @example
+ * ```ts
+ * // middleware.ts (Next.js <16)
+ * import { withSentryMiddlewareConfig } from '@sentry/nextjs';
+ *
+ * export const config = withSentryMiddlewareConfig({
+ *   matcher: ['/api/:path*', '/admin/:path*'],
+ * });
+ * ```
+ *
+ * @example
+ * ```ts
+ * // proxy.ts (Next.js 16+)
+ * import { withSentryProxyConfig } from '@sentry/nextjs';
+ *
+ * export const config = withSentryProxyConfig({
+ *   matcher: ['/api/:path*', '/admin/:path*'],
+ * });
+ * ```
+ *
+ * @param config - Middleware/proxy configuration object
+ * @returns Updated config with Sentry tunnel route excluded from matcher
+ */
+export function withSentryMiddlewareConfig(config: MiddlewareConfig): MiddlewareConfig {
+  const tunnelPath = process.env._sentryRewritesTunnelPath || globalWithInjectedValues._sentryRewritesTunnelPath;
+
+  // If no tunnel path or no matcher, return config as-is
+  if (!tunnelPath || !config.matcher) {
+    return config;
+  }
+
+  // Convert to array for easier handling
+  const matchers = Array.isArray(config.matcher) ? config.matcher : [config.matcher];
+
+  // Add negated matcher for the tunnel route
+  // This tells Next.js to NOT run middleware on the tunnel path
+  const tunnelExclusion = `/((?!${tunnelPath.replace(/^\//, '')}).*)`;
+
+  // Return updated config with tunnel exclusion
+  return {
+    ...config,
+    matcher: [...matchers, tunnelExclusion],
+  };
+}
+
+/**
+ * Alias for `withSentryMiddlewareConfig` to support Next.js 16+ terminology.
+ * In Next.js 16+, middleware files are called "proxy" files.
+ *
+ * @example
+ * ```ts
+ * // proxy.ts (Next.js 16+)
+ * import { withSentryProxyConfig } from '@sentry/nextjs';
+ *
+ * export const config = withSentryProxyConfig({
+ *   matcher: ['/api/:path*', '/admin/:path*'],
+ * });
+ * ```
+ */
+export const withSentryProxyConfig = withSentryMiddlewareConfig;

packages/nextjs/src/common/withSentryTunnelExclusion.ts

@@ -93,7 +93,7 @@ export function withSentryConfig<C>(nextConfig?: C, sentryBuildOptions: SentryBu
 
 /**
  * Checks if the user has a middleware/proxy file with a matcher that might exclude the tunnel route.
- * Warns the user if they have a matcher but are not using withSentryTunnelExclusion.
+ * Warns the user if they have a matcher but are not using withSentryMiddlewareConfig or withSentryProxyConfig.
  */
 function checkMiddlewareMatcherForTunnelRoute(tunnelPath: string): void {
   if (showedMiddlewareMatcherWarning) {
@@ -108,8 +108,11 @@ function checkMiddlewareMatcherForTunnelRoute(tunnelPath: string): void {
       return;
     }
 
-    // Check if they're already using withSentryTunnelExclusion
-    if (middlewareFile.contents.includes('withSentryTunnelExclusion')) {
+    // Check if they're already using Sentry middleware/proxy config helpers
+    if (
+      middlewareFile.contents.includes('withSentryMiddlewareConfig') ||
+      middlewareFile.contents.includes('withSentryProxyConfig')
+    ) {
       return;
     }
 
@@ -118,15 +121,16 @@ function checkMiddlewareMatcherForTunnelRoute(tunnelPath: string): void {
     const hasConfigMatcher = /export\s+const\s+config\s*=\s*{[^}]*matcher\s*:/s.test(middlewareFile.contents);
 
     if (hasConfigMatcher) {
+      const helperName = isProxy ? 'withSentryProxyConfig' : 'withSentryMiddlewareConfig';
       // eslint-disable-next-line no-console
       console.warn(
         `[@sentry/nextjs] WARNING: You have a ${isProxy ? 'proxy' : 'middleware'} file (${path.basename(middlewareFile.path)}) with a \`config.matcher\`. ` +
           `If your matcher does not include the Sentry tunnel route (${tunnelPath}), tunnel requests may be blocked. ` +
-          "To ensure your matcher doesn't interfere with Sentry event delivery, wrap your matcher with `withSentryTunnelExclusion`:\n\n" +
-          "  import { withSentryTunnelExclusion } from '@sentry/nextjs';\n" +
-          '  export const config = {\n' +
-          "    matcher: withSentryTunnelExclusion(['/your/routes']),\n" +
-          '  };\n',
+          `To ensure your matcher doesn't interfere with Sentry event delivery, wrap your config with \`${helperName}\`:\n\n` +
+          `  import { ${helperName} } from '@sentry/nextjs';\n` +
+          `  export const config = ${helperName}({\n` +
+          "    matcher: ['/your/routes'],\n" +
+          '  });\n',
       );
       showedMiddlewareMatcherWarning = true;
     }