Redirecting

Core Idea

Três formas de lidar com redirecionamento no Next.js (Pages Router), cada uma com seu momento e caso de uso, mais um padrão avançado para gerenciar milhares de redirects sem redeploy.

Key Concepts

• useRouter().push(): redirect client-side dentro de um componente (evento de usuário).
• redirects em next.config.js: redireciona uma rota de entrada para outro destino, com suporte a path matching e wildcard; roda antes do Proxy.
• NextResponse.redirect no Proxy: redirect condicional (ex.: autenticação) baseado na request; roda depois de redirects e antes da renderização.
• Bloom filter: estrutura para checar rapidamente, dentro do Proxy, se um pathname tem redirect sem carregar o arquivo/DB inteiro a cada request.

Code Examples

const nextConfig: NextConfig = {
  async redirects() {
    return [
      { source: '/about', destination: '/', permanent: true },
      { source: '/blog/:slug', destination: '/news/:slug', permanent: true },
    ]
  },
}

• O que demonstra: redirect básico e com wildcard path matching via next.config.js.

export function proxy(request: NextRequest) {
  const isAuthenticated = authenticate(request)
  if (isAuthenticated) return NextResponse.next()
  return NextResponse.redirect(new URL('/login', request.url))
}
export const config = { matcher: '/dashboard/:path*' }

• O que demonstra: redirect condicional por autenticação no Proxy, com matcher limitando o escopo.

Reference Tables

API	Propósito	Onde	Status Code
useRouter	Navegação client-side	Componentes	N/A
redirects em next.config.js	Redirect de path de entrada	next.config.js	307 ou 308
NextResponse.redirect	Redirect condicional	Proxy	Qualquer

Anti-patterns

• Colocar 1000+ redirects direto em next.config.js: plataformas como Vercel limitam a 1.024; usar Proxy + redirect map + bloom filter em vez disso.
• Importar arquivo de redirects grande direto no Proxy: degrada toda request; usar bloom filter + fetch a uma Route/API separada só quando há match.

Key Takeaways

1. Ordem de execução: redirects (next.config.js) roda antes do Proxy.
2. permanent: true gera 308, false gera 307.
3. Para escala (1000+ redirects), a solução recomendada é Proxy + bloom filter + lookup externo (DB/KV), não next.config.js.
4. useRouter é só para navegação programática dentro de componentes, não para regras de redirect declarativas.

Connects To

• Proxy (file convention): onde vive a lógica de NextResponse.redirect.
• rewrites em next.config.js: mecanismo irmão para reescrever URL sem redirecionar visivelmente.