`proxy.ts` in Next.js 16: What Replaced Middleware and What Changed

proxy.ts is the Next.js 16 name for the file that earlier versions called middleware.ts. It runs on the server before a request reaches a route, and it can redirect, rewrite, adjust headers, or answer the request itself. The interception behavior is unchanged, so the migration is mostly a rename.

One change is not cosmetic. Proxy always runs on the Node.js runtime, and unlike Middleware you cannot switch it to Edge.

The file belongs at the project root, at the same level as the app directory rather than inside it. This is the smallest version of it.

typescript

// proxy.ts
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'
 
export function proxy(request: NextRequest) {
  return NextResponse.redirect(new URL('/home', request.url))
}
 
export const config = {
  matcher: '/about/:path*',
}

A request to /about/team now answers with a 307 redirect to /home before any page renders. The exported config keeps the function off every other path, which matters because a proxy file with no matcher runs on every request in the project.

What changed between middleware and proxy

Four things carry a new name in Next.js 16. Everything else, including the request and response objects, the matcher syntax, and the ability to return a response directly, works the way it did before.

The old file name still runs in Next.js 16, but it is deprecated. Building a project that still uses it prints a warning that names the replacement and the codemod.

text

 ⚠ The "middleware" file convention is deprecated. Please use "proxy" instead.
 
  To migrate automatically, run:
  npx @next/codemod@canary middleware-to-proxy .
 
  Learn more: https://nextjs.org/docs/messages/middleware-to-proxy

Keeping the old file is only worthwhile if you depend on the Edge runtime, which the new convention does not offer. Everything else in the file continues to work unchanged.

Next.js explains the rename as a clarification of purpose. "Middleware" invited comparisons to Express, which encouraged people to treat it as a general application layer, while "proxy" describes a network boundary that sits in front of the app.

Migrating an existing project

Renaming the file and the function by hand is enough for most projects. The official codemod does both in one pass and is worth running first because it also catches a default export whose function still carries the old name.

The codemod renames both the file and the exported function, so a project that only used the standard shape needs no further edits. The Next.js 16 upgrade codemod runs this migration as part of the larger upgrade.

If you split proxy logic across helper modules, only the entry file needs the new name. Next.js still supports exactly one proxy file per project, and imports into it are unaffected.

The Node.js runtime rule

Middleware ran on the Edge runtime by default and gained stable Node.js support in Next.js 15.5. Proxy inverts that: Node.js is the only option, and the route segment runtime option is not available in the file.

Exporting one anyway is never silently ignored. next build fails with the message below, and next dev logs the same text once and then runs the file on Node.js regardless.

text

Route segment config is not allowed in Proxy file at "./proxy.ts". Proxy always runs on Node.js runtime. Learn more: https://nextjs.org/docs/messages/middleware-to-proxy

That removes a class of surprises. Node built-ins, database drivers, and libraries that were awkward or impossible under Edge constraints now work in the same place as the rest of your server code.

Static exports are the other limitation to know. A Node.js server and a Docker container both run Proxy, but a fully static export has no server to run it on, so the file is ignored there.

Where Proxy sits in the request pipeline

Proxy is not the first thing that touches a request. Headers and redirects declared in the Next.js config are applied before it, and filesystem routes are resolved after it. Knowing that order explains most surprising results.

A redirect declared in the config wins over Proxy for the same path, because it is applied first and the request never reaches the function. That is usually the right outcome, and it is why a config redirect is the better tool for a fixed old-to-new path mapping.

Server Functions are worth calling out here. They are not separate routes: a Server Action posts to the route it was used on, so a matcher that excludes that path also skips Proxy for the action.

What Proxy is not for

Proxy runs before every matched request, so slow work there slows down the whole site. Data fetching options such as the fetch cache and revalidation settings have no effect inside it, which is a strong hint about its intended scope.

Authorization is the other misuse. A redirect from Proxy is an optimistic check that improves the experience for a signed-out visitor, but it is not a security boundary, and a refactor that changes the matcher can silently remove it.

The durable rule is that every Server Action and Route Handler authorizes itself. Securing Server Actions covers the checks that belong inside the action rather than in front of it.

When to reach for Proxy

Reach for Proxy when the routing decision depends on the incoming request and cannot be expressed in configuration. Reading a cookie to choose an experiment, branching on a header, or rewriting to a region-specific page all qualify.

Prefer a config redirect or rewrite for static path mappings, and prefer a Server Component or Route Handler when the work involves real data. Those run once per matched route instead of in front of everything.

Three habits keep a proxy file healthy as a project grows. Give it a matcher immediately, so it never runs against static assets and image requests. Keep the function synchronous where you can, since anything awaited there is added to the time before the page starts rendering.

The third habit is verification. A proxy file that silently stops matching looks exactly like a proxy file that was never written, so check a covered path in the browser network panel after any matcher edit and confirm the status code you expect.