Capítulo 125 de 456

proxy.js

Core Idea

proxy.js|ts (renomeado de middleware na v16) roda código no servidor antes de a rota ser renderizada, permitindo rewrite, redirect, alteração de headers/cookies ou resposta direta. Fica na raiz do projeto (ou dentro de src), no mesmo nível de app/pages.

Key Concepts

  • proxy function: export default ou nomeado proxy; recebe request (NextRequest) e event (NextFetchEvent).
  • config.matcher: define em quais paths o Proxy roda; sem matcher, roda em toda requisição, inclusive assets estáticos.
  • event.waitUntil(promise): estende o ciclo de vida do Proxy até a promise resolver, útil para logging/analytics em background.
  • NextResponse: API para redirect, rewrite, setar headers/cookies de request e response.
  • Runtime: Proxy usa Node.js runtime por padrão; a config runtime não é suportada em arquivos Proxy (lança erro se setada).
  • skipTrailingSlashRedirect e skipProxyUrlNormalize: flags de next.config.js para casos avançados de migração incremental e controle total da URL.

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: redirect básico restrito por matcher.
export const config = {
  matcher: [
    '/((?!api|_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)',
  ],
}
  • O que demonstra: negative matching para excluir rotas de API e assets estáticos, evitando bloquear CSS/JS/imagens.
npx @next/codemod@canary middleware-to-proxy .
  • O que demonstra: codemod oficial para migrar middleware.ts → proxy.ts.

Reference Tables

Ordem de execução

  1. headers do next.config.js
  2. redirects do next.config.js
  3. Proxy
  4. beforeFiles rewrites do next.config.js
  5. Rotas de filesystem (public/, _next/static/, pages/, app/)
  6. afterFiles rewrites do next.config.js
  7. Dynamic Routes
  8. fallback rewrites do next.config.js

Suporte por plataforma de deploy

DeploymentSuportado
Node.js serverSim
Docker containerSim
Static exportNão
AdaptersDepende da plataforma

Anti-patterns

  • Confiar só no matcher para proteger Server Functions: elas são requisições POST para a rota onde são usadas; um matcher que exclui um path também pula a Server Function ali. Sempre valide autenticação/autorização dentro da própria Server Function.
  • Usar NextResponse.next({ headers: requestHeaders }) para propagar headers upstream: isso expõe o header ao cliente; o correto é NextResponse.next({ request: { headers: requestHeaders } }).
  • Reescrever manualmente via fetch() sem repassar headers RSC: NextResponse.rewrite() já propaga os headers de Flight necessários; fetch manual perde rsc, next-router-state-tree etc a menos que sejam repassados ou skipProxyUrlNormalize seja usado.
  • Assumir que excluir _next/data no matcher bloqueia o Proxy nessa rota: Next.js sempre invoca o Proxy para _next/data, intencionalmente, para não deixar a rota de dados desprotegida enquanto a página está protegida.

Key Takeaways

  1. Proxy substitui Middleware desde a v16; a função e o arquivo mudam de nome, mas a mecânica é a mesma (rode o codemod para migrar).
  2. matcher precisa ser um valor estático (constante) para ser analisado em build-time — variáveis dinâmicas são ignoradas.
  3. Use unstable_doesProxyMatch, isRewrite e getRewrittenUrl (de next/experimental/testing/server) para testar o Proxy sem subir o servidor.
  4. CORS pode ser configurado no Proxy globalmente (preflight + simple requests) ou por Route Handler individual.

Connects To

  • NextRequest / NextResponse: APIs manipuladas dentro de proxy.js.
  • route.js: onde Server Functions e Route Handlers de fato processam a requisição após o Proxy.
  • data-security guide: recomenda validar auth dentro de cada Server Function, não só no Proxy.
AnteriorParallel RoutesPróximopublic