Arquitetura (Feature-Sliced Design)
Prioridade: P2 (MÉDIA)
Adote Feature-Sliced Design (FSD) para aplicações escaláveis. Aviso: FSD introduz boilerplate. Utilize-o apenas se o projeto for crescer significativamente (ex: 20+ features). Para projetos menores, uma estrutura simples baseada em módulos é preferível.
Estratégia
- Limites RSC: Aplique regras estritas de serialização para props passadas do Servidor para o Cliente. Consulte Limites RSC e Serialização.
- Camada App é Enxuta: O diretório
app/(App Router) é apenas para Roteamento.- Regra:
page.tsxdeve importar apenas Widgets/Features. Nenhuma lógica de negócio (useEffect,fetch) diretamente nas páginas.
- Regra:
- Slices em vez de Tipos: Agrupe código por Domínio de Negócio (Usuário, Produto, Carrinho), não por Tipo de Arquivo (Componentes, Hooks, Utilitários).
- Ruim:
src/components/LoginForm.tsx,src/hooks/useLogin.ts - Bom:
src/features/auth/login/contendo ambos.
- Ruim:
- Hierarquia de Camadas: O código só pode importar de camadas abaixo dela.
App->Widgets->Features->Entities->Shared.
- Evite Entidades Excessivas: Não crie Entities prematuramente.
- Regra: Inicie a lógica em
FeaturesouPages. Mova paraEntitiesapenas quando dados/lógica forem estritamente reutilizados em várias features diferentes. - Regra: CRUD simples pertence a
shared/api, não aentities.
- Regra: Inicie a lógica em
- Segmentos Padrão: Use nomes de segmento padrão dentro dos slices.
ui(Componentes),model(Estado/ações),api(Busca de dados),lib(Auxiliares),config(Constantes).- Evite:
components,hooks,servicescomo nomes de segmento.
Estrutura de Referência
Para a disposição específica de diretórios e definições de camadas, consulte a documentação de referência.
- Estrutura de Pastas FSD
- Empacotamento e Compatibilidade
- Seleção de Runtime (Edge/Node)
- Dicas de Depuração e MCP
Checklist de Arquitetura (Obrigatório)
-
Imports entre Camadas: Alguma camada importa de uma camada ACIMA dela? (App > Widgets > Features > Entities > Shared)
-
Lógica de Página:
page.tsxé enxuta, contendo apenas Widgets/Features e zerouseEffect/fetch? -
Limites RSC: Os Componentes Servidor estão isolados dos Componentes Cliente com limites 'use client' adequados?
-
API Pública: Todo acesso a um slice é feito pelo
index.ts(API pública) do nível superior? -
Cross-Slice: Slices dentro da mesma camada (ex: duas features) importam diretamente um do outro? (Proibido)
-
Server Actions: Coloque-as na pasta
model/de uma Feature (ex:features/auth/model/actions.ts). -
Acesso a Dados (DAL): Coloque a lógica na pasta
model/de uma Entity (ex:entities/user/model/dal.ts). -
Componentes de UI: UI base (shadcn) pertence a
shared/ui. UI específica de feature pertence afeatures/*/ui.
Anti-Patterns
- Sem imports cross-slice: Slices na mesma camada não devem importar diretamente um do outro.
- Sem lógica de negócio em
page.tsx: Páginas importam apenas Widgets/Features; zerouseEffect/fetch. - Sem pastas por tipo de arquivo: Agrupe por domínio (
features/auth/), não por tipo (components/,hooks/). - Sem criação prematura de Entity: Comece em Features; mova para Entities apenas por reuso estrito.