feat: added warning if the user hasn't configured the matcher properly

Author: logaretm

packages/nextjs/src/config/util.ts

@@ -181,3 +181,37 @@ export function detectActiveBundler(): 'turbopack' | 'webpack' {
     return 'webpack';
   }
 }
+
+/**
+ * Finds the middleware or proxy file in the Next.js project.
+ * Next.js only allows one middleware file, so this returns the first match.
+ */
+export function findMiddlewareFile(): { path: string; contents: string } | undefined {
+  const projectDir = process.cwd();
+
+  // In Next.js 16+, the file is called 'proxy', in earlier versions it's 'middleware'
+  const nextVersion = getNextjsVersion();
+  const nextMajor = nextVersion ? parseSemver(nextVersion).major : undefined;
+  const basename = nextMajor && nextMajor >= 16 ? 'proxy' : 'middleware';
+  const directories = [projectDir, `${projectDir}/src`];
+  const extensions = ['.ts', '.js'];
+
+  // Find the first existing middleware/proxy file
+  for (const dir of directories) {
+    for (const ext of extensions) {
+      const filePath = `${dir}/${basename}${ext}`;
+      if (fs.existsSync(filePath)) {
+        try {
+          const contents = fs.readFileSync(filePath, 'utf-8');
+
+          return { path: filePath, contents };
+        } catch {
+          // If we can't read the file, continue searching
+          continue;
+        }
+      }
+    }
+  }
+
+  return undefined;
+}

packages/nextjs/src/config/withSentryConfig.ts

@@ -18,6 +18,7 @@ import type {
 } from './types';
 import {
   detectActiveBundler,
+  findMiddlewareFile,
   getNextjsVersion,
   requiresInstrumentationHook,
   supportsProductionCompileHook,
@@ -26,6 +27,7 @@ import { constructWebpackConfigFunction } from './webpack';
 
 let showedExportModeTunnelWarning = false;
 let showedExperimentalBuildModeWarning = false;
+let showedMiddlewareMatcherWarning = false;
 
 // Packages we auto-instrument need to be external for instrumentation to work
 // Next.js externalizes some packages by default, see: https://nextjs.org/docs/app/api-reference/config/next-config-js/serverExternalPackages
@@ -89,6 +91,50 @@ 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.
+ */
+function checkMiddlewareMatcherForTunnelRoute(tunnelPath: string): void {
+  if (showedMiddlewareMatcherWarning) {
+    return;
+  }
+
+  try {
+    const middlewareFile = findMiddlewareFile();
+
+    // No middleware file found
+    if (!middlewareFile) {
+      return;
+    }
+
+    // Check if they're already using withSentryTunnelExclusion
+    if (middlewareFile.contents.includes('withSentryTunnelExclusion')) {
+      return;
+    }
+
+    // Look for config.matcher export
+    const isProxy = middlewareFile.path.includes('proxy');
+    const hasConfigMatcher = /export\s+const\s+config\s*=\s*{[^}]*matcher\s*:/s.test(middlewareFile.contents);
+
+    if (hasConfigMatcher) {
+      // 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',
+      );
+      showedMiddlewareMatcherWarning = true;
+    }
+  } catch {
+    // Silently fail - this is just a helpful warning, not critical
+  }
+}
+
 /**
  * Generates a random tunnel route path that's less likely to be blocked by ad-blockers
  */
@@ -126,6 +172,7 @@ function getFinalConfigObject(
       userSentryOptions.tunnelRoute = resolvedTunnelRoute || undefined;
 
       setUpTunnelRewriteRules(incomingUserNextConfigObject, resolvedTunnelRoute);
+      checkMiddlewareMatcherForTunnelRoute(resolvedTunnelRoute);
     }
   }
 

packages/nextjs/test/config/util.test.ts

@@ -1,4 +1,6 @@
-import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import * as fs from 'fs';
+import * as path from 'path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import * as util from '../../src/config/util';
 
 describe('util', () => {
@@ -334,4 +336,134 @@ describe('util', () => {
       expect(util.detectActiveBundler()).toBe('webpack');
     });
   });
+
+  describe('findMiddlewareFile', () => {
+    vi.mock('../../src/config/util', async () => {
+      const actual = await vi.importActual('../../src/config/util');
+      return {
+        ...actual,
+        getNextjsVersion: vi.fn(),
+      };
+    });
+
+    let originalCwd: string;
+    let testDir: string;
+
+    beforeEach(() => {
+      originalCwd = process.cwd();
+      testDir = path.join(__dirname, '.test-middleware-temp');
+
+      // Create test directory
+      if (!fs.existsSync(testDir)) {
+        fs.mkdirSync(testDir, { recursive: true });
+      }
+
+      process.chdir(testDir);
+    });
+
+    afterEach(() => {
+      process.chdir(originalCwd);
+
+      // Clean up test directory
+      if (fs.existsSync(testDir)) {
+        fs.rmSync(testDir, { recursive: true, force: true });
+      }
+
+      vi.clearAllMocks();
+    });
+
+    describe('Next.js <16 (middleware)', () => {
+      beforeEach(() => {
+        vi.mocked(util.getNextjsVersion).mockReturnValue('15.0.0');
+      });
+
+      it('should find middleware.ts in root directory', () => {
+        fs.writeFileSync(path.join(testDir, 'middleware.ts'), 'export default function middleware() {}');
+
+        const result = util.findMiddlewareFile();
+
+        expect(result).toBeDefined();
+        expect(result?.path).toContain('middleware.ts');
+        expect(result?.contents).toBe('export default function middleware() {}');
+      });
+
+      it('should find middleware.js in root directory', () => {
+        fs.writeFileSync(path.join(testDir, 'middleware.js'), 'module.exports = function middleware() {}');
+
+        const result = util.findMiddlewareFile();
+
+        expect(result).toBeDefined();
+        expect(result?.path).toContain('middleware.js');
+        expect(result?.contents).toBe('module.exports = function middleware() {}');
+      });
+
+      it('should find middleware.ts in src directory', () => {
+        fs.mkdirSync(path.join(testDir, 'src'), { recursive: true });
+        fs.writeFileSync(path.join(testDir, 'src', 'middleware.ts'), 'export default function middleware() {}');
+
+        const result = util.findMiddlewareFile();
+
+        expect(result).toBeDefined();
+        expect(result?.path).toContain(path.join('src', 'middleware.ts'));
+        expect(result?.contents).toBe('export default function middleware() {}');
+      });
+
+      it('should prefer root over src directory', () => {
+        fs.mkdirSync(path.join(testDir, 'src'), { recursive: true });
+        fs.writeFileSync(path.join(testDir, 'middleware.ts'), 'root middleware');
+        fs.writeFileSync(path.join(testDir, 'src', 'middleware.ts'), 'src middleware');
+
+        const result = util.findMiddlewareFile();
+
+        expect(result).toBeDefined();
+        expect(result?.contents).toBe('root middleware');
+      });
+
+      it('should prefer .ts over .js extension', () => {
+        fs.writeFileSync(path.join(testDir, 'middleware.ts'), 'typescript middleware');
+        fs.writeFileSync(path.join(testDir, 'middleware.js'), 'javascript middleware');
+
+        const result = util.findMiddlewareFile();
+
+        expect(result).toBeDefined();
+        expect(result?.contents).toBe('typescript middleware');
+      });
+
+      it('should NOT find proxy.ts on Next.js <16', () => {
+        fs.writeFileSync(path.join(testDir, 'proxy.ts'), 'export default function proxy() {}');
+
+        const result = util.findMiddlewareFile();
+
+        expect(result).toBeUndefined();
+      });
+
+      it('should return undefined when no middleware file exists', () => {
+        const result = util.findMiddlewareFile();
+
+        expect(result).toBeUndefined();
+      });
+    });
+
+    // Note: Tests for Next.js 16+ (proxy) behavior would require mocking getNextjsVersion,
+    // which is challenging in this test setup due to module imports.
+    // The logic is the same as middleware tests but with 'proxy' instead of 'middleware'.
+
+    describe('edge cases', () => {
+      beforeEach(() => {
+        vi.mocked(util.getNextjsVersion).mockReturnValue('15.0.0');
+      });
+
+      it('should handle when getNextjsVersion returns undefined', () => {
+        vi.mocked(util.getNextjsVersion).mockReturnValue(undefined);
+
+        fs.writeFileSync(path.join(testDir, 'middleware.ts'), 'export default function middleware() {}');
+
+        const result = util.findMiddlewareFile();
+
+        // Should default to 'middleware' when version is unknown
+        expect(result).toBeDefined();
+        expect(result?.path).toContain('middleware.ts');
+      });
+    });
+  });
 });