Pular para o conteúdo
Documentação do Next.js PT-BR

Proxy

Proxy

Bom saber: A partir do Next.js 16, o Middleware passou a se chamar Proxy, para refletir melhor seu propósito. A funcionalidade continua a mesma.

O Proxy permite executar código antes de uma requisição ser concluída. Depois, com base na requisição recebida, você pode modificar a resposta: reescrevendo, redirecionando, alterando os headers da requisição ou da resposta, ou respondendo diretamente.

Casos de uso

Alguns cenários comuns em que o Proxy é eficaz:

  • Modificar headers para todas as páginas ou para um subconjunto delas
  • Reescrever para páginas diferentes com base em testes A/B ou experimentos
  • Redirecionamentos programáticos com base em propriedades da requisição recebida

Para redirecionamentos simples, considere primeiro usar a configuração redirects no next.config.ts. Use o Proxy quando precisar acessar os dados da requisição ou quando tiver uma lógica mais complexa.

Limitações

O Proxy não foi feito para buscas de dados lentas. Embora ele possa ajudar em verificações otimistas, como redirecionamentos baseados em permissão, não deve ser usado como solução completa de gerenciamento de sessão ou de autorização.

Diretivas como use cache e use server não têm efeito no Proxy, porque ele não aplica transformações de diretivas.

Opções de fetch como cache, next.revalidate e next.tags também não armazenam respostas em cache. Para reutilizar dados em cache no Proxy, use um cache ou armazenamento de dados externo. Como alternativa, mova o trabalho para um contexto que tenha suporte, como um Server Component ou um Route Handler.

Convenção

Crie um arquivo proxy.ts (ou .js) na raiz do projeto, ou dentro de src, se for o caso, para que ele fique no mesmo nível de pages ou app.

Observação: Como só há suporte para um arquivo proxy.ts por projeto, você ainda pode organizar a lógica do proxy em módulos. Separe as funcionalidades do proxy em arquivos .ts ou .js distintos e importe-os no seu proxy.ts principal. Assim fica mais fácil gerenciar o proxy específico de cada rota, centralizado no proxy.ts. Ao impor um único arquivo de proxy, a configuração fica mais simples, conflitos potenciais são evitados e o desempenho é otimizado, já que não há várias camadas de proxy.

Exemplo

Você pode exportar a função do proxy como exportação padrão ou como exportação nomeada proxy:

proxy.ts
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))
}

// Alternatively, you can use a default export:
// export default function proxy(request: NextRequest) { ... }

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

A configuração matcher permite filtrar o Proxy para rodar apenas em caminhos específicos. Veja a documentação de Matcher para mais detalhes sobre a correspondência de caminhos.

Leia mais sobre como usar o proxy, ou consulte a referência da API de proxy.

Referência da API

Saiba mais sobre o Proxy