{"id":550252,"date":"2026-10-08T07:28:04","date_gmt":"2026-10-08T07:28:04","guid":{"rendered":"https:\/\/webkul.com\/blog\/?p=550252"},"modified":"2026-10-08T07:28:19","modified_gmt":"2026-10-08T07:28:19","slug":"how-proxy-ts-works-in-next-js-16","status":"publish","type":"post","link":"https:\/\/webkul.com\/blog\/how-proxy-ts-works-in-next-js-16\/","title":{"rendered":"How proxy.ts Works in Next.js 16: Complete Guide"},"content":{"rendered":"\n
How proxy.ts Works in Next.js 16 is essential for handling authentication, redirects, request headers, and request interception before a route is processed.<\/p>\n\n\n\n
Whether you need authentication, redirects, header manipulation, or localization, proxy.ts<\/code> allows you to handle these tasks from a single entry point.<\/p>\n\n\n\n
Unlike traditional route handlers, proxy.ts<\/code> executes before route matching, making it ideal for request-level logic that applies across your application.<\/p>\n\n\n\n
In this guide, you’ll learn how proxy.ts<\/code> works in Next.js 16, where it fits into the request lifecycle, and how to use it effectively in production applications.<\/p>\n\n\n\n
What Is proxy.ts?<\/h2>\n\n\n\n
proxy.ts<\/code> is a special file that intercepts every incoming request before Next.js resolves the destination route.<\/p>\n\n\n\n
It enables developers to inspect requests, modify headers, redirect users, rewrite URLs, or block access before rendering a page.<\/p>\n\n\n\n
Since it runs early in the request lifecycle, it is commonly used for authentication, localization, feature flags, and security checks.<\/p>\n\n\n\n
In previous versions, developers used middleware.ts<\/code> for request interception.<\/p>\n\n\n\n
Next.js 16 renamed this file to proxy.ts<\/code> to better reflect its purpose of acting as a request proxy instead of traditional middleware.<\/p>\n\n\n\n
The new name improves clarity while keeping the overall development experience familiar for existing projects.<\/p>\n\n\n\n
When Should You Use proxy.ts?<\/h2>\n\n\n\n
Not every application requires proxy.ts<\/code>, but it becomes valuable when request processing must happen before a route is executed.<\/p>\n\n\n\n
Instead of repeating logic across multiple pages or API routes, you can centralize it in one location.<\/p>\n\n\n\n
\n
Protect authenticated routes.<\/li>\n\n\n\n
Redirect users based on conditions.<\/li>\n\n\n\n
Handle localization and country detection.<\/li>\n\n\n\n
Add or modify request headers.<\/li>\n\n\n\n
Apply maintenance mode.<\/li>\n\n\n\n
Implement feature flags.<\/li>\n<\/ul>\n\n\n\n
How proxy.ts Works<\/h2>\n\n\n\n
Every browser request first passes through proxy.ts<\/code> before Next.js determines which route should handle it.<\/p>\n\n\n\n
The file can inspect the request, perform validation, modify information, or redirect the user before continuing.<\/p>\n\n\n\n
If no changes are required, the request simply continues to the requested page or API route.<\/p>\n\n\n\n
<\/figure>\n\n\n\n
Request Lifecycle in proxy.ts<\/h2>\n\n\n\n
\n
User sends a request.<\/li>\n\n\n\n
Next.js executes proxy.ts<\/code>.<\/li>\n\n\n\n
Request headers and cookies become available.<\/li>\n\n\n\n
Your logic decides whether to continue, rewrite, or redirect.<\/li>\n\n\n\n
Next.js renders the matching route.<\/li>\n<\/ul>\n\n\n\n
This lifecycle allows applications to apply request-level rules before any page or API logic is executed.<\/p>\n\n\n\n
Creating Your First proxy.ts<\/h2>\n\n\n\n
Creating a basic proxy.ts<\/code> file is straightforward.<\/p>\n\n\n\n
The following example allows every request to continue without modification.<\/p>\n\n\n\n
import { NextRequest, NextResponse } from 'next\/server';\n\nexport function proxy(request: NextRequest) {\n return NextResponse.next();\n}<\/pre>\n\n\n\n
This is the simplest implementation of proxy.ts<\/code>. It receives the incoming request and forwards it to the next stage of the routing process.<\/p>\n\n\n\n
From this starting point, you can gradually introduce authentication, redirects, request rewrites, or header modifications without changing your application routes.<\/p>\n\n\n\n
Protecting Routes with proxy.ts<\/h2>\n\n\n\n
One of the most common production use cases for proxy.ts<\/code> is protecting private routes before they reach your application.<\/p>\n\n\n\n
Instead of checking authentication on every page, you can validate the user’s session once inside proxy.ts<\/code> and redirect unauthenticated users immediately.<\/p>\n\n\n\n
This reduces duplicate code and improves security by ensuring protected routes are never rendered for unauthorized users.<\/p>\n\n\n\n
import { NextRequest, NextResponse } from 'next\/server';\n\nexport function proxy(request: NextRequest) {\n const token = request.cookies.get('auth-token');\n\n if (!token && request.nextUrl.pathname.startsWith('\/dashboard')) {\n return NextResponse.redirect(new URL('\/login', request.url));\n }\n\n return NextResponse.next();\n}<\/pre>\n\n\n\n
This example checks for an authentication cookie before allowing access to the dashboard. If no session exists, the user is redirected to the login page.<\/p>\n\n\n\n
<\/figure>\n\n\n\n
Redirecting Users Before Routing<\/h2>\n\n\n\n
Besides authentication, proxy.ts<\/code> is frequently used to redirect users based on application rules.<\/p>\n\n\n\n
Common examples include maintenance mode, language detection, legacy URL migration, or redirecting users to region-specific pages.<\/p>\n\n\n\n
Handling these redirects before route matching improves performance and keeps routing logic centralized.<\/p>\n\n\n\n
import { NextRequest, NextResponse } from 'next\/server';\n\nexport function proxy(request: NextRequest) {\n const { pathname } = request.nextUrl;\n\n if (pathname === '\/old-blog') {\n return NextResponse.redirect(\n new URL('\/blog', request.url)\n );\n }\n\n return NextResponse.next();\n}<\/pre>\n\n\n\n
This example permanently redirects visitors from an old URL to its new destination before the page is rendered.<\/p>\n\n\n\n
Modifying Request Headers<\/h2>\n\n\n\n
Applications sometimes need to add request metadata before passing control to the requested route.<\/p>\n\n\n\n
This is useful for tracking requests, forwarding user information, enabling feature flags, or passing custom headers to downstream services.<\/p>\n\n\n\n
import { NextRequest, NextResponse } from 'next\/server';\n\nexport function proxy(request: NextRequest) {\n const requestHeaders = new Headers(request.headers);\n\n requestHeaders.set('x-app-version', '1.0.0');\n requestHeaders.set('x-request-source', 'proxy');\n\n return NextResponse.next({\n request: {\n headers: requestHeaders,\n },\n });\n}<\/pre>\n\n\n\n
The updated headers become available to the rest of the application without modifying individual pages or API routes.<\/p>\n\n\n\n
Using Config Matchers<\/h2>\n\n\n\n
By default, proxy.ts<\/code> can run for every incoming request. In production, this may introduce unnecessary overhead.<\/p>\n\n\n\n
Using a matcher limits execution to only the routes that actually require request interception.<\/p>\n\n\n\n
Restricting execution to selected routes improves performance because public pages bypass proxy.ts<\/code> entirely.<\/p>\n\n\n\n
Common Production Use Cases<\/h2>\n\n\n\n
Although authentication is the most common implementation, proxy.ts<\/code> supports many production scenarios that benefit from request interception.<\/p>\n\n\n\n
\n
Protect authenticated routes.<\/li>\n\n\n\n
Redirect users during maintenance windows.<\/li>\n\n\n\n
Detect user locale and redirect accordingly.<\/li>\n\n\n\n
Enable feature flags for selected users.<\/li>\n\n\n\n
Add custom security or tracking headers.<\/li>\n\n\n\n
Block suspicious bots or malicious traffic.<\/li>\n\n\n\n
Rewrite legacy URLs without changing application routes.<\/li>\n<\/ul>\n\n\n\n
proxy.ts vs Route Handlers<\/h2>\n\n\n\n
Although both proxy.ts<\/code> and Route Handlers work with incoming requests, they serve different purposes within a Next.js application.<\/p>\n\n\n\n
proxy.ts<\/code> executes before route matching and is designed for request interception, while Route Handlers process requests after a specific route has been matched.<\/p>\n\n\n\n
Use proxy.ts<\/code> for request-level decisions and Route Handlers for implementing business logic, database operations, or API endpoints.<\/p>\n\n\n\n
proxy.ts vs middleware.ts<\/h2>\n\n\n\n<\/figure>\n\n\n\n
If you’ve previously worked with middleware.ts<\/code>, you’ll notice that the overall development experience remains very similar.<\/p>\n\n\n\n
In Next.js 16, the file was renamed to proxy.ts<\/code> to better describe its responsibility of acting as a request proxy before routing.<\/p>\n\n\n\n
Most existing middleware logic can be migrated with minimal code changes, making the transition straightforward for existing applications.<\/p>\n\n\n\n
\/\/ Before (middleware.ts)\n\nimport { NextResponse } from 'next\/server';\n\nexport function middleware(request) {\n return NextResponse.next();\n}\n\n\/\/ After (proxy.ts)\n\nimport { NextResponse } from 'next\/server';\n\nexport function proxy(request) {\n return NextResponse.next();\n}<\/pre>\n\n\n\n
For most projects, migrating simply involves renaming the file and updating the exported function from middleware()<\/code> to proxy()<\/code>.<\/p>\n\n\n\n
Performance Best Practices<\/h2>\n\n\n\n
Because proxy.ts<\/code> executes before every matched request, keeping it lightweight is essential for maintaining fast response times.<\/p>\n\n\n\n
Heavy computations, database queries, and unnecessary external API requests increase request latency for every user.<\/p>\n\n\n\n
Instead, limit proxy.ts<\/code> to lightweight request processing and delegate complex work to Route Handlers or Server Components.<\/p>\n\n\n\n
\n
Use matchers to reduce unnecessary execution.<\/li>\n\n\n\n
Do not call external APIs whenever possible.<\/li>\n\n\n\n
Perform only request-level operations.<\/li>\n\n\n\n
Move business logic to Route Handlers or Server Actions.<\/li>\n<\/ul>\n\n\n\n
Common Mistakes to Avoid<\/h2>\n\n\n\n
Many performance issues arise because developers treat proxy.ts<\/code> as a general-purpose execution layer instead of a lightweight request interceptor.<\/p>\n\n\n\n
Understanding its intended role helps keep applications fast, scalable, and easier to maintain.<\/p>\n\n\n\n
A simple, focused implementation is usually faster, easier to debug, and more reliable than placing excessive logic inside proxy.ts<\/code>.<\/p>\n\n\n\n
Conclusion<\/h2>\n\n\n\n
proxy.ts<\/code> provides a centralized way to intercept and process requests before they reach your application’s routes in Next.js 16.<\/p>\n\n\n\n
By handling authentication, redirects, localization, and request headers in one place, you can reduce duplicated logic while improving maintainability and performance.<\/p>\n\n\n\n
When used correctly, proxy.ts<\/code> becomes an important part of a production-ready Next.js application, helping teams build secure, scalable, and efficient request handling workflows.<\/p>\n","protected":false},"excerpt":{"rendered":"
![\"How](\"https:\/\/cdnblog.webkul.com\/blog\/wp-content\/uploads\/2026\/07\/proxyts-1-1200x800.webp\")
<\/figure>\n\n\n\n![\"Authentication](\"https:\/\/cdnblog.webkul.com\/blog\/wp-content\/uploads\/2026\/08\/proxy-2-1200x800.webp\")
<\/figure>\n\n\n\n![\"proxy.ts](\"https:\/\/cdnblog.webkul.com\/blog\/wp-content\/uploads\/2026\/08\/routevsproxy-1200x800.webp\")
<\/figure>\n\n\n\n