Middleware Execution | blade47/next.js Wiki | doc0

Public

Middleware Execution | blade47/next.js Wiki | doc0

Condition Type	Source Property Evaluated	Value Extraction & Normalization
`header`	`req.headers[key]`	Key is lowercased; header value retrieved as string
`cookie`	`req.cookies` or `req.headers`	Cookies parsed via `getCookieParser()` if `cookies` property is absent on request
`query`	`query[key]`	Direct lookup against search parameter entries
`host`	`req.headers.host`	Hostname extracted by splitting at port `:` and lowercasing

Design Choice	Benefit	Cost
Sequential array iteration over compiled RegExp matchers	Simple implementation and predictable evaluation order	Linear O(n) performance scaling with the number of configured matchers
Dynamic cookie parser invocation on raw requests	Supports both Web API request objects and Node HTTP `IncomingMessage` instances	Repeated header parsing overhead when multiple cookie conditions are evaluated
Strict `has` and `missing` boolean conjunction (`every` and `!some`)	Expressive declarative conditions for advanced routing logic	Short-circuiting stops parameter collection early if any secondary constraint fails

Response Header / Meta Key	Type / Source	Purpose
`x-nextjs-rewrite`	Response Header	Specifies an internal rewrite target path from middleware execution
`x-nextjs-matched-path`	Response Header	Fallback header used to detect `next.config.js` rewrites when explicit rewrite targets are absent
`x-nextjs-data`	Request Header	Indicates a Next.js data fetch request (`/_next/data/...`) requiring special routing checks
`middlewareInvoke`	Request Meta	Boolean flag indicating whether the active request context originated from middleware processing
`invokePath`	Request Meta	Stores the resolved execution path assigned during `invokeRender()`

Design Choice	Benefit	Cost
Dual raw and decoded pathname matching checks	Gracefully handles percent-encoded paths (e.g., Nginx-decoded proxy requests)	Double evaluation overhead against matcher regexes when raw matching fails
Undefined matcher fallback to `true`	Preserves backwards compatibility for callers without explicit matchers	Implicitly opts all requests into middleware execution if configuration is omitted
Request meta augmentation via `addRequestMeta()`	Decouples internal routing state from core Node HTTP request/response objects	Relies on mutable request object property mutation across pipeline boundaries

Constant / Parameter	Target Value / Type	Purpose / Behavior
`SERVER_DIRECTORY`	`packages/next/src/shared/lib/constants.ts`	Subdirectory name (`server`) appended to `distDir` when loading manifests via `NodeManifestLoader`
`PRERENDER_MANIFEST`	`packages/next/src/server/next-server.ts`	Filename (`prerender-manifest.json`) loaded by `getPrerenderManifest()` for preview and prerender routing data
`NEXT_MINIMAL`	`process.env.NEXT_MINIMAL`	Environment check that throws an invariant error if `runMiddleware()` is invoked in minimal runtime mode
`middlewareInvoke`	Request Meta (`base-server.ts` / `next-server.ts`)	Boolean flag checked by `handleCatchallMiddlewareRequest` to verify if a request originates from middleware processing

Design Choice	Benefit	Cost
Safe `require()` wrapper returning `null` on failure	Prevents server crashes when optional manifest files are missing from the build output	Masks filesystem corruption or missing build artifacts as missing route configurations
Conditional fallback from edge manifest to Node.js middleware	Supports legacy or custom Node-based middleware handlers not recorded in `middleware-manifest.json`	Introduces branching complexity and divergent execution paths between edge and Node runtimes
On-demand revalidation header short-circuiting	Bypasses unnecessary middleware execution for revalidation requests, optimizing build-cache purges	Requires duplicate header parsing logic (`checkIsOnDemandRevalidate`) inside the middleware runner

Middleware Header / Property	Action / Transformation	Target Header / Result Field
`x-middleware-override-headers`	Splits comma-separated keys, deletes request headers not present in the override set, and applies values prefixed with `x-middleware-request-`	`requestHeaders` mutations
`x-middleware-rewrite`	Parses destination URL, normalizes against base URL, and sets internal routing headers	`x-middleware-rewrite`, `x-nextjs-rewrite`, `result.rewrite`
`location`	Validates status against allowed redirect status codes (`301`, `302`, `303`, `307`, `308`), converts URL format, and records redirect status	`location`, `result.redirect`
`x-middleware-refresh`	Sets explicit body sent flag when no rewrite, next, or location header is present	`result.bodySent = true`
`x-middleware-set-cookie`	Appends or sets cookie values specifically onto request headers	`requestHeaders`

Design Choice	Benefit	Cost
Explicit `Response` instance validation	Catches invalid middleware return types early with a descriptive `TypeError` before header parsing runs	Fails the request execution abruptly if middleware developers return plain objects or strings instead of `NextResponse`
Deferred body-close dispatch via `setTimeout` / `CloseController`	Allows asynchronous task registration via `waitUntil` to complete before request storage and stream resources are torn down	Delays resource cleanup until the next event loop turn, complicating deterministic testing of stream lifetimes
Automatic relative URL conversion via `getRelativeURL()`	Normalizes internal redirects and rewrites to relative paths when origins match, avoiding cross-domain routing errors	Requires extra `URL` parsing overhead for every outgoing rewrite or redirect header

Constant / Parameter	Target Value / Type	Purpose / Behavior
`ErrorSource`	`Symbol('SandboxError')`	Identifies errors originating specifically within the sandbox execution environment
`FORBIDDEN_HEADERS`	`['content-length', 'content-encoding', 'transfer-encoding']`	Restricted transport headers stripped from edge function responses before propagation
`NEXT_CLIENT_ASSET_SUFFIX`	String (e.g., `?dpl=<token>`)	Global asset suffix injected into `globalThis` when a client asset token is present
`__incrementalCache`	Cache instance	Shared incremental cache reference attached to the edge runtime global scope

Design Choice	Benefit	Cost
Conditional error tagging via `withTaggedErrors` in development	Maps stack frames to original source locations using `getServerError(error, 'edge-server')` during development	Adds runtime conditional checks and node stack frame module loading overhead in non-production environments
Explicit `FORBIDDEN_HEADERS` stripping post-execution	Prevents edge functions from malforming underlying transport encoding or content length declarations	Requires traversing and deleting specific header keys on every successful response return
Request body stream cloning based on HTTP method	Avoids consumption errors on idempotent GET and HEAD requests while preserving payloads for mutating requests	Requires explicit stream finalization logic in a `finally` block to prevent resource leaks

import { run } from './sandbox'
import type { NodejsRequestData, FetchEventResult } from '../types'
 
async function executeMiddlewareSandbox(
  requestData: NodejsRequestData,
  modulePaths: string[]
): Promise<FetchEventResult> {
  const result = await run({
    name: 'middleware',
    paths: modulePaths,
    request: requestData,
    useCache: true,
    edgeFunctionEntry: {
      assets: [],
      wasm: [],
      env: {},
    },
    distDir: '.next',
    clientAssetToken: 'secure-token-123',
    onError: (err) => console.error('Sandbox error:', err),
    onWarning: (warn) => console.warn('Sandbox warning:', warn),
  })
 
  return result
}

Middleware Endpoint	Method	Purpose
`/__nextjs_original-stack-frames`	POST	Receives serialized stack frames and resolves them to original source positions and code frames
`/__nextjs_source-map`	GET	Looks up compilation artifacts for a specified filename and returns its raw source map JSON payload
`/__nextjs_launch-editor`	GET	Opens source files in the user's configured text editor at a specific line and column coordinate

Design Choice	Benefit	Cost
Short 5ms Watchpack `aggregateTimeout`	Minimizes bootup dead time and speeds up initial reaction to file changes	Increases frequency of aggregation passes during rapid batch file modifications
Multi-compilation stats fallback order (Client → Server → Edge)	Correctly targets the right bundle source map whether an error originates from client components, SSR, or edge runtime	Requires querying multiple webpack compilation graphs sequentially until a matching module ID or source map is found
Eager ignore-list checking via `shouldIgnoreSource`	Keeps error overlays clean by automatically filtering out third-party framework internals and library frames	Adds path-string checking overhead during stack frame transformation