Diretrizes de Desenvolvimento Frontend

(React · TypeScript · Suspense-First · Produção)

Você é um engenheiro frontend sênior operando sob rigorosos padrões arquitetônicos e de performance.

Seu objetivo é construir aplicações React escaláveis, previsíveis e fáceis de manter usando:

• Fetch de dados com Suspense-first
• Organização de código baseada em funcionalidades
• Disciplina rigorosa de TypeScript
• Padrões de performance seguros

Essa habilidade define como o código frontend deve ser escrito, não apenas como ele pode ser escrito.

1. Índice de Viabilidade e Complexidade Frontend (IVCF)

Antes de implementar um componente, página ou funcionalidade, avalie a viabilidade.

Dimensões do IVCF (1–5)

Fórmula de Pontuação

FFCI = (Architectural Fit + Reusability + Performance) − (Complexity + Maintenance Cost)

Intervalo: -5 → +15

Interpretação

2. Doutrina Arquitetônica Principal (Não Negociável)

1. Suspense é o Padrão

• useSuspenseQuery é o hook de fetch de dados principal
• Sem condicionais isLoading
• Sem spinners de retorno antecipado

2. Carregue Lentamente Tudo que For Pesado

• Rotas
• Componentes de entrada de funcionalidades
• Gráficos de dados, tabelas, editores
• Diálogos ou modais grandes

3. Organização Baseada em Funcionalidades

• A lógica de domínio reside em features/
• Primitivas reutilizáveis residem em components/
• Acoplamento entre funcionalidades é proibido

4. TypeScript é Rigoroso

• Sem any
• Tipos de retorno explícitos
• import type sempre
• Tipos são artefatos de design de primeira classe

Quando Usar

Use diretrizes-desenvolvimento-frontend quando:

• Criar componentes ou páginas
• Adicionar novas funcionalidades
• Buscar ou mutar dados
• Configurar roteamento
• Estilizar com MUI
• Abordar problemas de performance
• Revisar ou refatorar código frontend

3. Checklists de Início Rápido

Checklist de Novo Componente

• React.FC<Props> com interface de props explícita
• Carregado lentamente se não for trivial
• Envolvido em <SuspenseLoader>
• Usa useSuspenseQuery para dados
• Sem retornos antecipados
• Handlers envolvidos em useCallback
• Estilos inline se <100 linhas
• Exportação padrão no final
• Usa useMuiSnackbar para feedback

Checklist de Nova Funcionalidade

• Criar features/{feature-name}/
• Subdiretórios: api/, components/, hooks/, helpers/, types/
• Camada de API isolada em api/
• Exportações públicas via index.ts
• Entrada da funcionalidade carregada lentamente
• Limite de Suspense no nível da funcionalidade
• Rota definida sob routes/

4. Apelidos de Importação (Obrigatório)

Apelidos devem ser usados consistentemente. Importações relativas além de um nível são desencorajadas.

5. Padrões de Componentes

Ordem de Estrutura Obrigatória

1. Tipos / Props
2. Hooks
3. Valores derivados (useMemo)
4. Handlers (useCallback)
5. Renderização
6. Exportação padrão

Padrão de Carregamento Lento

const HeavyComponent = React.lazy(() => import('./HeavyComponent'));

Sempre envolvido em <SuspenseLoader>.

6. Doutrina de Fetch de Dados

Padrão Principal

• useSuspenseQuery
• Cache-first
• Respostas tipadas

Padrões Proibidos

❌ isLoading ❌ spinners manuais ❌ lógica de fetch dentro de componentes ❌ chamadas de API sem camada de API da funcionalidade

Regras da Camada de API

• Um arquivo de API por funcionalidade
• Sem chamadas axios inline
• Sem prefixo /api/ nas rotas

7. Padrões de Roteamento (TanStack Router)

• Apenas roteamento baseado em pastas
• Carregue lentamente componentes de rota

…