How to Use Proxy in Next.js 16 (Replacing Middleware) - The Modern Backend-for-Frontend Layer

Using Proxy in Next.js 16: A Modern Middleware Replacement

Next.js 16 introduces a powerful new feature: the proxy.js / proxy.ts convention that replaces the old middleware.js pattern. With Proxy, you can intercept and modify incoming HTTP requests before they reach your routes or APIs. This makes it easy to perform redirects, rewrites, header manipulation, and request forwarding directly within your Next.js app. In modern web architectures (especially e-commerce and microservice setups), Proxy effectively turns your Next.js app into a Backend-for-Frontend (BFF) layer - centralizing API communication, authentication, and routing in one place.

What Is Proxy in Next.js 16 and Why It Matters

The Proxy file (proxy.js/.ts) in Next.js is a special server-side file (located in the project root or under src) that runs before any route handling or page rendering occurs. In fact, Proxy (and Middleware) executes before every incoming request - not just those for pages or APIs - including requests for assets like images, icons, or JavaScript files. Because of this, Next.js provides the matcher configuration, allowing you to specify which routes the Proxy should apply to and avoid intercepting unnecessary requests.

It allows you to inspect the incoming request, then respond, redirect, rewrite, or modify headers based on your application’s needs.

Proxy vs Middleware and Rewrites

• In previous versions, middleware.js (App Router) was used for this pattern; Proxy replaces it.
• While rewrites() in next.config.js can act like a proxy by mapping URL paths to different destinations, the Proxy feature goes further — it gives you direct access to the request object itself, including headers, cookies, and other request data.

When to Use Proxy in Next.js

Proxy works best in scenarios that require lightweight, real-time adjustments to incoming requests — such as performing quick redirects based on request details, dynamically rewriting routes for A/B testing or experimental features, or modifying request and response headers across specific routes or the entire application.

However, it’s not well-suited for tasks involving heavy data fetching or complex session management, as those are better handled by dedicated API routes or backend services.

How Proxy Fits the Backend-for-Frontend (BFF) Pattern

In the BFF (Backend-for-Frontend) pattern, the frontend has a dedicated backend layer that aggregates, transforms, or proxies requests to multiple microservices. Next.js now natively supports this architecture through Route Handlers, Proxy, and Server Actions, allowing your application to efficiently manage communication between frontend and backend layers without leaving the Next.js ecosystem.

How to Set Up Proxy in Next.js 16

Proxy File Convention and Location

• Create a proxy.ts (or proxy.js) file in the project root or inside src/ alongside your top‐level app/ or pages/folder.
• Only one proxy file per project is supported—though you can modularize logic within it by importing helpers.
• Export a function named proxy (or default) that receives a NextRequest and returns a NextResponse.
• Optionally export a config object with a matcher property to specify which routes this proxy applies to.

Example: Simple Redirect Using Proxy

// proxy.ts
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

export function proxy(request: NextRequest) {
  // simple redirect
  return NextResponse.redirect(new URL('/home', request.url));
}

export const config = {
  matcher: '/about/:path*',
}

This intercepts /about/* and sends users to /home.

Example: Rewriting Pathnames with Proxy

// proxy.ts
import { NextResponse } from 'next/server';
 
export function proxy(request: Request) {
  if (request.nextUrl.pathname === '/v1/docs') {
    request.nextUrl.pathname = '/v2/docs'
    return NextResponse.redirect(request.nextUrl);
  }
}

This way /v1/docs in your Next.js app becomes a proxy to your v2 version.

Matcher Configuration Explained

• matcher can be a string, array of strings, or objects with source, has, missing, regexp for fine control.
• You should exclude internal Next.js paths such as /_next/, static assets etc, to avoid intercepting everything accidentally.
• Be aware of runtime: The Proxy is executed by default in the Edge Runtime environment; performance matters.

Using Proxy for Modern E-commerce and BFF Architectures

Authentication and Session Control

Before forwarding to upstream API, you can inspect cookies/headers in Proxy, validate session, add or strip auth headers, or reject unauthorized requests early. This centralises “frontend backend” logic.

For example:

if (!request.cookies.get('sessionToken')) {
  return NextResponse.redirect('/login')
}

Feature Flags and A/B Testing

E-commerce often runs experiments: you might want to route certain requests to a “new checkout backend” or “legacy order API” based on a feature flag. Proxy allows dynamic routing:

if (featureFlag.isEnabled('newCheckout') && pathname.startsWith('/checkout')) {
  return NextResponse.rewrite(new URL('/new-checkout' + rest, request.url))
}

This is exactly where Proxy shines, beyond simple rewrites. The docs mention this scenario.

Micro-Frontend and Multi-Zone Routing

If you break your site into zones (e.g., /shop, /blog, /dashboard) and each is a separate Next.js app or separate backend service, you can use Proxy to route to the correct service based on path or condition. The docs mention this under Multi-Zones: “Proxy can also be used when there is a need for a dynamic decision when routing.”

How Proxy Supports SSG, ISR, and SSR Strategies

In your e-commerce context (as your referenced articles explore SSG/ISR/SSR), Proxy supports architecture by giving you control over how client-requests hit your backend:

• If you statically generate product pages (SSG/ISR) but still need dynamic APIs behind the scenes (inventory, pricing), Proxy sits in front of those APIs.
• If you use SSR for checkout or account pages, you might fetch via your BFF rather than directly from client; Proxy gives you that layer.
• This allows you to decouple the frontend build (Next.js) from the backend services, while still providing unified domain, consistent cookies/sessions, and reduction of client-side complexity.

Summary and Best Practices for Next.js Proxy

The Proxy file convention in Next.js is a modern, flexible tool for intercepting HTTP requests early in your application lifecycle. It’s especially valuable in setups where your frontend is part of a larger ecosystem (microservices, e-commerce, feature-flagged experiments) and you need a lightweight backend-for-frontend layer without building a full custom server.

For e-commerce platforms built with Next.js—where you may have static product pages, dynamic inventory/pricing APIs, customer sessions, checkout flows—the Proxy gives you an elegant place to manage domain-consolidation, routing, auth, A/B experimentation and API facade logic.

However, you should use it wisely: keep logic lean, use it for the right cases (redirects, rewrites, header manipulation, request forwarding) rather than heavy data aggregation. Combined with Next.js’s rendering strategies (SSG, ISR, SSR) and BFF pattern, Proxy becomes an important architectural building block.

FAQ - Common Questions About Next.js Proxy

Q: What’s the difference between Proxy and Middleware in Next.js?

A: In Next.js 16, the proxy.js file replaces middleware.js. While Middleware could modify requests at the edge, Proxy goes further — giving direct access to the NextRequest object and allowing full control over redirects, rewrites, headers, and even request forwarding.

Q: Where should I put the Proxy file in my Next.js app?

A: Place proxy.ts (or proxy.js) in your project root or inside the src/ directory, next to your top-level app/ or pages/ folder. Only one Proxy file is supported per project.

Q: When should I use Next.js Proxy?

A: Use Proxy for lightweight, request-time logic such as redirects, rewrites, A/B routing, authentication checks, or modifying headers. Avoid using it for heavy API calls or data aggregation.

Q: Does Next.js Proxy run at the Edge?

A: Yes, by default Proxy runs in the Edge Runtime for fast global performance. You can still import Node.js APIs if you opt into a Node runtime manually.

Q: Can Proxy replace API routes or Route Handlers?

A: No - Proxy complements them. Use Proxy for pre-processing requests and delegating logic, while Route Handlers or API routes should perform the main data handling or business logic.

Q: How does Proxy help with e-commerce apps?

A: In e-commerce, Proxy acts as a smart gateway - handling authentication, A/B testing, checkout routing, and API consolidation before requests hit your backend. It’s ideal for building scalable Backend-for-Frontend (BFF) architectures in Next.js.

Final Thoughts: Why Proxy Is a Game-Changer for Next.js 16

The introduction of the Proxy layer in Next.js 16 marks a significant evolution in how developers can shape request flow and application architecture. By allowing direct interception and modification of HTTP requests at the edge, Proxy unifies the roles previously divided among middleware, rewrites, and custom servers. This streamlined approach provides both simplicity and flexibility, enabling precise control over routing, authentication, and integration with external APIs. For teams building scalable applications, particularly in e-commerce and microservice environments, Proxy establishes a true Backend-for-Frontend layer within the framework itself. When used judiciously, it enhances performance, security, and maintainability, solidifying Next.js as a modern standard for full-stack web development.