proxy.js (or .ts) sits beside app/ and exports a function named proxy (or a default export) plus an optional config.matcher. For each matching request it gets a NextRequest and can:
NextResponse.redirect()orrewrite()to another URL,NextResponse.next({ request: { headers } })to pass request headers on to the route,- set response headers and cookies,
- return its own
Response.
It runs after next.config headers and redirects and before every rewrite and the filesystem. On Next.js 16.4.5 (next start), a config redirect for /old answered 307 without Proxy running; for a beforeFiles rewrite of /bf to /dash, Proxy saw /bf.
What belongs there: decisions from the request alone. A/B or locale rewrites, redirects that depend on a cookie or header, adding headers, and the optimistic "no session cookie, go to /login" check. Static redirects belong in next.config's redirects. Database calls don't belong in Proxy: it runs on every matched request, including prefetches.
What it can't do: per the docs (not run here), use cache and fetch caching options have no effect there. It also shares no module state with routes: a counter imported by both was incremented in Proxy and read 0 in a route handler.
The rename (16.0). The docs give two reasons: "middleware" was confused with Express middleware, inviting app logic into a feature meant as a last resort, and "proxy" names what it is, a network boundary in front of the app that may be deployed apart from it. 16 also made Proxy Node.js only. A middleware.js still built on 16.4.5, with a deprecation warning, and ran on the Edge runtime. The codemod is npx @next/codemod@canary middleware-to-proxy ..