feat(nextjs): Add routeManifestInjection option to exclude routes from client bundle (#18798)

Added a new `routeManifestInjection` configuration option that allows
users to exclude specific routes from the route manifest injected into
the client bundle. This addresses concerns about sensitive or unreleased
route patterns being exposed in the client-side code.

This also deprecated `disableManifestInjection` option since it would be
possible to have conflicting options present which wouldn't be a great
DX.

Users can disable it entirely by passing `false`, otherwise they can use
an object with an `exclude` property. The property can be an array of
string/regex values, or a predicate function.

The value typings prevent disabling the manifest and excluding it at the
same time, also deprecation annotations and build-time warnings should
point users towards the new option.

```ts
// Disable route manifest injection entirely
withSentryConfig(nextConfig, {
  routeManifestInjection: false
})

// Exclude specific routes
withSentryConfig(nextConfig, {
  routeManifestInjection: {
    exclude: [
      '/admin',           // Exact match
      /^\/internal\//,    // Regex: routes starting with /internal/
      /\/secret-/,        // Regex: routes containing /secret-
    ]
  }
})

// Exclude using a function
withSentryConfig(nextConfig, {
  routeManifestInjection: {
    exclude: (route) => route.includes('hidden')
  }
})
```

closes #18713

Author: logaretm

packages/nextjs/src/config/types.ts

@@ -491,7 +491,7 @@ export type SentryBuildOptions = {
      * A list of strings representing the names of components to ignore. The plugin will not apply `data-sentry` annotations on the DOM element for these components.
      */
     ignoredComponents?: string[];
-  };
+  }; // TODO(v11): remove this option
 
   /**
    * Options to be passed directly to the Sentry Webpack Plugin (`@sentry/webpack-plugin`) that ships with the Sentry Next.js SDK.
@@ -500,7 +500,7 @@ export type SentryBuildOptions = {
    * Please note that this option is unstable and may change in a breaking way in any release.
    * @deprecated Use `webpack.unstable_sentryWebpackPluginOptions` instead.
    */
-  unstable_sentryWebpackPluginOptions?: SentryWebpackPluginOptions;
+  unstable_sentryWebpackPluginOptions?: SentryWebpackPluginOptions; // TODO(v11): remove this option
 
   /**
    * Include Next.js-internal code and code from dependencies when uploading source maps.
@@ -522,19 +522,19 @@ export type SentryBuildOptions = {
    * Defaults to `true`.
    * @deprecated Use `webpack.autoInstrumentServerFunctions` instead.
    */
-  autoInstrumentServerFunctions?: boolean;
+  autoInstrumentServerFunctions?: boolean; // TODO(v11): remove this option
 
   /**
    * Automatically instrument Next.js middleware with error and performance monitoring. Defaults to `true`.
    * @deprecated Use `webpack.autoInstrumentMiddleware` instead.
    */
-  autoInstrumentMiddleware?: boolean;
+  autoInstrumentMiddleware?: boolean; // TODO(v11): remove this option
 
   /**
    * Automatically instrument components in the `app` directory with error monitoring. Defaults to `true`.
    * @deprecated Use `webpack.autoInstrumentAppDirectory` instead.
    */
-  autoInstrumentAppDirectory?: boolean;
+  autoInstrumentAppDirectory?: boolean; // TODO(v11): remove this option
 
   /**
    * Exclude certain serverside API routes or pages from being instrumented with Sentry during build-time. This option
@@ -567,7 +567,7 @@ export type SentryBuildOptions = {
    *
    * @deprecated Use `webpack.treeshake.removeDebugLogging` instead.
    */
-  disableLogger?: boolean;
+  disableLogger?: boolean; // TODO(v11): remove this option
 
   /**
    * Automatically create cron monitors in Sentry for your Vercel Cron Jobs if configured via `vercel.json`.
@@ -576,7 +576,7 @@ export type SentryBuildOptions = {
    *
    * @deprecated Use `webpack.automaticVercelMonitors` instead.
    */
-  automaticVercelMonitors?: boolean;
+  automaticVercelMonitors?: boolean; // TODO(v11): remove this option
 
   /**
    * When an error occurs during release creation or sourcemaps upload, the plugin will call this function.
@@ -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; // TODO(v11): remove this option
+
+  /**
+   * 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.
@@ -630,7 +669,7 @@ export type SentryBuildOptions = {
    *
    * @default false
    */
-  disableSentryWebpackConfig?: boolean;
+  disableSentryWebpackConfig?: boolean; // TODO(v11): remove this option
 
   /**
    * When true (and Next.js >= 15), use the runAfterProductionCompile hook to consolidate sourcemap uploads

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

@@ -1,4 +1,4 @@
-import { parseSemver } from '@sentry/core';
+import { isMatchingPattern, parseSemver } from '@sentry/core';
 import { getSentryRelease } from '@sentry/node';
 import { createRouteManifest } from '../manifest/createRouteManifest';
 import type { RouteManifest } from '../manifest/types';
@@ -89,13 +89,59 @@ export function maybeCreateRouteManifest(
   incomingUserNextConfigObject: NextConfigObject,
   userSentryOptions: SentryBuildOptions,
 ): RouteManifest | undefined {
+  // Handle deprecated option with warning
+  // eslint-disable-next-line deprecation/deprecation
   if (userSentryOptions.disableManifestInjection) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      '[@sentry/nextjs] The `disableManifestInjection` option is deprecated. Use `routeManifestInjection: false` instead.',
+    );
+  }
+
+  // If explicitly disabled, skip
+  if (userSentryOptions.routeManifestInjection === false) {
     return undefined;
   }
 
-  return createRouteManifest({
+  // Still check the deprecated option if the new option is not set
+  // eslint-disable-next-line deprecation/deprecation
+  if (userSentryOptions.routeManifestInjection === undefined && userSentryOptions.disableManifestInjection) {
+    return undefined;
+  }
+
+  const manifest = createRouteManifest({
     basePath: incomingUserNextConfigObject.basePath,
   });
+
+  // Apply route exclusion filter if configured
+  const excludeFilter = userSentryOptions.routeManifestInjection?.exclude;
+  return filterRouteManifest(manifest, excludeFilter);
+}
+
+type ExcludeFilter = ((route: string) => boolean) | (string | RegExp)[] | undefined;
+
+/**
+ * Filters routes from the manifest based on the exclude filter.
+ * (Exported only for testing)
+ */
+export function filterRouteManifest(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 => isMatchingPattern(route, pattern));
+  };
+
+  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,164 @@
+import { describe, expect, it } from 'vitest';
+import type { RouteManifest } from '../../../src/config/manifest/types';
+import { filterRouteManifest } from '../../../src/config/withSentryConfig/getFinalConfigObjectUtils';
+
+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 = filterRouteManifest(mockManifest, undefined);
+      expect(result).toEqual(mockManifest);
+    });
+  });
+
+  describe('with string patterns', () => {
+    it('should exclude routes containing the string pattern (substring match)', () => {
+      const result = filterRouteManifest(mockManifest, ['/admin']);
+
+      // All routes containing '/admin' are excluded
+      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 exclude routes matching multiple string patterns', () => {
+      const result = filterRouteManifest(mockManifest, ['/about', '/blog']);
+
+      expect(result.staticRoutes.map(r => r.path)).toEqual([
+        '/',
+        '/admin',
+        '/admin/dashboard',
+        '/internal/secret',
+        '/public/page',
+      ]);
+      expect(result.isrRoutes).toEqual(['/admin/reports', '/internal/stats']);
+    });
+
+    it('should match substrings anywhere in the route', () => {
+      // 'secret' matches '/internal/secret' and '/secret-feature/:id'
+      const result = filterRouteManifest(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 regex patterns', () => {
+    it('should exclude routes matching regex', () => {
+      const result = filterRouteManifest(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 = filterRouteManifest(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 = filterRouteManifest(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']);
+    });
+
+    it('should handle case-insensitive regex', () => {
+      const result = filterRouteManifest(mockManifest, [/ADMIN/i]);
+
+      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']);
+    });
+  });
+
+  describe('with mixed patterns', () => {
+    it('should support both strings and regex', () => {
+      const result = filterRouteManifest(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 = filterRouteManifest(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 = filterRouteManifest(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 = filterRouteManifest(emptyManifest, [/admin/]);
+      expect(result).toEqual(emptyManifest);
+    });
+
+    it('should handle filter that excludes everything', () => {
+      const result = filterRouteManifest(mockManifest, () => true);
+
+      expect(result.staticRoutes).toEqual([]);
+      expect(result.dynamicRoutes).toEqual([]);
+      expect(result.isrRoutes).toEqual([]);
+    });
+
+    it('should handle filter that excludes nothing', () => {
+      const result = filterRouteManifest(mockManifest, () => false);
+      expect(result).toEqual(mockManifest);
+    });
+
+    it('should handle empty filter array', () => {
+      const result = filterRouteManifest(mockManifest, []);
+      expect(result).toEqual(mockManifest);
+    });
+  });
+});