feat: added routeManifestInjection exclude options to disable manifest for specific pages

Author: logaretm

packages/nextjs/src/config/types.ts

@@ -603,20 +603,59 @@ export type SentryBuildOptions = {
   /**
    * Disables automatic injection of the route manifest into the client bundle.
    *
+   * @deprecated Use `routeManifestInjection: false` instead.
+   *
+   * @default false
+   */
+  disableManifestInjection?: boolean;
+
+  /**
+   * Options for the route manifest injection feature.
+   *
    * The route manifest is a build-time generated mapping of your Next.js App Router
    * routes that enables Sentry to group transactions by parameterized route names
    * (e.g., `/users/:id` instead of `/users/123`, `/users/456`, etc.).
    *
-   * **Disable this option if:**
-   * - You want to minimize client bundle size
-   * - You're experiencing build issues related to route scanning
-   * - You're using custom routing that the scanner can't detect
-   * - You prefer raw URLs in transaction names
-   * - You're only using Pages Router (this feature is only supported in the App Router)
+   * Set to `false` to disable route manifest injection entirely.
    *
-   * @default false
+   * @example
+   * ```js
+   * // Disable route manifest injection
+   * routeManifestInjection: false
+   *
+   * // Exclude specific routes
+   * routeManifestInjection: {
+   *   exclude: [
+   *     '/admin',           // Exact match
+   *     /^\/internal\//,    // Regex: all routes starting with /internal/
+   *     /\/secret-/,        // Regex: any route containing /secret-
+   *   ]
+   * }
+   *
+   * // Exclude using a function
+   * routeManifestInjection: {
+   *   exclude: (route) => route.includes('hidden')
+   * }
+   * ```
    */
-  disableManifestInjection?: boolean;
+  routeManifestInjection?:
+    | false
+    | {
+        /**
+         * Exclude specific routes from the route manifest.
+         *
+         * Use this option to prevent certain routes from being included in the client bundle's
+         * route manifest. This is useful for:
+         * - Hiding confidential or unreleased feature routes
+         * - Excluding internal/admin routes you don't want exposed
+         * - Reducing bundle size by omitting rarely-used routes
+         *
+         * Can be specified as:
+         * - An array of strings (exact match) or RegExp patterns
+         * - A function that receives a route path and returns `true` to exclude it
+         */
+        exclude?: Array<string | RegExp> | ((route: string) => boolean);
+      };
 
   /**
    * Disables automatic injection of Sentry's Webpack configuration.

packages/nextjs/src/config/withSentryConfig/getFinalConfigObjectUtils.ts

@@ -89,13 +89,47 @@ export function maybeCreateRouteManifest(
   incomingUserNextConfigObject: NextConfigObject,
   userSentryOptions: SentryBuildOptions,
 ): RouteManifest | undefined {
+  // Handle deprecated option with warning
   if (userSentryOptions.disableManifestInjection) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      '[@sentry/nextjs] The `disableManifestInjection` option is deprecated. Use `routeManifestInjection: false` instead.',
+    );
+  }
+
+  // Check if manifest injection is disabled (new option takes precedence)
+  if (userSentryOptions.routeManifestInjection === false || userSentryOptions.disableManifestInjection) {
     return undefined;
   }
 
-  return createRouteManifest({
+  const manifest = createRouteManifest({
     basePath: incomingUserNextConfigObject.basePath,
   });
+
+  // Apply route exclusion filter if configured
+  const excludeFilter = userSentryOptions.routeManifestInjection?.exclude;
+  if (!excludeFilter) {
+    return manifest;
+  }
+
+  const shouldExclude = (route: string): boolean => {
+    if (typeof excludeFilter === 'function') {
+      return excludeFilter(route);
+    }
+
+    return excludeFilter.some(pattern => {
+      if (typeof pattern === 'string') {
+        return route === pattern;
+      }
+      return pattern.test(route);
+    });
+  };
+
+  return {
+    staticRoutes: manifest.staticRoutes.filter(r => !shouldExclude(r.path)),
+    dynamicRoutes: manifest.dynamicRoutes.filter(r => !shouldExclude(r.path)),
+    isrRoutes: manifest.isrRoutes.filter(r => !shouldExclude(r)),
+  };
 }
 
 /**

packages/nextjs/test/config/manifest/excludeRoutesFromManifest.test.ts

@@ -0,0 +1,175 @@
+import { describe, expect, it } from 'vitest';
+import type { RouteManifest } from '../../../src/config/manifest/types';
+import type { SentryBuildOptions } from '../../../src/config/types';
+
+type RouteManifestInjectionOptions = Exclude<SentryBuildOptions['routeManifestInjection'], false | undefined>;
+type ExcludeFilter = RouteManifestInjectionOptions['exclude'];
+
+// Inline the filtering logic for unit testing
+// This mirrors what maybeCreateRouteManifest does internally
+function filterManifest(manifest: RouteManifest, excludeFilter: ExcludeFilter): RouteManifest {
+  if (!excludeFilter) {
+    return manifest;
+  }
+
+  const shouldExclude = (route: string): boolean => {
+    if (typeof excludeFilter === 'function') {
+      return excludeFilter(route);
+    }
+
+    return excludeFilter.some((pattern: string | RegExp) => {
+      if (typeof pattern === 'string') {
+        return route === pattern;
+      }
+      return pattern.test(route);
+    });
+  };
+
+  return {
+    staticRoutes: manifest.staticRoutes.filter(r => !shouldExclude(r.path)),
+    dynamicRoutes: manifest.dynamicRoutes.filter(r => !shouldExclude(r.path)),
+    isrRoutes: manifest.isrRoutes.filter(r => !shouldExclude(r)),
+  };
+}
+
+describe('routeManifestInjection.exclude', () => {
+  const mockManifest: RouteManifest = {
+    staticRoutes: [
+      { path: '/' },
+      { path: '/about' },
+      { path: '/admin' },
+      { path: '/admin/dashboard' },
+      { path: '/internal/secret' },
+      { path: '/public/page' },
+    ],
+    dynamicRoutes: [
+      { path: '/users/:id', regex: '^/users/([^/]+)$', paramNames: ['id'] },
+      { path: '/admin/users/:id', regex: '^/admin/users/([^/]+)$', paramNames: ['id'] },
+      { path: '/secret-feature/:id', regex: '^/secret-feature/([^/]+)$', paramNames: ['id'] },
+    ],
+    isrRoutes: ['/blog', '/admin/reports', '/internal/stats'],
+  };
+
+  describe('with no filter', () => {
+    it('should return manifest unchanged', () => {
+      const result = filterManifest(mockManifest, undefined);
+      expect(result).toEqual(mockManifest);
+    });
+  });
+
+  describe('with string patterns', () => {
+    it('should exclude exact string matches', () => {
+      const result = filterManifest(mockManifest, ['/admin']);
+
+      expect(result.staticRoutes.map(r => r.path)).toEqual([
+        '/',
+        '/about',
+        '/admin/dashboard', // Not excluded - not exact match
+        '/internal/secret',
+        '/public/page',
+      ]);
+    });
+
+    it('should exclude multiple exact matches', () => {
+      const result = filterManifest(mockManifest, ['/admin', '/about', '/blog']);
+
+      expect(result.staticRoutes.map(r => r.path)).toEqual([
+        '/',
+        '/admin/dashboard',
+        '/internal/secret',
+        '/public/page',
+      ]);
+      expect(result.isrRoutes).toEqual(['/admin/reports', '/internal/stats']);
+    });
+  });
+
+  describe('with regex patterns', () => {
+    it('should exclude routes matching regex', () => {
+      const result = filterManifest(mockManifest, [/^\/admin/]);
+
+      expect(result.staticRoutes.map(r => r.path)).toEqual(['/', '/about', '/internal/secret', '/public/page']);
+      expect(result.dynamicRoutes.map(r => r.path)).toEqual(['/users/:id', '/secret-feature/:id']);
+      expect(result.isrRoutes).toEqual(['/blog', '/internal/stats']);
+    });
+
+    it('should support multiple regex patterns', () => {
+      const result = filterManifest(mockManifest, [/^\/admin/, /^\/internal/]);
+
+      expect(result.staticRoutes.map(r => r.path)).toEqual(['/', '/about', '/public/page']);
+      expect(result.isrRoutes).toEqual(['/blog']);
+    });
+
+    it('should support partial regex matches', () => {
+      const result = filterManifest(mockManifest, [/secret/]);
+
+      expect(result.staticRoutes.map(r => r.path)).toEqual([
+        '/',
+        '/about',
+        '/admin',
+        '/admin/dashboard',
+        '/public/page',
+      ]);
+      expect(result.dynamicRoutes.map(r => r.path)).toEqual(['/users/:id', '/admin/users/:id']);
+    });
+  });
+
+  describe('with mixed patterns', () => {
+    it('should support both strings and regex', () => {
+      const result = filterManifest(mockManifest, ['/about', /^\/admin/]);
+
+      expect(result.staticRoutes.map(r => r.path)).toEqual(['/', '/internal/secret', '/public/page']);
+    });
+  });
+
+  describe('with function filter', () => {
+    it('should exclude routes where function returns true', () => {
+      const result = filterManifest(mockManifest, (route: string) => route.includes('admin'));
+
+      expect(result.staticRoutes.map(r => r.path)).toEqual(['/', '/about', '/internal/secret', '/public/page']);
+      expect(result.dynamicRoutes.map(r => r.path)).toEqual(['/users/:id', '/secret-feature/:id']);
+      expect(result.isrRoutes).toEqual(['/blog', '/internal/stats']);
+    });
+
+    it('should support complex filter logic', () => {
+      const result = filterManifest(mockManifest, (route: string) => {
+        // Exclude anything with "secret" or "internal" or admin routes
+        return route.includes('secret') || route.includes('internal') || route.startsWith('/admin');
+      });
+
+      expect(result.staticRoutes.map(r => r.path)).toEqual(['/', '/about', '/public/page']);
+      expect(result.dynamicRoutes.map(r => r.path)).toEqual(['/users/:id']);
+      expect(result.isrRoutes).toEqual(['/blog']);
+    });
+  });
+
+  describe('edge cases', () => {
+    it('should handle empty manifest', () => {
+      const emptyManifest: RouteManifest = {
+        staticRoutes: [],
+        dynamicRoutes: [],
+        isrRoutes: [],
+      };
+
+      const result = filterManifest(emptyManifest, [/admin/]);
+      expect(result).toEqual(emptyManifest);
+    });
+
+    it('should handle filter that excludes everything', () => {
+      const result = filterManifest(mockManifest, () => true);
+
+      expect(result.staticRoutes).toEqual([]);
+      expect(result.dynamicRoutes).toEqual([]);
+      expect(result.isrRoutes).toEqual([]);
+    });
+
+    it('should handle filter that excludes nothing', () => {
+      const result = filterManifest(mockManifest, () => false);
+      expect(result).toEqual(mockManifest);
+    });
+
+    it('should handle empty filter array', () => {
+      const result = filterManifest(mockManifest, []);
+      expect(result).toEqual(mockManifest);
+    });
+  });
+});