NEXT.JS PROXYFormerly middlewareA Next.js middleware file tends to grow: a sign-in redirect, then a database lookup, a role check and some logging, until every request waits on it. Next.js 16 renamed it proxy.ts, and the name fits the job: a thin layer in front of your routes. Here is what goes there, what stays out, and where the real access check lives.
What is the proxy file?
It is one file, proxy.ts or proxy.js, whose function runs on the server before a request completes. It can redirect, rewrite, change request or response headers, or answer the request itself. It sits in the project root (or src) next to app, and exports one function, named proxy or as the default export. A project has one proxy file, which can import other modules.
Next.js 16 renamed the middleware convention to proxy, and the docs say the functionality is unchanged. "Middleware" was easily confused with Express middleware, and the Next.js team recommends the feature only as a last resort. The proxy runs on the Node.js runtime; setting the runtime option in the file throws an error. Codemods handle the rename, including config flags such as skipMiddlewareUrlNormalize.
Using the Edge runtime? The proxy does not support it, so the upgrade guide says to keep middleware.ts in that case for now.
What jobs suit the proxy?
Decisions that need only the request: its URL, headers and cookies. It runs after the headers and redirects in next.config and before any route renders. Typical jobs:
- Conditional redirects, such as sending a signed-out visitor from
/dashboardto/login. - Rewrites that serve a different page at the same URL, for an A/B test or experiment.
- Locale detection: read
Accept-Languageand redirect/productsto/en-US/products, as the Next.js internationalisation guide shows. - Headers that depend on the request, such as CORS headers on
/apiroutes. - Guarding static pages that share content between users, such as paid articles. They are built ahead of time, so the docs point to the proxy for these.
What should stay out of it?
Anything slow, and anything that must be the final word on access. The docs say the proxy is not for slow data fetching, nor a full session management or authorisation solution. It runs on every matched route, including prefetches, so the authentication guide says to read the session from the cookie only and avoid database checks. We keep out:
- Database or API calls on every request, such as loading the user or their permissions.
- Work that relies on caching:
use cacheanduse serverhave no effect here, andfetchcache options do not cache. Move it to a Server Component or route handler. - Large imports, such as a full redirect map. For very large lists, the docs' example checks a small Bloom filter in the proxy and lets a route handler read the full map.
- Logging that delays the response.
event.waitUntil()lets it finish after the response is sent.
How do you limit where it runs?
Export a config object with a matcher. Without one, the proxy runs on every request, including _next/static, _next/image and files in public, so an auth redirect can block CSS, scripts and images. A matcher can be a path, a list, a pattern with a negative lookahead, or objects with has and missing conditions. Values must be constants, because Next.js reads them at build time.
For sign-in redirects, the authentication guide recommends running the proxy on all routes; its example skips static files and decides inside the function which paths need a session. A minimal version:
// proxy.ts
import { NextResponse, type NextRequest } from 'next/server'
const protectedPaths = ['/dashboard', '/settings']
export function proxy(request: NextRequest) {
const { pathname } = request.nextUrl
const isProtected = protectedPaths.some(
(p) => pathname === p || pathname.startsWith(`${p}/`)
)
// Optimistic check: the cookie only, no database call
if (isProtected && !request.cookies.has('session')) {
return NextResponse.redirect(new URL('/login', request.url))
}
return NextResponse.next()
}
export const config = {
// Skip API routes, build files, images and metadata files
matcher: [
'/((?!api|_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)',
],
}Checking that the cookie exists is the lightest option; the guide's own example decrypts the session cookie, still without a database call. Skipping /api is fine here, because each route handler should check the session itself.
Why check auth again next to the data?
Because the proxy only sees a cookie, and a request can reach your data without passing through it. The docs say the proxy should not be your only line of defence, and that most security checks belong as close as possible to the data source.
Server Actions are POST requests to the route that uses them, so a matcher that skips a path skips those calls too, and moving an action can silently remove coverage. Layouts do not re-render on navigation, so a layout check does not run on every route change. And in March 2025, the official advisory for CVE-2025-29927 said access checks placed in middleware could be bypassed. Our pattern has three layers:
- The proxy sends signed-out visitors to sign-in, from the cookie alone.
- A server-only data access layer checks the session in every Server Component that loads private data, Server Action and route handler; see Server Actions or route handlers.
- Each query confirms this user may see or change this record, and returns only the fields the screen needs.
Where to start
Open proxy.ts, or middleware.ts if you have not upgraded, and list every job it does. Anything that needs data, or is the only guard on that data, moves down to the data layer. Then check that the matcher skips static files. Our web app development service builds and reviews Next.js apps this way, and you can ask us to look at yours.
FAQ
Frequently asked questions
Can we keep middleware.ts on Next.js 16?
Only as a stopgap. The Next.js 16 release post says middleware.ts is still available for Edge runtime use cases, but it is deprecated and will be removed in a future version. Unless you need Edge, rename it now: the version 16 codemods update the file, the function and related config flags. Then test your redirects and matcher before release.
Can the proxy check user roles?
Only from what is already in the session cookie. If the session cookie includes a role, the proxy can send a non-admin away from /admin without a database call, which the docs class as an optimistic check. The secure check, reading the current role from your database, belongs in the data access layer that loads the admin data.
Should old URL redirects go in the proxy?
Usually not. A known list of old and new URLs belongs in redirects in next.config, which runs before the proxy and returns a 307 or 308 depending on the permanent option. Use the proxy when a redirect depends on the request, such as a cookie or header, or when the list runs into the thousands.
Does the proxy work with a static export?
No. The Next.js docs list static export as not supported for the proxy. It is supported on a Node.js server and in a Docker container, and on other platforms it depends on their adapter. On a statically exported site, set up redirects and headers at your host or CDN instead.
Was the 2025 middleware vulnerability fixed?
Yes. CVE-2025-29927 was fixed in Next.js 15.2.3, 14.2.25, 13.5.9 and 12.3.5, and the advisory noted that deployments hosted on Vercel were automatically protected. If you self-host an older version, upgrade. The lesson holds on every version: the Next.js team does not recommend middleware as the only way to protect routes.
Can we test which paths the proxy runs on?
Yes, with experimental helpers. Since Next.js 15.1, an experimental testing package ships with Next.js and includes unstable_doesMiddlewareMatch, which reports whether the proxy would run for a given URL, headers and cookies. Other helpers in it check whether a response is a rewrite and return the rewrite or redirect URL, so routing logic is tested before it reaches production.

