Proxy

Proxy

Proxy allows you to run code before a request is completed. Then, based on the incoming request, you can modify the response by rewriting, redirecting, modifying the request or response headers, or responding directly.

Use cases

Some common scenarios where Proxy is effective include:

• Quick redirects after reading parts of the incoming request
• Rewriting to different pages based on A/B tests or experiments
• Modifying headers for all pages or a subset of pages

Proxy is not a good fit for:

• Slow data fetching
• Session management

Using fetch with options.cache, options.next.revalidate, or options.next.tags, has no effect in Proxy.

Convention

Create a proxy.ts (or .js) file in the project root, or inside src if applicable, so that it is located at the same level as pages or app.

Note: While only one proxy.ts file is supported per project, you can still organize your proxy logic into modules. Break out proxy functionalities into separate .ts or .js files and import them into your main proxy.ts file. This allows for cleaner management of route-specific proxy, aggregated in the proxy.ts for centralized control. By enforcing a single proxy file, it simplifies configuration, prevents potential conflicts, and optimizes performance by avoiding multiple proxy layers.

Example

import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'
 
// This function can be marked `async` if using `await` inside
export function proxy(request: NextRequest) {
  return NextResponse.redirect(new URL('/home', request.url))
}
 
// See "Matching Paths" below to learn more
export const config = {
  matcher: '/about/:path*',
}

Read more about using proxy, or refer to the proxy API reference.