Redirecting

Core Idea

Next.js oferece cinco formas distintas de redirecionar, cada uma adequada a um momento e contexto diferente (após mutação, navegação client-side, config estático, ou baseado em condição de requisição).

Key Concepts

• redirect(): redireciona em Server Components, Route Handlers e Server Functions; usa 307 (ou 303 em Server Action) por padrão; lança um erro, então deve ficar fora do try em try/catch.
• permanentRedirect(): mesma API que redirect, mas emite 308 (permanente) — usado quando a URL canônica de uma entidade muda.
• useRouter().push(): navegação client-side em event handlers dentro de Client Components; redirect() não pode ser chamado em event handlers.
• redirects em next.config.js: redireciona path de entrada baseado em rotas conhecidas antecipadamente; suporta path/header/cookie/query matching; roda antes do Proxy.
• NextResponse.redirect() no Proxy: redireciona com base em condição avaliada em runtime (ex. autenticação); roda depois de redirects e antes do render.

Code Examples

'use server'
import { redirect } from 'next/navigation'
import { revalidatePath } from 'next/cache'

export async function createPost(id: string) {
  try {
    // Call database
  } catch (error) {
    // Handle errors
  }
  revalidatePath('/posts')
  redirect(`/post/${id}`)
}

• O que demonstra: redirect chamado fora do bloco try, após revalidatePath, em uma Server Action.

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: redirecionamento condicional baseado em autenticação, via Proxy com matcher.

Reference Tables

API	Propósito	Onde	Status Code
redirect	Redirecionar após mutação/evento	Server Components, Server Functions, Route Handlers	307 (ou 303 em Server Action)
permanentRedirect	Redirecionar após mutação/evento (URL canônica)	Server Components, Server Functions, Route Handlers	308
useRouter	Navegação client-side	Event Handlers em Client Components	N/A
redirects em next.config.js	Redirecionar path conhecido antecipadamente	next.config.js	307 ou 308
NextResponse.redirect	Redirecionar baseado em condição	Proxy	Qualquer

Anti-patterns

• Redirects em massa (1000+) via next.config.js: hospedagens como a Vercel limitam a 1.024 redirects; para escala use Proxy com bloom filter + Route Handler para consulta.
• Chamar redirect() dentro do try: como a função lança erro, ficaria capturado pelo catch e nunca redirecionaria.

Key Takeaways

1. Escolha a API pelo contexto de execução: mutação de servidor usa redirect/permanentRedirect, clique do usuário usa useRouter, regra estática usa next.config.js, condição em runtime usa Proxy.
2. Ordem de execução: redirects do config roda antes do Proxy, que roda antes do render.
3. Para redirects em escala (1000+), use bloom filter no Proxy pra evitar carregar um arquivo grande de redirects a cada requisição.

Connects To

• Proxy (proxy.js): mecanismo de execução de código antes do request completar, base do NextResponse.redirect.
• Server Actions: contexto típico de uso do redirect() após mutação.