Deprecate middleware and recommend proxy (#84119)

We recommend users avoid relying on Middleware unless no other options
exist. Our goal is to give them APIs with better ergonomics so they can
achieve their goals without Middleware.

The term “middleware” often confuses users with Express.js middleware,
which can encourage misuse. To clarify our direction, we are renaming
the file convention to “proxy.” This highlights that we are moving away
from Middleware, breaking down its overloaded features, and making the
Proxy clear in its purpose.

`proxy.js` should be a drop-in replacement for `middleware.js` for its
features, but ONE thing:

```diff
- export function middleware
+ export function proxy
```

Codemod: #84127

---------

Co-authored-by: Benjamin Woodruff <[email protected]>

Author: devjiwonchoi

crates/next-core/src/middleware.rs

@@ -9,7 +9,7 @@ use crate::util::load_next_js_template;
 #[turbo_tasks::function]
 pub async fn middleware_files(page_extensions: Vc<Vec<RcStr>>) -> Result<Vc<Vec<RcStr>>> {
     let extensions = page_extensions.await?;
-    let files = ["middleware.", "src/middleware."]
+    let files = ["middleware.", "src/middleware.", "proxy.", "src/proxy."]
         .into_iter()
         .flat_map(|f| {
             extensions
@@ -29,14 +29,16 @@ pub async fn get_middleware_module(
 ) -> Result<Vc<Box<dyn Module>>> {
     const INNER: &str = "INNER_MIDDLEWARE_MODULE";
 
+    // Determine if this is a proxy file by checking the module path
+    let userland_path = userland_module.ident().path().await?;
+    let is_proxy = userland_path.file_stem() == Some("proxy");
+    let page_path = if is_proxy { "/proxy" } else { "/middleware" };
+
     // Load the file from the next.js codebase.
     let source = load_next_js_template(
         "middleware.js",
         project_root,
-        &[
-            ("VAR_USERLAND", INNER),
-            ("VAR_DEFINITION_PAGE", "/middleware"),
-        ],
+        &[("VAR_USERLAND", INNER), ("VAR_DEFINITION_PAGE", page_path)],
         &[],
         &[],
     )

packages/next/errors.json

@@ -863,5 +863,7 @@
   "862": "Request body exceeded %s",
   "863": "\\`<Link legacyBehavior>\\` received a direct child that is either a Server Component, or JSX that was loaded with React.lazy(). This is not supported. Either remove legacyBehavior, or make the direct child a Client Component that renders the Link's \\`<a>\\` tag.",
   "864": "Missing value for segment key: \"%s\" with dynamic param type: %s",
-  "865": "`experimental.rdcForNavigations` is enabled, but `experimental.cacheComponents` is not."
+  "865": "`experimental.rdcForNavigations` is enabled, but `experimental.cacheComponents` is not.",
+  "866": "Both \"%s\" and \"%s\" files are detected. Please use \"%s\" instead.",
+  "867": "The %s \"%s\" must export a %s or a \\`default\\` function"
 }

packages/next/src/build/entries.ts

@@ -20,6 +20,8 @@ import {
   APP_DIR_ALIAS,
   WEBPACK_LAYERS,
   INSTRUMENTATION_HOOK_FILENAME,
+  PROXY_FILENAME,
+  MIDDLEWARE_FILENAME,
 } from '../lib/constants'
 import { isAPIRoute } from '../lib/is-api-route'
 import { isEdgeRuntime } from '../lib/is-edge-runtime'
@@ -948,7 +950,13 @@ export async function createEntrypoints(
                 isDev: false,
               })
           } else if (isMiddlewareFile(page)) {
-            server[serverBundlePath.replace('src/', '')] = getEdgeServerEntry({
+            server[
+              serverBundlePath
+                // proxy.js still uses middleware.js for bundle path for now.
+                // TODO: Revisit when we remove middleware.js.
+                .replace(PROXY_FILENAME, MIDDLEWARE_FILENAME)
+                .replace('src/', '')
+            ] = getEdgeServerEntry({
               ...params,
               rootDir,
               absolutePagePath: absolutePagePath,
@@ -1023,7 +1031,12 @@ export async function createEntrypoints(
                   : undefined,
               }).import
             }
-            edgeServer[serverBundlePath] = getEdgeServerEntry({
+            const edgeServerBundlePath = isMiddlewareFile(page)
+              ? serverBundlePath
+                  .replace(PROXY_FILENAME, MIDDLEWARE_FILENAME)
+                  .replace('src/', '')
+              : serverBundlePath
+            edgeServer[edgeServerBundlePath] = getEdgeServerEntry({
               ...params,
               rootDir,
               absolutePagePath: absolutePagePath,

packages/next/src/build/index.ts

@@ -21,6 +21,7 @@ import {
   STATIC_STATUS_PAGE_GET_INITIAL_PROPS_ERROR,
   PUBLIC_DIR_MIDDLEWARE_CONFLICT,
   MIDDLEWARE_FILENAME,
+  PROXY_FILENAME,
   PAGES_DIR_ALIAS,
   INSTRUMENTATION_HOOK_FILENAME,
   RSC_PREFETCH_SUFFIX,
@@ -1163,6 +1164,10 @@ export default async function build(
         `^${MIDDLEWARE_FILENAME}\\.(?:${config.pageExtensions.join('|')})$`
       )
 
+      const proxyDetectionRegExp = new RegExp(
+        `^${PROXY_FILENAME}\\.(?:${config.pageExtensions.join('|')})$`
+      )
+
       const instrumentationHookDetectionRegExp = new RegExp(
         `^${INSTRUMENTATION_HOOK_FILENAME}\\.(?:${config.pageExtensions.join(
           '|'
@@ -1172,6 +1177,7 @@ export default async function build(
       const rootDir = path.join((pagesDir || appDir)!, '..')
       const includes = [
         middlewareDetectionRegExp,
+        proxyDetectionRegExp,
         instrumentationHookDetectionRegExp,
       ]
 
@@ -1186,6 +1192,17 @@ export default async function build(
       const hasMiddlewareFile = rootPaths.some((p) =>
         p.includes(MIDDLEWARE_FILENAME)
       )
+      const hasProxyFile = rootPaths.some((p) => p.includes(PROXY_FILENAME))
+      if (hasMiddlewareFile) {
+        if (hasProxyFile) {
+          throw new Error(
+            `Both "${MIDDLEWARE_FILENAME}" and "${PROXY_FILENAME}" files are detected. Please use "${PROXY_FILENAME}" instead.`
+          )
+        }
+        Log.warn(
+          `The "${MIDDLEWARE_FILENAME}" file convention is deprecated. Please use "${PROXY_FILENAME}" instead.`
+        )
+      }
 
       NextBuildContext.hasInstrumentationHook = hasInstrumentationHook
 
@@ -2543,8 +2560,8 @@ export default async function build(
           return serverFilesManifest
         })
 
-      const middlewareFile = rootPaths.find((p) =>
-        p.includes(MIDDLEWARE_FILENAME)
+      const middlewareFile = rootPaths.find(
+        (p) => p.includes(MIDDLEWARE_FILENAME) || p.includes(PROXY_FILENAME)
       )
       let hasNodeMiddleware = false
 
@@ -3918,7 +3935,7 @@ export default async function build(
           rewritesWithHasCount: combinedRewrites.filter((r: any) => !!r.has)
             .length,
           redirectsWithHasCount: redirects.filter((r: any) => !!r.has).length,
-          middlewareCount: hasMiddlewareFile ? 1 : 0,
+          middlewareCount: hasMiddlewareFile || hasProxyFile ? 1 : 0,
           totalAppPagesCount,
           staticAppPagesCount,
           serverAppPagesCount,

packages/next/src/build/templates/middleware.ts

@@ -10,13 +10,15 @@ import { edgeInstrumentationOnRequestError } from '../../server/web/globals'
 import { isNextRouterError } from '../../client/components/is-next-router-error'
 
 const mod = { ..._mod }
-const handler = mod.middleware || mod.default
 
 const page = 'VAR_DEFINITION_PAGE'
+// @ts-expect-error `page` will be replaced during build
+const isProxy = page === '/proxy' || page === '/src/proxy'
+const handler = (isProxy ? mod.proxy : mod.middleware) || mod.default
 
 if (typeof handler !== 'function') {
   throw new Error(
-    `The Middleware "${page}" must export a \`middleware\` or a \`default\` function`
+    `The ${isProxy ? 'Proxy' : 'Middleware'} "${page}" must export a ${isProxy ? '`proxy`' : '`middleware`'} or a \`default\` function`
   )
 }
 

packages/next/src/build/utils.ts

@@ -22,6 +22,7 @@ import {
   SERVER_PROPS_SSG_CONFLICT,
   SSG_GET_INITIAL_PROPS_CONFLICT,
   WEBPACK_LAYERS,
+  PROXY_FILENAME,
 } from '../lib/constants'
 import type {
   AppPageModule,
@@ -96,7 +97,12 @@ export function difference<T>(
 }
 
 export function isMiddlewareFilename(file?: string | null) {
-  return file === MIDDLEWARE_FILENAME || file === `src/${MIDDLEWARE_FILENAME}`
+  return (
+    file === MIDDLEWARE_FILENAME ||
+    file === `src/${MIDDLEWARE_FILENAME}` ||
+    file === PROXY_FILENAME ||
+    file === `src/${PROXY_FILENAME}`
+  )
 }
 
 export function isInstrumentationHookFilename(file?: string | null) {
@@ -489,7 +495,7 @@ export async function printTreeView(
   const middlewareInfo = middlewareManifest.middleware?.['/']
   if (middlewareInfo?.files.length > 0) {
     messages.push([])
-    messages.push(['ƒ Middleware'])
+    messages.push(['ƒ Proxy (Middleware)'])
   }
 
   print(
@@ -1375,7 +1381,10 @@ export function isCustomErrorPage(page: string) {
 
 export function isMiddlewareFile(file: string) {
   return (
-    file === `/${MIDDLEWARE_FILENAME}` || file === `/src/${MIDDLEWARE_FILENAME}`
+    file === `/${MIDDLEWARE_FILENAME}` ||
+    file === `/src/${MIDDLEWARE_FILENAME}` ||
+    file === `/${PROXY_FILENAME}` ||
+    file === `/src/${PROXY_FILENAME}`
   )
 }
 
@@ -1405,9 +1414,10 @@ export function getPossibleMiddlewareFilenames(
   folder: string,
   extensions: string[]
 ) {
-  return extensions.map((extension) =>
-    path.join(folder, `${MIDDLEWARE_FILENAME}.${extension}`)
-  )
+  return extensions.flatMap((extension) => [
+    path.join(folder, `${MIDDLEWARE_FILENAME}.${extension}`),
+    path.join(folder, `${PROXY_FILENAME}.${extension}`),
+  ])
 }
 
 export class NestedMiddlewareError extends Error {

packages/next/src/build/webpack/loaders/next-middleware-loader.ts

@@ -3,7 +3,10 @@ import type {
   MiddlewareMatcher,
 } from '../../analysis/get-page-static-info'
 import { getModuleBuildInfo } from './get-module-build-info'
-import { MIDDLEWARE_LOCATION_REGEXP } from '../../../lib/constants'
+import {
+  MIDDLEWARE_LOCATION_REGEXP,
+  PROXY_LOCATION_REGEXP,
+} from '../../../lib/constants'
 import { loadEntrypoint } from '../../load-entrypoint'
 
 export type MiddlewareLoaderOptions = {
@@ -49,7 +52,12 @@ export default async function middlewareLoader(this: any) {
   buildInfo.nextEdgeMiddleware = {
     matchers,
     page:
-      page.replace(new RegExp(`/${MIDDLEWARE_LOCATION_REGEXP}$`), '') || '/',
+      page.replace(
+        new RegExp(
+          `/(${MIDDLEWARE_LOCATION_REGEXP}|${PROXY_LOCATION_REGEXP})$`
+        ),
+        ''
+      ) || '/',
   }
   buildInfo.rootDir = rootDir
   buildInfo.route = {

packages/next/src/lib/constants.ts

@@ -46,6 +46,10 @@ export const INFINITE_CACHE = 0xfffffffe
 export const MIDDLEWARE_FILENAME = 'middleware'
 export const MIDDLEWARE_LOCATION_REGEXP = `(?:src/)?${MIDDLEWARE_FILENAME}`
 
+// Patterns to detect proxy files (replacement for middleware)
+export const PROXY_FILENAME = 'proxy'
+export const PROXY_LOCATION_REGEXP = `(?:src/)?${PROXY_FILENAME}`
+
 // Pattern to detect instrumentation hooks file
 export const INSTRUMENTATION_HOOK_FILENAME = 'instrumentation'
 

packages/next/src/server/dev/hot-reloader-turbopack.ts

@@ -1311,6 +1311,8 @@ export async function createHotReloaderTurbopack(
             // TODO: why is this entry missing in turbopack?
             if (page === '/middleware') return
             if (page === '/src/middleware') return
+            if (page === '/proxy') return
+            if (page === '/src/proxy') return
             if (page === '/instrumentation') return
             if (page === '/src/instrumentation') return
 

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

@@ -76,7 +76,11 @@ import {
 import { getDefineEnv } from '../../../build/define-env'
 import { TurbopackInternalError } from '../../../shared/lib/turbopack/internal-error'
 import { normalizePath } from '../../../lib/normalize-path'
-import { JSON_CONTENT_TYPE_HEADER } from '../../../lib/constants'
+import {
+  JSON_CONTENT_TYPE_HEADER,
+  MIDDLEWARE_FILENAME,
+  PROXY_FILENAME,
+} from '../../../lib/constants'
 import {
   createRouteTypesManifest,
   writeRouteTypesManifest,
@@ -387,6 +391,29 @@ async function startWatcher(
         sortByPageExts(nextConfig.pageExtensions)
       )
 
+      let hasMiddlewareFile = false
+      let hasProxyFile = false
+      for (const fileName of sortedKnownFiles) {
+        const { name } = path.parse(fileName)
+        if (name === MIDDLEWARE_FILENAME) {
+          hasMiddlewareFile = true
+        }
+        if (name === PROXY_FILENAME) {
+          hasProxyFile = true
+        }
+      }
+
+      if (hasMiddlewareFile) {
+        if (hasProxyFile) {
+          throw new Error(
+            `Both "${MIDDLEWARE_FILENAME}" and "${PROXY_FILENAME}" files are detected. Please use "${PROXY_FILENAME}" instead.`
+          )
+        }
+        Log.warn(
+          `The "${MIDDLEWARE_FILENAME}" file convention is deprecated. Please use "${PROXY_FILENAME}" instead.`
+        )
+      }
+
       for (const fileName of sortedKnownFiles) {
         if (
           !files.includes(fileName) &&
@@ -467,6 +494,7 @@ async function startWatcher(
             continue
           }
           serverFields.actualMiddlewareFile = rootFile
+
           await propagateServerField(
             opts,
             'actualMiddlewareFile',