[Breaking] Skip Next.js internal routes /_next in middleware (#84239)

### Why?

When the user hasn't set a matcher in the middleware, it always hits the
internal route `/_next/`. This is redundant, though quite common, as it
serves all the static assets. Therefore, skip the internal route by
default when no matcher is set.

---------

Co-authored-by: JJ Kasper <[email protected]>
Co-authored-by: vercel[bot] <35613825+vercel[bot]@users.noreply.github.com>

Author: 3 people

crates/next-api/src/middleware.rs

@@ -42,6 +42,31 @@ use crate::{
     route::{Endpoint, EndpointOutput, EndpointOutputPaths},
 };
 
+/// Rust implementation of the TypeScript getDefaultMiddlewareMatcher function
+/// Generates default middleware matcher patterns that respect skipMiddlewareNextInternalRoutes
+fn get_default_middleware_matcher(
+    skip_middleware_next_internal_routes: Option<bool>,
+) -> MiddlewareMatcher {
+    let skip_internal = skip_middleware_next_internal_routes.unwrap_or(true);
+
+    if skip_internal {
+        // Skip "/_next/" internal routes, except for "/_next/data/" which is needed for
+        // client-side navigation. Do not consider basePath as the user cannot create a
+        // route starts with underscore.
+        MiddlewareMatcher {
+            regexp: Some(rcstr!("^(?!.*\\/\\_next\\/(?!data\\/)).*")),
+            original_source: rcstr!("/((?!_next/(?!data/))[^]*)*"),
+            ..Default::default()
+        }
+    } else {
+        MiddlewareMatcher {
+            regexp: Some(rcstr!("^/.*$")),
+            original_source: rcstr!("/:path*"),
+            ..Default::default()
+        }
+    }
+}
+
 #[turbo_tasks::value]
 pub struct MiddlewareEndpoint {
     project: ResolvedVc<Project>,
@@ -165,6 +190,8 @@ impl MiddlewareEndpoint {
             .map(|i18n| i18n.locales.len() > 1)
             .unwrap_or(false);
         let base_path = next_config.base_path().await?;
+        let skip_middleware_next_internal_routes =
+            next_config.skip_middleware_next_internal_routes().await?;
 
         let matchers = if let Some(matchers) = config.middleware_matcher.as_ref() {
             matchers
@@ -216,11 +243,9 @@ impl MiddlewareEndpoint {
                 })
                 .collect()
         } else {
-            vec![MiddlewareMatcher {
-                regexp: Some(rcstr!("^/.*$")),
-                original_source: rcstr!("/:path*"),
-                ..Default::default()
-            }]
+            vec![get_default_middleware_matcher(
+                *skip_middleware_next_internal_routes,
+            )]
         };
 
         if matches!(runtime, NextRuntime::NodeJs) {

crates/next-core/src/next_config.rs

@@ -103,6 +103,7 @@ pub struct NextConfig {
     asset_prefix: Option<RcStr>,
     base_path: Option<RcStr>,
     skip_middleware_url_normalize: Option<bool>,
+    skip_middleware_next_internal_routes: Option<bool>,
     skip_trailing_slash_redirect: Option<bool>,
     i18n: Option<I18NConfig>,
     cross_origin: Option<CrossOriginConfig>,
@@ -1343,6 +1344,11 @@ impl NextConfig {
         Vc::cell(self.base_path.clone())
     }
 
+    #[turbo_tasks::function]
+    pub fn skip_middleware_next_internal_routes(&self) -> Vc<Option<bool>> {
+        Vc::cell(self.skip_middleware_next_internal_routes)
+    }
+
     #[turbo_tasks::function]
     pub fn cache_handler(&self, project_path: FileSystemPath) -> Result<Vc<OptionFileSystemPath>> {
         if let Some(handler) = &self.cache_handler {

packages/next/src/build/entries.ts

@@ -45,6 +45,7 @@ import {
   isInstrumentationHookFilename,
 } from './utils'
 import { getPageStaticInfo } from './analysis/get-page-static-info'
+import { getDefaultMiddlewareMatcher } from '../shared/lib/router/utils/get-default-middleware-matcher'
 import { normalizePathSep } from '../shared/lib/page-path/normalize-path-sep'
 import { normalizePagePath } from '../shared/lib/page-path/normalize-page-path'
 import type { ServerRuntime } from '../types'
@@ -898,7 +899,7 @@ export async function createEntrypoints(
 
       if (isMiddlewareFile(page)) {
         middlewareMatchers = staticInfo.middleware?.matchers ?? [
-          { regexp: '.*', originalSource: '/:path*' },
+          getDefaultMiddlewareMatcher(params.config),
         ]
       }
 

packages/next/src/build/index.ts

@@ -150,6 +150,7 @@ import { isEdgeRuntime } from '../lib/is-edge-runtime'
 import { recursiveCopy } from '../lib/recursive-copy'
 import { lockfilePatchPromise, teardownTraceSubscriber } from './swc'
 import { getNamedRouteRegex } from '../shared/lib/router/utils/route-regex'
+import { getDefaultMiddlewareMatcher } from '../shared/lib/router/utils/get-default-middleware-matcher'
 import { getFilesInDir } from '../lib/get-files-in-dir'
 import { eventSwcPlugins } from '../telemetry/events/swc-plugins'
 import { normalizeAppPath } from '../shared/lib/router/utils/app-paths'
@@ -2583,10 +2584,7 @@ export default async function build(
           functionsConfigManifest.functions['/_middleware'] = {
             runtime: staticInfo.runtime,
             matchers: staticInfo.middleware?.matchers ?? [
-              {
-                regexp: '^.*$',
-                originalSource: '/:path*',
-              },
+              getDefaultMiddlewareMatcher(config),
             ],
           }
 

packages/next/src/build/webpack-config.ts

@@ -2081,6 +2081,7 @@ export default async function getBaseWebpackConfig(
           dev,
           sriEnabled: !dev && !!config.experimental.sri?.algorithm,
           rewrites,
+          nextConfig: config,
           edgeEnvironments: {
             __NEXT_BUILD_ID: buildId,
             NEXT_SERVER_ACTIONS_ENCRYPTION_KEY: encryptionKey,

packages/next/src/build/webpack/plugins/middleware-plugin.ts

@@ -5,6 +5,7 @@ import type {
 import type { EdgeSSRMeta } from '../loaders/get-module-build-info'
 import type { MiddlewareMatcher } from '../../analysis/get-page-static-info'
 import { getNamedMiddlewareRegex } from '../../../shared/lib/router/utils/route-regex'
+import { getDefaultMiddlewareMatcher } from '../../../shared/lib/router/utils/get-default-middleware-matcher'
 import { getModuleBuildInfo } from '../loaders/get-module-build-info'
 import { getSortedRoutes } from '../../../shared/lib/router/utils'
 import { webpack, sources } from 'next/dist/compiled/webpack/webpack'
@@ -36,6 +37,7 @@ import type { CustomRoutes } from '../../../lib/load-custom-routes'
 import { isInterceptionRouteRewrite } from '../../../lib/generate-interception-routes-rewrites'
 import { getDynamicCodeEvaluationError } from './wellknown-errors-plugin/parse-dynamic-code-evaluation-error'
 import { getModuleReferencesInOrder } from '../utils'
+import type { NextConfigComplete } from '../../../server/config-shared'
 
 const KNOWN_SAFE_DYNAMIC_PACKAGES =
   require('../../../lib/known-edge-safe-packages.json') as string[]
@@ -195,21 +197,29 @@ function getCreateAssets(params: {
         continue
       }
 
-      const matcherSource = metadata.edgeSSR?.isAppDir
-        ? normalizeAppPath(page)
-        : page
-
-      const catchAll = !metadata.edgeSSR && !metadata.edgeApiFunction
-
-      const { namedRegex } = getNamedMiddlewareRegex(matcherSource, {
-        catchAll,
-      })
-      const matchers = metadata?.edgeMiddleware?.matchers ?? [
-        {
-          regexp: namedRegex,
-          originalSource: page === '/' && catchAll ? '/:path*' : matcherSource,
-        },
-      ]
+      let matchers: MiddlewareMatcher[]
+      if (metadata?.edgeMiddleware?.matchers) {
+        matchers = metadata.edgeMiddleware.matchers
+      } else {
+        // For middleware at root with no explicit matchers, use getDefaultMiddlewareMatcher
+        // which respects skipMiddlewareNextInternalRoutes config
+        const catchAll = !metadata.edgeSSR && !metadata.edgeApiFunction
+        if (page === '/' && catchAll) {
+          matchers = [getDefaultMiddlewareMatcher(opts.nextConfig)]
+        } else {
+          const matcherSource = metadata.edgeSSR?.isAppDir
+            ? normalizeAppPath(page)
+            : page
+          matchers = [
+            {
+              regexp: getNamedMiddlewareRegex(matcherSource, {
+                catchAll,
+              }).namedRegex,
+              originalSource: matcherSource,
+            },
+          ]
+        }
+      }
 
       const isEdgeFunction = !!(metadata.edgeApiFunction || metadata.edgeSSR)
       const edgeFunctionDefinition: EdgeFunctionDefinition = {
@@ -818,19 +828,28 @@ interface Options {
   sriEnabled: boolean
   rewrites: CustomRoutes['rewrites']
   edgeEnvironments: EdgeRuntimeEnvironments
+  nextConfig: NextConfigComplete
 }
 
 export default class MiddlewarePlugin {
   private readonly dev: Options['dev']
   private readonly sriEnabled: Options['sriEnabled']
   private readonly rewrites: Options['rewrites']
   private readonly edgeEnvironments: EdgeRuntimeEnvironments
-
-  constructor({ dev, sriEnabled, rewrites, edgeEnvironments }: Options) {
+  private readonly nextConfig: Options['nextConfig']
+
+  constructor({
+    dev,
+    sriEnabled,
+    rewrites,
+    edgeEnvironments,
+    nextConfig,
+  }: Options) {
     this.dev = dev
     this.sriEnabled = sriEnabled
     this.rewrites = rewrites
     this.edgeEnvironments = edgeEnvironments
+    this.nextConfig = nextConfig
   }
 
   public apply(compiler: webpack.Compiler) {
@@ -886,6 +905,7 @@ export default class MiddlewarePlugin {
             rewrites: this.rewrites,
             edgeEnvironments: this.edgeEnvironments,
             dev: this.dev,
+            nextConfig: this.nextConfig,
           },
         })
       )

packages/next/src/server/config-schema.ts

@@ -675,6 +675,7 @@ export const configSchema: zod.ZodType<NextConfig> = z.lazy(() =>
       .optional(),
     serverExternalPackages: z.array(z.string()).optional(),
     skipMiddlewareUrlNormalize: z.boolean().optional(),
+    skipMiddlewareNextInternalRoutes: z.boolean().optional(),
     skipTrailingSlashRedirect: z.boolean().optional(),
     staticPageGenerationTimeout: z.number().optional(),
     expireTime: z.number().optional(),

packages/next/src/server/config-shared.ts

@@ -1235,6 +1235,12 @@ export interface NextConfig {
 
   skipMiddlewareUrlNormalize?: boolean
 
+  /**
+   * Skip Next.js internals route `/_next` from middleware.
+   * @default true
+   */
+  skipMiddlewareNextInternalRoutes?: boolean
+
   skipTrailingSlashRedirect?: boolean
 
   modularizeImports?: Record<
@@ -1511,6 +1517,7 @@ export const defaultConfig = Object.freeze({
   },
   htmlLimitedBots: undefined,
   bundlePagesRouterDependencies: false,
+  skipMiddlewareNextInternalRoutes: true,
 } satisfies NextConfig)
 
 export async function normalizeConfig(phase: string, config: any) {

packages/next/src/server/lib/router-utils/filesystem.ts

@@ -31,6 +31,7 @@ import { pathHasPrefix } from '../../../shared/lib/router/utils/path-has-prefix'
 import { normalizeLocalePath } from '../../../shared/lib/i18n/normalize-locale-path'
 import { removePathPrefix } from '../../../shared/lib/router/utils/remove-path-prefix'
 import { getMiddlewareRouteMatcher } from '../../../shared/lib/router/utils/middleware-route-matcher'
+import { getDefaultMiddlewareMatcher } from '../../../shared/lib/router/utils/get-default-middleware-matcher'
 import {
   APP_PATH_ROUTES_MANIFEST,
   BUILD_ID_FILE,
@@ -314,7 +315,7 @@ export async function setupFsCheck(opts: {
     } else if (functionsConfigManifest?.functions['/_middleware']) {
       middlewareMatcher = getMiddlewareRouteMatcher(
         functionsConfigManifest.functions['/_middleware'].matchers ?? [
-          { regexp: '.*', originalSource: '/:path*' },
+          getDefaultMiddlewareMatcher(opts.config),
         ]
       )
     }

packages/next/src/server/lib/router-utils/setup-dev-bundler.ts

@@ -48,6 +48,7 @@ import {
 } from '../../../shared/lib/constants'
 
 import { getMiddlewareRouteMatcher } from '../../../shared/lib/router/utils/middleware-route-matcher'
+import { getDefaultMiddlewareMatcher } from '../../../shared/lib/router/utils/get-default-middleware-matcher'
 
 import {
   isMiddlewareFile,
@@ -472,7 +473,7 @@ async function startWatcher(
             serverFields.actualMiddlewareFile
           )
           middlewareMatchers = staticInfo.middleware?.matchers || [
-            { regexp: '^/.*$', originalSource: '/:path*' },
+            getDefaultMiddlewareMatcher(opts.nextConfig),
           ]
           continue
         }