Capítulo 174 de 456

redirect

Core Idea

Redireciona o usuário para outra URL, usável em Server/Client Components, Route Handlers e Server Functions, com semântica temporária (307) por padrão.

Key Concepts

  • redirect(path, type): type é 'replace' (default) ou 'push' (default em Server Actions); sem efeito em Server Components.
  • Status HTTP: 307 por padrão (preserva método POST); Server Action form submission usa 303 (força GET no follow); com JS disponível, Server Actions fazem navegação client-side em vez de redirect HTTP.
  • never return type: não precisa return redirect().
  • Em Client Component: pode ser chamado durante render, mas não em event handlers — use useRouter para isso. No load inicial via SSR, faz redirect server-side.

Code Examples

// app/team/[id]/page.tsx
import { redirect } from 'next/navigation'

export default async function Profile({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params
  const team = await fetchTeam(id)
  if (!team) {
    redirect('/login')
  }
}
  • O que demonstra: redirect condicional em Server Component quando recurso não é encontrado.
// Client Component chamando redirect durante render
'use client'
import { redirect, usePathname } from 'next/navigation'

export function ClientRedirect() {
  const pathname = usePathname()
  if (pathname.startsWith('/admin') && !pathname.includes('/login')) {
    redirect('/admin/login')
  }
  return <div>Login Page</div>
}
  • O que demonstra: uso válido de redirect em Client Component (durante render, não em handler de evento).
// app/actions.ts
'use server'
import { redirect } from 'next/navigation'

export async function navigate(data: FormData) {
  redirect(`/posts/${data.get('id')}`)
}
  • O que demonstra: redirect a partir de um Server Action disparado por form.

Reference Tables

ParameterTypeDescription
pathstringURL relativa ou absoluta de destino
type'replace' | 'push'tipo de navegação no histórico
StatusComportamento
302 (não usado por padrão)mudaria método POST → GET
307padrão de redirect, preserva método
308usado por permanentRedirect
303usado em Server Action form submission
VersionChanges
v13.0.0redirect introduzido

Anti-patterns

  • Chamar dentro do bloco try: redirect lança erro, deve ficar fora do try/catch.
  • Chamar em event handler de Client Component: não funciona; use useRouter().push().
  • Redirect antes do render, via next.config.js ou Proxy: se o redirect não depende de lógica de render, prefira redirects() no config ou NextResponse.redirect no Proxy, mais eficiente.

Key Takeaways

  1. redirect usa 307/308 em vez de 301/302 porque preserva o método HTTP original (importante para POST).
  2. Server Action form submissions usam 303 para garantir GET no destino; com JS habilitado, a navegação é client-side.
  3. Para redirects estáticos conhecidos de antemão, prefira config ou Proxy em vez de redirect() no render.

Connects To

  • permanentRedirect: variante 308 para mudanças definitivas de URL.
  • useRouter: alternativa para redirect disparado por evento em Client Component.
  • Server Actions: contexto onde redirect tem comportamento de navegação client-side quando JS está disponível.
AnteriorpermanentRedirectPróximorefresh