Project Structure
Core Idea
Referência completa das convenções de pastas e arquivos do App Router (arquivos especiais, rotas dinâmicas, route groups, slots paralelos/interceptados, metadata files) e das estratégias recomendadas para organizar o projeto.
Key Concepts
app/pages/public/src: pastas de topo padrão; app é o App Router, src é opcional para separar código de config.- Arquivos especiais de rota:
page, layout, loading, error, global-error, not-found, route, template, default (cada um com papel fixo na hierarquia).
- Rota pública: um segmento só vira acessível via URL quando contém
page ou route; outros arquivos no mesmo diretório podem ser colocalizados sem virar rota.
- Dynamic segments:
[segment] (um parâmetro), [...segment] (catch-all), [[...segment]] (catch-all opcional).
- Route groups
(folder): agrupam rotas sem afetar a URL; usados para múltiplos layouts raiz ou layouts opcionais por seção.
- Private folders
_folder: prefixo de underscore tira a pasta (e subpastas) do sistema de roteamento; útil para separar lógica de UI de lógica de rota.
- Parallel routes
@slot: slots nomeados renderizados pelo layout pai (ex.: sidebar + main).
- Intercepting routes:
(.)folder, (..)folder, (..)(..)folder, (...)folder interceptam outra rota para renderizar dentro do layout atual sem mudar a URL (ex.: modais).
- Component hierarchy: ordem de renderização por arquivo especial:
layout → template → error (boundary) → loading (suspense) → not-found (boundary) → page ou layout aninhado.
- Colocation: arquivos de projeto podem ficar dentro de
app com segurança, só viram rota se forem page/route.
Reference Tables
| Path | URL pattern |
|---|
app/blog/[slug]/page.tsx | /blog/my-first-post |
app/shop/[...slug]/page.tsx | /shop/clothing, /shop/clothing/shirts |
app/docs/[[...slug]]/page.tsx | /docs, /docs/layouts-and-pages, ... |
| Pattern | Significado | Uso típico |
|---|
@folder | slot nomeado | sidebar + conteúdo principal |
(.)folder | intercepta mesmo nível | preview de rota irmã em modal |
(..)folder | intercepta nível pai | abrir filho do pai como overlay |
(..)(..)folder | intercepta dois níveis | overlay profundamente aninhado |
(...)folder | intercepta a partir da raiz | mostrar rota arbitrária na view atual |
| Arquivo top-level | Papel |
|---|
next.config.js | configuração do Next.js |
instrumentation.ts | OpenTelemetry e instrumentação |
proxy.ts | proxy de requisições |
.env / .env.local / .env.production / .env.development | variáveis de ambiente |
eslint.config.mjs | configuração do ESLint |
Anti-patterns
- Achar que basta criar a pasta para a rota existir: sem
page.js ou route.js a rota não é publicamente acessível, mesmo com subpastas criadas.
- Colocar
layout.js em toda pasta "só para garantir": layouts se aninham automaticamente pela hierarquia de pastas; layout extra sem necessidade quebra reuso.
- Remover o
layout.js raiz sem substituí-lo: ao criar múltiplos root layouts via route groups, cada grupo precisa do próprio <html>/<body>, senão a app quebra.
Key Takeaways
- Rota só é pública quando existe
page ou route no segmento, tudo mais no diretório é colocalizável com segurança.
- Route groups
(nome) organizam sem afetar URL e permitem múltiplos root layouts ou layouts opcionais por seção.
- Private folders
_nome tiram pastas inteiras do roteamento, úteis para separar UI/lib do que é rota.
- Parallel (
@slot) e intercepting ((.), (..), (...)) routes resolvem padrões de UI específicos como slots e modais sem mudar a URL.
- Next.js é "unopinionated" sobre organização: colocar arquivos fora de
app, dentro de app na raiz, ou divididos por feature são estratégias igualmente válidas, escolha uma e seja consistente.
Connects To
- Layouts and Pages: aplica na prática as convenções
page/layout descritas aqui.
- Linking and Navigating: rotas dinâmicas e route groups afetam como o prefetch/streaming se comporta.