Skip internal routes in middleware

Author: devjiwonchoi

packages/next/src/experimental/testing/server/middleware-testing-utils.ts

@@ -33,7 +33,10 @@ export function unstable_doesMiddlewareMatch({
     return true
   }
   const matchers = getMiddlewareMatchers(config.matcher, nextConfig ?? {})
-  const routeMatchFn = getMiddlewareRouteMatcher(matchers)
+  const routeMatchFn = getMiddlewareRouteMatcher(
+    matchers,
+    nextConfig?.skipMiddlewareNextInternalRoutes !== false
+  )
   const { pathname, searchParams = new URLSearchParams() } = parseUrl(url) || {}
   const request = constructRequest({ url, headers, cookies })
   return routeMatchFn(pathname, request, Object.fromEntries(searchParams))

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

@@ -690,6 +690,7 @@ export const configSchema: zod.ZodType<NextConfig> = z.lazy(() =>
     serverRuntimeConfig: z.record(z.string(), z.any()).optional(),
     skipMiddlewareUrlNormalize: z.boolean().optional(),
     skipTrailingSlashRedirect: z.boolean().optional(),
+    skipMiddlewareNextInternalRoutes: z.boolean().optional(),
     staticPageGenerationTimeout: z.number().optional(),
     expireTime: z.number().optional(),
     target: z.string().optional(),

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

@@ -1241,6 +1241,12 @@ export interface NextConfig {
 
   skipMiddlewareUrlNormalize?: boolean
 
+  /**
+   * Skip Next.js internals route `/_next` from middleware.
+   * @default true
+   */
+  skipMiddlewareNextInternalRoutes?: boolean
+
   skipTrailingSlashRedirect?: boolean
 
   modularizeImports?: Record<

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

@@ -672,7 +672,8 @@ export default class DevServer extends Server {
     // field as it isn't serializable
     if (this.middleware?.match === null) {
       this.middleware.match = getMiddlewareRouteMatcher(
-        this.middleware.matchers || []
+        this.middleware.matchers || [],
+        this.nextConfig.skipMiddlewareNextInternalRoutes !== false
       )
     }
     return this.middleware

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

@@ -309,13 +309,15 @@ export async function setupFsCheck(opts: {
 
     if (middlewareManifest.middleware?.['/']?.matchers) {
       middlewareMatcher = getMiddlewareRouteMatcher(
-        middlewareManifest.middleware?.['/']?.matchers
+        middlewareManifest.middleware?.['/']?.matchers,
+        opts.config.skipMiddlewareNextInternalRoutes !== false
       )
     } else if (functionsConfigManifest?.functions['/_middleware']) {
       middlewareMatcher = getMiddlewareRouteMatcher(
         functionsConfigManifest.functions['/_middleware'].matchers ?? [
           { regexp: '.*', originalSource: '/:path*' },
-        ]
+        ],
+        opts.config.skipMiddlewareNextInternalRoutes !== false
       )
     }
 

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

@@ -908,7 +908,10 @@ async function startWatcher(
       serverFields.hasAppNotFound = hasRootAppNotFound
 
       opts.fsChecker.middlewareMatcher = serverFields.middleware?.matchers
-        ? getMiddlewareRouteMatcher(serverFields.middleware?.matchers)
+        ? getMiddlewareRouteMatcher(
+            serverFields.middleware?.matchers,
+            opts.nextConfig.skipMiddlewareNextInternalRoutes !== false
+          )
         : undefined
 
       const interceptionRoutes = generateInterceptionRoutesRewrites(

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

@@ -145,7 +145,8 @@ const MiddlewareMatcherCache = new WeakMap<
 >()
 
 function getMiddlewareMatcher(
-  info: MiddlewareManifest['middleware'][string]
+  info: MiddlewareManifest['middleware'][string],
+  skipMiddlewareNextInternalRoutes: boolean
 ): MiddlewareRouteMatch {
   const stored = MiddlewareMatcherCache.get(info)
   if (stored) {
@@ -158,7 +159,10 @@ function getMiddlewareMatcher(
     )
   }
 
-  const matcher = getMiddlewareRouteMatcher(info.matchers)
+  const matcher = getMiddlewareRouteMatcher(
+    info.matchers,
+    skipMiddlewareNextInternalRoutes
+  )
   MiddlewareMatcherCache.set(info, matcher)
   return matcher
 }
@@ -1467,7 +1471,8 @@ export default class NextNodeServer extends BaseServer<
           match: getMiddlewareRouteMatcher(
             middlewareModule.config?.matchers || [
               { regexp: '.*', originalSource: '/:path*' },
-            ]
+            ],
+            this.nextConfig.skipMiddlewareNextInternalRoutes !== false
           ),
           page: '/',
         }
@@ -1477,7 +1482,10 @@ export default class NextNodeServer extends BaseServer<
     }
 
     return {
-      match: getMiddlewareMatcher(middleware),
+      match: getMiddlewareMatcher(
+        middleware,
+        this.nextConfig.skipMiddlewareNextInternalRoutes !== false
+      ),
       page: '/',
     }
   }

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

@@ -12,14 +12,20 @@ export interface MiddlewareRouteMatch {
 }
 
 export function getMiddlewareRouteMatcher(
-  matchers: MiddlewareMatcher[]
+  matchers: MiddlewareMatcher[],
+  skipMiddlewareNextInternalRoutes: boolean
 ): MiddlewareRouteMatch {
+  // Apply exclusion logic to matchers if needed
+  const processedMatchers = skipMiddlewareNextInternalRoutes
+    ? excludeNextInternalRoutesFromMatchers(matchers)
+    : matchers
+
   return (
     pathname: string | null | undefined,
     req: BaseNextRequest,
     query: Params
   ) => {
-    for (const matcher of matchers) {
+    for (const matcher of processedMatchers) {
       const routeMatch = new RegExp(matcher.regexp).exec(pathname!)
       if (!routeMatch) {
         continue
@@ -38,3 +44,28 @@ export function getMiddlewareRouteMatcher(
     return false
   }
 }
+
+function excludeNextInternalRoutesFromMatchers(matchers: MiddlewareMatcher[]) {
+  return matchers.map((matcher) => {
+    // If the matcher explicitly targets _next, don't modify it
+    if (matcher.originalSource?.includes('/_next/')) {
+      return matcher
+    }
+
+    // Modify the regex to exclude _next routes
+    let modifiedRegex = matcher.regexp
+
+    // If the regex starts with ^, insert negative lookahead after it
+    if (modifiedRegex.startsWith('^')) {
+      modifiedRegex = `^(?!.*/_next/)${modifiedRegex.slice(1)}`
+    } else {
+      // Otherwise, add negative lookahead at the beginning
+      modifiedRegex = `(?!.*/_next/)${modifiedRegex}`
+    }
+
+    return {
+      ...matcher,
+      regexp: modifiedRegex,
+    }
+  })
+}