Melhores Práticas de Roteamento do Next.js

Um resumo condensado das 25 melhores práticas mais importantes, extraídas de todas as páginas desta seção.

Aguarde params e searchParams: No Next.js 15+, ambas as props são Promises em Server Components - const { id } = await params - desestruturar sem await retorna o objeto Promise e suas buscas retornarão silenciosamente undefined.
Não Colida page.tsx com route.tsx: Uma pasta não pode conter page.tsx e route.tsx - o Route Handler sombreará a página, então mantenha as rotas de API em app/api/ para evitar conflitos silenciosos.
Use template.tsx para Resetar por Navegação: layout.tsx persiste entre navegações e seu estado sobrevive a mudanças de rota filha; quando você precisar especificamente remontar (por exemplo, resetar animações ou estado a cada navegação), use template.tsx em vez disso.
Analise Tipos de Parâmetros Dinâmicos: Cada valor de segmento dinâmico chega como uma string - const postId = Number(params.id) - então converta para a forma que você realmente precisa em vez de confiar apenas na anotação de tipo.
Use [[...slug]] Quando o Caminho Base Deve Corresponder: Um catch-all [...path] não corresponde à rota pai, então /docs retorna 404; mude para [[...path]] ou adicione um page.tsx separado ao lado dele quando o segmento base deve resolver.
Deixe o Estático Vencer o Dinâmico Explicitamente: Quando rotas estáticas e dinâmicas se sobrepõem, a estática sempre vence, então você pode manter um page.tsx em /blog/about/ ao lado de [slug]/page.tsx sem conflito.
generateStaticParams Executa no Tempo de Build: A função é executada durante next build, então qualquer fonte de dados indisponível falha o build; combine-a com dynamicParams = true quando novos caminhos ainda devem renderizar na primeira requisição.
error.tsx Deve Ser "use client": React Error Boundaries requerem ciclo de vida do cliente, então todo error.tsx precisa da diretiva "use client" - e ele só captura erros abaixo de si mesmo, nunca no layout.tsx irmão no mesmo segmento.
global-error.tsx Possui html e body: global-error.tsx substitui todo o layout raiz quando acionado, então ele deve renderizar seu próprio <html><body>; também note que ele só ativa em produção (o overlay de desenvolvimento roda em desenvolvimento).
notFound e redirect Lançam Exceções: Ambos lançam erros sentinela do Next.js, então um try/catch circundante os engole - chame-os fora de try/catch, ou use unstable_rethrow no bloco catch para deixá-los propagar.
Reserve not-found Raiz para Rotas Não Correspondentes: O not-found.tsx raiz captura automaticamente qualquer URL que não corresponda a uma rota, enquanto arquivos not-found.tsx aninhados só disparam quando você chama explicitamente notFound() de dentro dessa subárvore.
Layouts Não Podem Ler searchParams: Apenas páginas recebem searchParams; se um layout precisar de estado de URL, eleve a lógica para uma página ou um Client Component que use useSearchParams() dentro de um limite Suspense.
Passe Dados Via Contexto, Não Props de Layout: Layouts não podem encaminhar props para seus filhos, então compartilhe estado através de um provedor de Contexto do Cliente, cookies, ou um Server Component auxiliar que re-busque em cada filho.
Importe useRouter de next/navigation: No App Router, useRouter, usePathname e useSearchParams vivem em next/navigation; next/router é do Pages Router e falha silenciosamente ou retorna 404 quando importado.
Envolva useSearchParams em Suspense: useSearchParams() sem um limite <Suspense> circundante opta toda a rota para renderização no lado do cliente - sempre proteja-o: <Suspense fallback={null}><SearchFilters /></Suspense>.
Use useTransition para UI Pendente: router.push() retorna void, então envolva navegações em useTransition - startTransition(() => router.push("/dashboard")) - para obter uma flag isPending e desabilitar botões ou mostrar spinners durante mudanças de rota.
router.refresh Escopo para Rota Atual: refresh() re-busca dados do servidor apenas para a rota ativa; outras rotas em cache permanecem desatualizadas, então combine-o com revalidateTag/revalidatePath quando a mutação afetar irmãos.
Controle Prefetch e Scroll do Link: <Link> faz prefetch ao entrar na viewport e rola para o topo por padrão - <Link href="/settings" prefetch={false} scroll={false}> - defina prefetch={false} em links raramente usados e scroll={false} para UIs de abas/filtros que devem permanecer no lugar.
Sempre Defina um matcher de Middleware: Sem config.matcher seu middleware executa em cada requisição incluindo /_next/static e favicons - export const config = { matcher: ["/dashboard/:path*", "/api/:path*"] } - escopo explicitamente e exclua destinos de redirecionamento para evitar loops infinitos.
Middleware de Edge Proíbe APIs do Node: Middleware executa no Edge Runtime, então bcrypt, fs e a maioria dos drivers de banco de dados quebram no build ou em tempo de execução - use apenas Web APIs e bibliotecas compatíveis com edge.
Retorne NextResponse.next para Continuar: NextResponse.next() não causa curto-circuito; você deve return (ou um redirect/rewrite) para realmente parar a cadeia de middleware, caso contrário, a lógica subsequente continuará executando.
Cada Slot Paralelo Precisa de default.tsx: Pastas @slot devem incluir um fallback default.tsx, caso contrário, navegações rígidas ou sub-rotas não correspondentes retornam 404; slots também devem ser filhos diretos do layout e não podem aninhar uns dentro dos outros.
Reserve Espaço para Slots Independentes: Slots de rota paralelos resolvem independentemente, então dê a cada um uma altura fixa ou esqueleto correspondente ao conteúdo final - caso contrário, o streaming causa mudança visível de layout à medida que cada slot é preenchido.
Cuidado com a Convenção de Ponto de Interceptação: (.), (..), (..)(..) e (...) contam segmentos de grupos de rotas da mesma forma que pastas regulares, então grupos de rotas podem exigir um salto (..) extra; a falta de default.tsx no slot de hospedagem também quebra o descarte de navegação para trás.
Grupos de Rotas Não Podem Colidir: Duas pastas (group) não podem resolver para o mesmo caminho de URL (o build falha), e múltiplos layouts raiz forçam uma recarga completa da página entre os grupos em vez de navegação suave - mantenha a rota inicial / em exatamente um grupo.

Aguarde params e searchParams: No Next.js 15+, ambas as props são Promises em Server Components - const { id } = await params - desestruturar sem await retorna o objeto Promise e suas buscas retornarão silenciosamente undefined.
Não Colida page.tsx com route.tsx: Uma pasta não pode conter page.tsx e route.tsx - o Route Handler sombreará a página, então mantenha as rotas de API em app/api/ para evitar conflitos silenciosos.
Use template.tsx para Resetar por Navegação: layout.tsx persiste entre navegações e seu estado sobrevive a mudanças de rota filha; quando você precisar especificamente remontar (por exemplo, resetar animações ou estado a cada navegação), use template.tsx em vez disso.
Analise Tipos de Parâmetros Dinâmicos: Cada valor de segmento dinâmico chega como uma string - const postId = Number(params.id) - então converta para a forma que você realmente precisa em vez de confiar apenas na anotação de tipo.
Use [[...slug]] Quando o Caminho Base Deve Corresponder: Um catch-all [...path] não corresponde à rota pai, então /docs retorna 404; mude para [[...path]] ou adicione um page.tsx separado ao lado dele quando o segmento base deve resolver.
Deixe o Estático Vencer o Dinâmico Explicitamente: Quando rotas estáticas e dinâmicas se sobrepõem, a estática sempre vence, então você pode manter um page.tsx em /blog/about/ ao lado de [slug]/page.tsx sem conflito.
generateStaticParams Executa no Tempo de Build: A função é executada durante next build, então qualquer fonte de dados indisponível falha o build; combine-a com dynamicParams = true quando novos caminhos ainda devem renderizar na primeira requisição.
error.tsx Deve Ser "use client": React Error Boundaries requerem ciclo de vida do cliente, então todo error.tsx precisa da diretiva "use client" - e ele só captura erros abaixo de si mesmo, nunca no layout.tsx irmão no mesmo segmento.
global-error.tsx Possui html e body: global-error.tsx substitui todo o layout raiz quando acionado, então ele deve renderizar seu próprio <html><body>; também note que ele só ativa em produção (o overlay de desenvolvimento roda em desenvolvimento).
notFound e redirect Lançam Exceções: Ambos lançam erros sentinela do Next.js, então um try/catch circundante os engole - chame-os fora de try/catch, ou use unstable_rethrow no bloco catch para deixá-los propagar.
Reserve not-found Raiz para Rotas Não Correspondentes: O not-found.tsx raiz captura automaticamente qualquer URL que não corresponda a uma rota, enquanto arquivos not-found.tsx aninhados só disparam quando você chama explicitamente notFound() de dentro dessa subárvore.
Layouts Não Podem Ler searchParams: Apenas páginas recebem searchParams; se um layout precisar de estado de URL, eleve a lógica para uma página ou um Client Component que use useSearchParams() dentro de um limite Suspense.
Passe Dados Via Contexto, Não Props de Layout: Layouts não podem encaminhar props para seus filhos, então compartilhe estado através de um provedor de Contexto do Cliente, cookies, ou um Server Component auxiliar que re-busque em cada filho.
Importe useRouter de next/navigation: No App Router, useRouter, usePathname e useSearchParams vivem em next/navigation; next/router é do Pages Router e falha silenciosamente ou retorna 404 quando importado.
Envolva useSearchParams em Suspense: useSearchParams() sem um limite <Suspense> circundante opta toda a rota para renderização no lado do cliente - sempre proteja-o: <Suspense fallback={null}><SearchFilters /></Suspense>.
Use useTransition para UI Pendente: router.push() retorna void, então envolva navegações em useTransition - startTransition(() => router.push("/dashboard")) - para obter uma flag isPending e desabilitar botões ou mostrar spinners durante mudanças de rota.
router.refresh Escopo para Rota Atual: refresh() re-busca dados do servidor apenas para a rota ativa; outras rotas em cache permanecem desatualizadas, então combine-o com revalidateTag/revalidatePath quando a mutação afetar irmãos.
Controle Prefetch e Scroll do Link: <Link> faz prefetch ao entrar na viewport e rola para o topo por padrão - <Link href="/settings" prefetch={false} scroll={false}> - defina prefetch={false} em links raramente usados e scroll={false} para UIs de abas/filtros que devem permanecer no lugar.
Sempre Defina um matcher de Middleware: Sem config.matcher seu middleware executa em cada requisição incluindo /_next/static e favicons - export const config = { matcher: ["/dashboard/:path*", "/api/:path*"] } - escopo explicitamente e exclua destinos de redirecionamento para evitar loops infinitos.
Middleware de Edge Proíbe APIs do Node: Middleware executa no Edge Runtime, então bcrypt, fs e a maioria dos drivers de banco de dados quebram no build ou em tempo de execução - use apenas Web APIs e bibliotecas compatíveis com edge.
Retorne NextResponse.next para Continuar: NextResponse.next() não causa curto-circuito; você deve return (ou um redirect/rewrite) para realmente parar a cadeia de middleware, caso contrário, a lógica subsequente continuará executando.
Cada Slot Paralelo Precisa de default.tsx: Pastas @slot devem incluir um fallback default.tsx, caso contrário, navegações rígidas ou sub-rotas não correspondentes retornam 404; slots também devem ser filhos diretos do layout e não podem aninhar uns dentro dos outros.
Reserve Espaço para Slots Independentes: Slots de rota paralelos resolvem independentemente, então dê a cada um uma altura fixa ou esqueleto correspondente ao conteúdo final - caso contrário, o streaming causa mudança visível de layout à medida que cada slot é preenchido.
Cuidado com a Convenção de Ponto de Interceptação: (.), (..), (..)(..) e (...) contam segmentos de grupos de rotas da mesma forma que pastas regulares, então grupos de rotas podem exigir um salto (..) extra; a falta de default.tsx no slot de hospedagem também quebra o descarte de navegação para trás.
Grupos de Rotas Não Podem Colidir: Duas pastas (group) não podem resolver para o mesmo caminho de URL (o build falha), e múltiplos layouts raiz forçam uma recarga completa da página entre os grupos em vez de navegação suave - mantenha a rota inicial / em exatamente um grupo.

Melhores Práticas de Roteamento do Next.js

Buscar na documentação

Melhores Práticas de Roteamento do Next.js