whats the difference between proxy.ts and middleware.ts

[foggy bobcat]

whats the difference between proxy.ts and middleware.ts

[cerulean spruce]

Hi @foggy bobcat. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:

---

In Next.js 16, proxy.ts is essentially the renamed and slightly re-scoped version of middleware.ts, but there are some important differences.

1. Naming and exports

• Old convention: middleware.ts with a middleware export.
• New convention: proxy.ts with a proxy export (can be named or default). [Upgrade v16; Proxy API]

Example migration: [Codemod 16.0]

// Before (middleware.ts)
import { NextResponse } from 'next/server'

export function middleware(request: Request) {
  return NextResponse.next()
}

// After (proxy.ts)
import { NextResponse } from 'next/server'

export function proxy(request: Request) {
  return NextResponse.next()
}

Next.js provides a codemod to do this automatically:

npx @next/codemod@latest middleware-to-proxy .

2. Runtime behavior

• middleware.ts (old): ran on the Edge Runtime by default. [Migration to Proxy]
• proxy.ts (new): runs on Node.js only, and Edge runtime is not supported or configurable. [Upgrade v16; Vercel routing middleware]

So if you need Edge runtime behavior, you must keep using middleware.ts for now; proxy.ts is strictly Node.js.

3. Status of each convention

• middleware file convention is deprecated in Next.js 16. [Proxy API; Migration to Proxy]
• proxy is the recommended convention going forward and is what new docs and codemods target. [Proxy getting started]

4. Location and usage

Both follow the same placement rules:

• File at project root or inside src, at the same level as app or pages. [Proxy API; Pages proxy]
• Only one proxy.ts per project is supported; logic can be split into modules and imported. [Proxy getting started]

Functionally (rewrites, redirects, headers, cookies, etc.) they behave the same; the main differences are name, export, and runtime (Edge vs Node).

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: