Next.js 16: Migrate middleware.ts to proxy.ts

If you upgrade a project to Next.js 16 and your login redirect quietly stops firing, the cause is almost always the same: your middleware.ts file no longer runs. Next.js 16 renamed the whole convention. I hit this on my own portfolio, and the fix is mechanical — but the reasons behind it are worth understanding before you rename a single file.

This post walks through exactly what changed, the one-line codemod that does the boring part, the trap that leaves protected routes wide open, and the single most important lesson the Next.js team keeps repeating: the request-interception layer was never meant to be your security boundary.

What actually changed in Next.js 16

Next.js 16 shipped on October 21, 2025. Alongside stable Turbopack and Cache Components, it renamed middleware.ts to proxy.ts. The file does the same job — it runs code before a request is completed, so you can rewrite, redirect, or modify headers — but the name now describes what it really is: a proxy that sits at your app's network boundary.

Two things move with the rename. The file becomes proxy.ts, and the exported function becomes proxy. Config flags that carried the old name change too — skipMiddlewareUrlNormalize becomes skipProxyUrlNormalize. One detail matters a lot: proxy runs only on the Node.js runtime. The edge runtime is not supported in proxy, and the runtime cannot be configured. If you genuinely need the edge runtime, you keep the deprecated middleware file for now.

// middleware.ts  (Next.js 15 and earlier)
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'

export function middleware(request: NextRequest) {
  return NextResponse.redirect(new URL('/home', request.url))
}

export const config = {
  matcher: '/about/:path*',
}

// ---------------------------------------------

// proxy.ts  (Next.js 16+) — runs on the Node.js runtime
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'

// same logic; only the file name and function name change
export function proxy(request: NextRequest) {
  return NextResponse.redirect(new URL('/home', request.url))
}

export const config = {
  matcher: '/about/:path*',
}

Why the rename — and the CVE behind it

The rename is partly cosmetic, but it lands against a real security backdrop. CVE-2025-29927, published March 21, 2025 with a CVSS score of 9.1, let an attacker bypass Next.js middleware entirely by sending a spoofed x-middleware-subrequest header. That header exists internally to stop middleware from calling itself in a loop; when it was trusted blindly, any request carrying it skipped middleware execution.

The advisory's wording is blunt: it is possible to bypass authorization checks within a Next.js application if the authorization check occurs in middleware. It was patched in 12.3.5, 13.5.9, 14.2.25, and 15.2.3 — but the deeper lesson outlived the patch. A file that intercepts requests at the edge is the wrong place to be the only thing standing between an attacker and your data.

The mechanical migration

The change itself is trivial. The official version-16 upgrade codemod migrates the middleware convention to proxy for you, along with the renamed config flags. If you prefer to do it by hand, rename the file, rename the function, and update any flags. Here is the whole procedure.

# 1. Automated: the v16 upgrade codemod migrates the convention for you
npx @next/codemod@canary upgrade latest

# 2. Or do it by hand — rename the file
mv middleware.ts proxy.ts
# (then rename the exported function: middleware -> proxy)

# 3. Rename any config flags that carried the old name
#    skipMiddlewareUrlNormalize  ->  skipProxyUrlNormalize

• Run the codemod, or rename middleware.ts to proxy.ts (proxy.js for JavaScript) at the same level as your app or pages directory.
• Rename the exported function from middleware to proxy — do this even if you use a default export, so the intent is clear.
• Rename config flags: skipMiddlewareUrlNormalize becomes skipProxyUrlNormalize. The codemod handles these for you as well.
• Only one proxy file is supported per project, at the root or inside src — split logic into imported modules if it grows, but keep a single entry point.

Proxy is not an authentication boundary

This is the part to internalize. The Next.js docs state plainly that proxy should not be used as a full session management or authorization solution. It is fine for optimistic checks — a fast, best-effort redirect that improves the experience — but it is not a security control. The real authorization check belongs where the data lives.

In practice, that means verifying the session in your Server Components, Route Handlers, and Server Actions — as close to the database as you can get. Do the check right before you read or mutate data, not one hop earlier at the request boundary. If proxy is bypassed, spoofed, or accidentally renamed away, a data-layer check still holds the line. Proxy becomes a UX optimization on top of real enforcement, never the enforcement itself.

Strip the header at the edge

There is still an edge you should harden. For the CVE specifically, the mitigation for anyone who cannot patch immediately is to prevent external requests containing the x-middleware-subrequest header from reaching your Next.js application. You strip or block that header at your load balancer, reverse proxy, or CDN before it ever hits the app.

Managed platforms like Vercel apply this protection automatically, but on a self-hosted deployment it is your responsibility. I run behind a reverse proxy, so I drop the x-middleware-subrequest header there as defense in depth — even on a patched version, no legitimate external client should ever send an internal Next.js header.

middleware.ts versus proxy.ts at a glance

The rename is a small diff, but treat it as a prompt. Move any real authorization out of proxy and into your route and data layer, strip internal headers at your edge, and let proxy do the one thing its new name promises — intercepting requests at the network boundary, nothing more.