Skip internal routes in middleware

Author: devjiwonchoi

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'
@@ -2580,10 +2581,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

@@ -676,6 +676,7 @@ export const configSchema: zod.ZodType<NextConfig> = z.lazy(() =>
     serverExternalPackages: z.array(z.string()).optional(),
     serverRuntimeConfig: z.record(z.string(), z.any()).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

@@ -1236,6 +1236,12 @@ export interface NextConfig {
 
   skipMiddlewareUrlNormalize?: boolean
 
+  /**
+   * Skip Next.js internals route `/_next` from middleware.
+   * @default true
+   */
+  skipMiddlewareNextInternalRoutes?: boolean
+
   skipTrailingSlashRedirect?: boolean
 
   modularizeImports?: Record<
@@ -1515,6 +1521,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
         }

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

@@ -71,6 +71,7 @@ import type { LoadComponentsReturnType } from './load-components'
 import isError, { getProperError } from '../lib/is-error'
 import { splitCookiesString, toNodeOutgoingHttpHeaders } from './web/utils'
 import { getMiddlewareRouteMatcher } from '../shared/lib/router/utils/middleware-route-matcher'
+import { getDefaultMiddlewareMatcher } from '../shared/lib/router/utils/get-default-middleware-matcher'
 import { loadEnvConfig } from '@next/env'
 import { urlQueryToSearchParams } from '../shared/lib/router/utils/querystring'
 import { removeTrailingSlash } from '../shared/lib/router/utils/remove-trailing-slash'
@@ -1455,13 +1456,13 @@ export default class NextNodeServer extends BaseServer<
       const middlewareModule = await this.loadNodeMiddleware()
 
       if (middlewareModule) {
+        const matchers = middlewareModule.config?.matchers || [
+          getDefaultMiddlewareMatcher(this.nextConfig),
+        ]
         return {
-          match: getMiddlewareRouteMatcher(
-            middlewareModule.config?.matchers || [
-              { regexp: '.*', originalSource: '/:path*' },
-            ]
-          ),
+          match: getMiddlewareRouteMatcher(matchers),
           page: '/',
+          matchers,
         }
       }
 
@@ -1471,6 +1472,7 @@ export default class NextNodeServer extends BaseServer<
     return {
       match: getMiddlewareMatcher(middleware),
       page: '/',
+      matchers: middleware.matchers,
     }
   }
 
@@ -1679,6 +1681,7 @@ export default class NextNodeServer extends BaseServer<
       return { finished: false }
     }
 
+
     await this.ensureMiddleware(params.request.url)
     const middlewareInfo = this.getEdgeFunctionInfo({
       page: middleware.page,

packages/next/src/shared/lib/router/utils/get-default-middleware-matcher.ts

@@ -0,0 +1,35 @@
+import type { NextConfig } from '../../../../types'
+import type { MiddlewareMatcher } from '../../../../build/analysis/get-page-static-info'
+
+export function getDefaultMiddlewareMatcher({
+  skipMiddlewareNextInternalRoutes,
+  basePath,
+}: Pick<
+  NextConfig,
+  'skipMiddlewareNextInternalRoutes' | 'basePath'
+>): MiddlewareMatcher {
+  const skipInternal = skipMiddlewareNextInternalRoutes !== false
+
+  if (skipInternal) {
+    // Allow middleware to run on all routes except Next.js internal routes (/_next/*)
+    // Exception: still match /_next/data/* routes since they're used for client-side navigation
+    // When basePath is configured, the pattern includes the basePath prefix
+    if (basePath) {
+      return {
+        // Escape special characters in basePath
+        regexp: `^${basePath.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?!\\/\\_next\\/(?!data\\/)).*`,
+        originalSource: '/:path*',
+      }
+    }
+
+    return {
+      regexp: '^(?!\\/\\_next\\/(?!data\\/)).*',
+      originalSource: '/:path*',
+    }
+  }
+
+  return {
+    regexp: '.*',
+    originalSource: '/:path*',
+  }
+}