Prioridade: P0 (CRÍTICA)
Diretrizes de Implementação
Arquitetura de Roteamento
- Estrutura: Use o diretório
app/. Defina rotas com app/dashboard/layout.tsx retornando {children}; a UI compartilhada se aninha automaticamente em app/layout.tsx. Gerencie estados com loading.tsx, error.tsx e not-found.tsx.
- Segmentos: Organize funcionalidades com Grupos de Rotas (colchetes
(auth)) para serem excluídos do caminho da URL. Use Rotas Dinâmicas (colchetes [slug]) e defina caminhos estáticos via generateStaticParams.
- Especializados: Use Rotas Paralelas (
@modal) adicionando o slot ao layout pai e fornecendo um fallback default.tsx. Use Rotas de Interceptação ((.)route) para layouts avançados como painéis de controle.
Dados e Funções
- Next.js 15+ Assíncrono: Sempre use
await no params: Promise, searchParams, cookies() e headers().
- Segurança: Use
middleware.ts para autenticação e redirecionamento no lado do edge. Garanta que todos os Route Handlers (route.ts) estejam protegidos com verificações de autenticação apropriadas.
- RSC: Padrão para React Server Components (RSC). Use
'use client' apenas em nós folha para interatividade (hooks/eventos).
- Error Boundaries: Crie
app/dashboard/loading.tsx para envolver automaticamente as rotas em um boundary de Suspense. Em error.tsx, use 'use client' e forneça uma função reset: () => void.
Exemplo
import { cookies } from 'next/headers'
export default async function DashboardLayout({
children,
modal
}: {
children: React.ReactNode
modal: React.ReactNode
}) {
const cookieStore = await cookies()
const theme = cookieStore.get('theme')
return (
<>
{children}
{modal}
</>
)
}
Convenções de Arquivos
- page.tsx: UI para uma rota.
- layout.tsx: UI compartilhada que envolve os filhos. Persiste durante a navegação.
- loading.tsx: Boundary de Suspense para estados de carregamento.
- error.tsx: Error boundary (deve ser um Componente Cliente).
- route.ts: Endpoint de API no lado do servidor.
Padrões de Estrutura
- Grupos de Rotas: Use parênteses
(auth) para organizar sem afetar o caminho da URL.
- Pastas Privadas: Use sublinhado
_lib para excluir do roteamento.
- Rotas Dinâmicas: Use colchetes
[slug] ou [...slug] (catch-all).
Melhores Práticas
- Boundaries RSC: Garanta que as props passadas para Componentes Cliente sejam serializáveis. Veja RSC Boundaries & Serialization.
- Rotas Paralelas (
@folder): Renderize múltiplas páginas no mesmo layout. Use default.tsx para fallback.
- Rotas de Interceptação (
(..)folder): Carregue rotas dentro do contexto do layout atual.
- Colocação: Mantenha arquivos de componente, estilos e testes dentro da pasta da rota.
- Layouts: Use o Layout Raiz (
app/layout.tsx) para as tags <html> e <body>.
- Padrão de Self-Hosting
Anti-Padrões
- Nenhum await em APIs assíncronas:
params, cookies(), headers() são Promises no Next.js 15+; sempre use await.
- Nenhum
'use client' na raiz da árvore: Coloque nas folhas; mantenha layouts e páginas como Server Components.
- Nenhuma tag
<html>/<body> em layouts aninhados: Apenas app/layout.tsx (layout raiz) deve incluí-las.
- Nenhum
error.tsx ausente: Cada segmento de rota precisa de um error boundary de Componente Cliente.