Skip to content

Topics

Jump to a topic.

Search questions

Find a question by title, tag, or summary.

What is proxy.ts, what should run there, and why was middleware renamed?

Questions in this chapter (5)
  • Draft
  • medium
  • Askedvery often
  • Verified November 2026

Answer

proxy.js (or .ts) sits beside app/ and exports a function named proxy (or a default export) plus an optional config.matcher. For each matching request it gets a NextRequest and can:

  • NextResponse.redirect() or rewrite() to another URL,
  • NextResponse.next({ request: { headers } }) to pass request headers on to the route,
  • set response headers and cookies,
  • return its own Response.

It runs after next.config headers and redirects and before every rewrite and the filesystem. On Next.js 16.4.5 (next start), a config redirect for /old answered 307 without Proxy running; for a beforeFiles rewrite of /bf to /dash, Proxy saw /bf.

What belongs there: decisions from the request alone. A/B or locale rewrites, redirects that depend on a cookie or header, adding headers, and the optimistic "no session cookie, go to /login" check. Static redirects belong in next.config's redirects. Database calls don't belong in Proxy: it runs on every matched request, including prefetches.

What it can't do: per the docs (not run here), use cache and fetch caching options have no effect there. It also shares no module state with routes: a counter imported by both was incremented in Proxy and read 0 in a route handler.

The rename (16.0). The docs give two reasons: "middleware" was confused with Express middleware, inviting app logic into a feature meant as a last resort, and "proxy" names what it is, a network boundary in front of the app that may be deployed apart from it. 16 also made Proxy Node.js only. A middleware.js still built on 16.4.5, with a deprecation warning, and ran on the Edge runtime. The codemod is npx @next/codemod@canary middleware-to-proxy ..

Example

// proxy.js
import { NextResponse } from 'next/server';

export function proxy(request) {
  const { pathname } = request.nextUrl;

  if (pathname === '/pricing') {
    const bucket = request.cookies.get('ab')?.value ?? (Math.random() < 0.5 ? 'a' : 'b');
    const res = NextResponse.rewrite(new URL(`/pricing/${bucket}`, request.url));
    res.cookies.set('ab', bucket);
    return res;
  }

  const headers = new Headers(request.headers);
  headers.set('x-pathname', pathname);
  return NextResponse.next({ request: { headers } });
}

export const config = {
  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
};

GET /pricing without a cookie rendered app/pricing/a/page.jsx at the URL /pricing and set ab=a; with Cookie: ab=b it rendered variant B. A page calling (await headers()).get('x-pathname') printed /where. Requests for _next/static chunks never reached Proxy; /robots.txt from public/ did.

Pitfalls

  • Shipping without a matcher. Proxy then ran for every JavaScript chunk, public/ file and /_next/image request: one page load logged seven chunk requests.
  • Writing NextResponse.next({ headers }) instead of { request: { headers } }. With a copy of the request headers, the response echoed the client's Cookie and Authorization back to it.
  • Keeping export const runtime = 'edge' after renaming. The build failed: "Route segment config is not allowed in Proxy file at "./proxy.js". Proxy always runs on Node.js runtime."
  • Leaving both files in place. The build failed: "Both middleware file "./middleware.js" and proxy file "./proxy.js" are detected."

Follow-ups

Does Proxy run for prefetches and Server Action calls?
Yes. Chrome 156's <Link> prefetches of /dash and the action POST / both went through it. The rsc and next-router-prefetch headers and the _rsc query were hidden from request, so Proxy can't treat a prefetch differently by mistake; next-action was visible.
Which runtime does it get?
Node.js: process.env.NEXT_RUNTIME was nodejs, process.version v24.19.0, and require and Buffer existed. The same code as middleware.js logged NEXT_RUNTIME=edge.
Why not just use next.config for everything?
Config headers, redirects and rewrites are static rules: a path pattern plus, per the docs (not run here), has/missing conditions on headers, cookies or query. Proxy is code: it can compute a bucket, read a signed cookie or call a fast service.

Comments

Comments are GitHub Discussions: you sign in with GitHub to post or react.