proxy.ts is Next.js’s project-level hook for handling a request before routing finishes: it can redirect or rewrite a request, change headers, or return a response. In Next.js 16, the older Middleware convention was renamed and deprecated in favor of Proxy; the core functionality remains the same. Use it for request-dependent routing decisions, not as your application’s sole authorization or session-management layer.
What is proxy.ts in Next.js?
Proxy runs code before a request is completed. It can inspect a request and decide how Next.js should handle it—for example, by redirecting to another URL, rewriting the destination, changing request or response headers, or returning a response directly. The official Next.js Proxy overview describes request-dependent redirects, experiment rewrites, and header changes as suitable uses.
In Next.js 16, Proxy is the renamed and deprecated-replacement convention for Middleware. The Proxy API reference records the change in v16.0.0; the version 16 upgrade guide explains the runtime change to account for as well.
Where does proxy.ts go?
Put one Proxy file at the project root, or inside src at the same level as app or pages. A project supports only one Proxy file. If your project customizes pageExtensions, use the corresponding naming convention, such as proxy.page.ts. These conventions are documented in the API reference.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchPC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11#1 Best Overall
How do I use proxy.ts?
Export one function, either as a named proxy export or as the default export. The optional config object can define where Proxy runs. This example redirects matching requests to /home:
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*',
}NextResponse can redirect or rewrite, set request or response headers, set cookies, or allow the request to continue. A Proxy function may also return a standard Response. See the API reference for the complete API.
Rank #2
How do matchers control where Proxy runs?
Proxy is invoked for project routes, so use a matcher to scope the paths and conditions where your logic applies. Matcher values must be statically analyzable constants; dynamically computed values are ignored at build time.
- A matcher can be a string, an array of strings, or an object with a
sourceand optional locale,has, ormissingconditions. - Conditions can test request headers, query parameters, or cookies.
- Patterns begin with
/. Named path parameters support*,?, and+modifiers, and regular expressions are also supported.
For example, '/about/:path*' matches /about and paths nested beneath it. Choose the matcher deliberately: excluding a path can also prevent Proxy from running for Server Function calls made on that path. Matcher syntax and execution behavior are described in the API reference.
When should I use Proxy instead of next.config redirects?
Choose based on whether the decision depends on the incoming request or needs logic beyond a static mapping. Next.js processes headers and redirects from next.config.js before Proxy; Proxy then runs before beforeFiles rewrites and filesystem routes.
| Approach | Use it when | Trade-off |
|---|---|---|
redirects in next.config |
A straightforward redirect can be declared statically. | Does not provide Proxy’s request-dependent logic. |
proxy.ts |
The redirect or rewrite depends on request data, or you need logic such as an experiment decision or header change. | Adds a request-time hook; keep its work lightweight rather than using it for slow data fetching. |
Next.js says fetch options such as cache, next.revalidate, and next.tags have no effect in Proxy. For use cases and limitations, see the getting-started guide.
What runtime does Proxy use?
Proxy uses the Node.js runtime by default. You cannot configure a runtime option in the Proxy file, and the Next.js 16 upgrade guide says Edge is not supported for Proxy. When upgrading, check that the project’s deployment and any libraries used by the hook fit the runtime available in the Next.js version you run. The API reference and version 16 guide document these constraints.
Is Proxy enough to authorize a request?
No. Proxy can make an optimistic routing decision, such as redirecting a request that appears unauthenticated, but it is not a full authorization or session-management solution. Enforce access control in the relevant Server Function, route handler, or other application code that performs the protected operation. This matters especially when a matcher skips a path: a Server Function called on that path may not pass through Proxy. The API reference explicitly advises verifying authorization inside each Server Function.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problemsHow do I migrate middleware.ts to proxy.ts?
The rename applies to the Next.js 16 convention. The official migration guidance provides the codemod below as a starting point:
npx @next/codemod@canary middleware-to-proxy .- Rename
middleware.tsormiddleware.jstoproxy.tsorproxy.js. - Rename a named
middlewareexport toproxy. A default export remains an available function-export form. - Rename Middleware-specific configuration flags too; for example,
skipMiddlewareUrlNormalizebecomesskipProxyUrlNormalize. - Review the matcher, runtime assumptions, and authorization checks in application code after the codemod. Confirm that deployment settings and libraries are compatible with Proxy’s Node.js runtime.
If you are not upgrading to Next.js 16, check the documentation for the version your project actually runs before changing conventions; the rename and runtime guidance here are specific to the documented Next.js 16 transition.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
