Next.js 16 Proxy Convention
Next.js 16 renamed middleware to proxy to better reflect its network boundary purpose.
Key Changes from Middleware
| Old (Next.js 15) | New (Next.js 16+) |
|---|---|
middleware.ts | proxy.ts |
export function middleware() | export function proxy() |
| Same location | Same location |
File Location
Place proxy.ts at the same level as app or pages:
src/
├── proxy.ts ← Correct location
├── app/
│ └── ...NOT inside app/:
src/
├── app/
│ ├── proxy.ts ← Wrong location
│ └── ...Basic Template
import { NextResponse } from "next/server";
import type { NextRequest } from "next/server";
export function proxy(request: NextRequest) {
const { pathname } = request.nextUrl;
// Example: rewrite /uploads/* to /api/uploads/*
if (pathname.startsWith("/uploads/")) {
const newUrl = request.nextUrl.clone();
newUrl.pathname = pathname.replace("/uploads/", "/api/uploads/");
return NextResponse.rewrite(newUrl);
}
return NextResponse.next();
}
export const config = {
matcher: ["/uploads/:path*"],
};Common Issue: Dynamic Routes Catching Paths
When you have a dynamic route like [teamSlug] at the root, it can catch paths before rewrites in next.config.ts are applied.
Problem:
- Request:
/uploads/image.png - Dynamic route
[teamSlug]catches it asteamSlug = "uploads" - Results in 404
Solution: Use proxy.ts instead of next.config.ts rewrites. Proxy runs before routing.
Migration Command
npx @next/codemod@canary middleware-to-proxy .This automatically:
- Renames
middleware.ts→proxy.ts - Updates function name
middleware→proxy