Proxy

Core Idea

Proxy (renamed from Middleware in Next.js 16, same functionality) runs code before a request completes, letting you rewrite, redirect, modify headers, or respond directly based on the incoming request.

Key Concepts

• proxy.ts: Convention file at project root (or inside src/), same level as pages or app; only one is supported per project, but it can import from other modules.
• proxy export: Export as default or named proxy function; can be marked async.
• config.matcher: Filters which paths Proxy runs on, using path-matching patterns.
• No slow data fetching: Proxy is not meant for full session management/authorization or slow fetches; fetch options cache, next.revalidate, next.tags have no effect inside Proxy.

Code Examples

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*',
}

• O que demonstra: Redirecionamento simples via Proxy com matcher restringindo o path de execução.

Anti-patterns

• Usar Proxy para fetch lento ou autenticação completa: cache options não funcionam dentro de Proxy, e ele não substitui autorização/sessão real; use apenas para checagens otimistas.
• Redirects simples via Proxy: prefira a config redirects em next.config.ts quando não precisar de dados da request.

Key Takeaways

1. Proxy substitui o antigo Middleware (Next.js 16), mesma API e comportamento.
2. Use para reescrever, redirecionar ou modificar headers com base na request, nunca para lógica pesada/lenta.
3. matcher limita onde o Proxy roda; sem ele, roda em todas as rotas.
4. Apenas um proxy.ts por projeto; organize lógica em módulos importados.

Connects To

• authentication (ch024): Proxy é usado para checagens otimistas de sessão (optimistic checks), nunca para autorização segura completa.
• backend-for-frontend: padrão de uso do Proxy como camada de backend for frontend.