Erros Comuns e Armadilhas da Arquitetura React

Um guia de campo sobre os erros mais comuns que arquitetos React e líderes técnicos cometem em projetos reais - agrupados por área e ordenados do fundamental ao específico. Use-o como uma revisão pré-lançamento, uma lista de verificação de auditoria de código ou um documento de integração para novos contratados seniores.

Como Usar Esta Lista

• Percorra cada item - se você não puder dizer com confiança "nós não fazemos isso", crie um ticket.
• Não a trate como um guia de estilo - estes são modos de falha arquitetônica, não regras de lint.
• Releia a cada marco. Os erros que prejudicam no MVP são diferentes daqueles que prejudicam em escala.

Estado e Dados (1–6)

1. Estado global por padrão - Recorrer a Redux, Zustand ou um átomo global no momento em que dois componentes compartilham dados.

   • Por que acontece: As equipes assumem que "compartilhado = global" e pulam o estado local, o estado elevado e o estado da URL como opções.
   • Correção: Comece com estado local; eleve apenas quando um irmão realmente precisar; promova para global apenas quando 3 ou mais branches não relacionados o lerem.

2. Contexto para valores de atualização rápida - Colocar estado de formulário, contadores ou posição do cursor em um provedor de Contexto.

   • Por que acontece: "Contexto resolve prop drilling" é generalizado demais.
   • Correção: Contexto é para valores de baixa frequência e leitura ampla (tema, usuário de autenticação, localidade). Para valores de atualização rápida, use Zustand, Jotai ou estado local.

3. Busca em useEffect - fetch manual + setState + booleanos de carregamento/erro em cada componente.

   • Por que acontece: É o que a maioria dos tutoriais ainda mostra.
   • Correção: Use TanStack Query, SWR ou RSC. Cache, dedup, retries e tratamento de erros são problemas resolvidos.

4. Nenhuma estratégia de invalidação de cache - Mutações bem-sucedidas, mas a visualização da lista ainda mostra dados desatualizados.

   • Por que acontece: As equipes configuram uma biblioteca de dados, mas nunca codificam convenções de invalidação.
   • Correção: Defina uma taxonomia de chave de consulta antecipadamente e use invalidateQueries/mutate consistentemente em cada mutação.

5. Busca apenas no cliente no App Router do Next.js - Cada página começa com "use client" e busca no cliente.

   • Por que acontece: Memória muscular do Pages Router ou dias de SPA.
   • Correção: Use componentes de servidor por padrão; busque no servidor; desça para o cliente apenas para interatividade.

6. Estado da URL armazenado no estado React - Filtros, abas, paginação e flags de diálogo aberto mantidos em useState.

   • Por que acontece: useState é o caminho mais curto.
   • Correção: Coloque estado compartilhável/navegável com botões de voltar/avançar na URL (searchParams, route params). Reserve useState para estado de UI verdadeiramente efêmero.

Componentes e Abstrações (7–12)

7. Abstração prematura - Extrair um componente "reutilizável" após o segundo uso, travando uma API ruim.

   • Por que acontece: Dogma DRY e o desejo de parecer organizado.
   • Correção: Espere o terceiro uso real. Três cópias semelhantes são mais baratas do que uma abstração errada.

8. Wrappers sobre wrappers - Button personalizado envolve Button do shadcn que envolve Button do Radix - ninguém sabe quais props atingem o DOM.

   • Por que acontece: As equipes se protegem contra cada API de terceiros "por via das dúvidas".
   • Correção: Use componentes de terceiros diretamente, a menos que você tenha um motivo concreto para envolver. Quando você envolver, reexporte o tipo subjacente com ComponentPropsWithoutRef.

9. Prop drilling ignorado - Uma prop passa por 6 componentes que não a utilizam.

   • Por que acontece: Refatorar cadeias de props parece arriscado.
   • Correção: Use composição (children, slot props), um Contexto colocalizado ou promova o consumidor para cima na árvore.

10. Sobre-memoização - useMemo, useCallback e React.memo espalhados por toda parte.

    • Por que acontece: Culto de carga como "melhor prática de performance".
    • Correção: Memoize apenas após perfilar um problema real de re-renderização. A memoização tem um custo - tanto de tempo de execução quanto cognitivo.

11. Sub-memoização de caminhos quentes reais - Uma tabela de 10.000 linhas re-renderiza cada célula a cada pressionamento de tecla.

    • Por que acontece: "React é rápido" é generalizado demais; a perfilagem é pulada.
    • Correção: Perfilar com React DevTools, virtualizar listas longas, dividir contexto e memoizar o componente quente real.

12. Componentes de página massivos - Arquivos de página de 600 linhas fazendo busca, estado, layout e lógica de negócios.

    • Por que acontece: Começa com 80 linhas e cresce uma funcionalidade de cada vez.
    • Correção: Extraia módulos de funcionalidade com uma API pública clara. Uma página deve principalmente orquestrar - não implementar.

Limite Cliente/Servidor (13–17)

13. "use client" no topo da árvore - Marcar o layout raiz como cliente puxa toda a árvore para o bundle do cliente.

    • Por que acontece: Uma criança precisa de um hook e o líder adiciona "use client" ao ancestral mais próximo.
    • Correção: Empurre "use client" o mais fundo possível - isole-o na folha que realmente usa hooks/eventos.

14. Tratando RSC como SSR - Esperando useState ou useEffect em um componente de servidor.

    • Por que acontece: O modelo mental do Pages Router continua.
    • Correção: Componentes de servidor são um primitivo diferente - sem hooks, sem estado, sem manipuladores de eventos. Aprenda o limite antes de escrever código.

15. Surpresas de serialização - Passar uma instância de classe, função ou objeto que envolve Date de um componente de servidor para um de cliente.

    • Por que acontece: Os tipos compilam bem; o erro aparece em tempo de execução.
    • Correção: Passe dados serializáveis simples (strings, números, arrays, POJOs). Reconstrua instâncias de classe no componente cliente, se necessário.

16. Misturando padrões do Pages Router no App Router - Convenções de getServerSideProps, getStaticProps ou _app.tsx invadindo app/.

    • Por que acontece: Tutoriais, Stack Overflow e dados de treinamento de LLM antigos assumem o Pages Router.
    • Correção: Leia node_modules/next/dist/docs/ diretamente. Preste atenção aos avisos de depreciação. Não copie e cole de fontes anteriores a 2024.

17. Cachoeiras de dados em componentes de servidor aninhados - awaits sequenciais que bloqueiam a renderização.

    • Por que acontece: Cada componente busca seus próprios dados, sem saber dos irmãos.
    • Correção: Paralelize com Promise.all, eleve buscas para um pai compartilhado ou use loading.tsx + streaming no nível da rota.

Performance (18–21)

18. Sem orçamento de bundle - Nenhuma verificação de CI no tamanho do JS; cada dependência aumenta silenciosamente o bundle.

    • Por que acontece: "Lidaremos com isso mais tarde."
    • Correção: Adicione um orçamento de tamanho à CI (por exemplo, @next/bundle-analyzer, size-limit) e falhe PRs que o excedam.

19. Armadilhas de tree-shaking de arquivos de barril - Importando de index.ts que reexporta tudo.

    • Por que acontece: Barris parecem limpos em tempo de desenvolvimento.
    • Correção: Importe do caminho de origem (lib/date/format) ou audite se o seu bundler realmente faz tree-shaking dos seus barris (muitos não fazem de forma confiável).

20. Componentes de cliente para conteúdo estático - Páginas de marketing marcadas como "use client" para uma única animação.

    • Por que acontece: Um widget interativo puxa a página inteira para o bundle do cliente.
    • Correção: Mantenha a página como um componente de servidor; renderize o widget interativo como uma pequena ilha cliente.

21. Sem monitoramento de Core Web Vitals - Envio sem telemetria LCP/INP/CLS.

    • Por que acontece: Testes sintéticos passam; métricas de usuários reais são uma reflexão tardia.
    • Correção: Conecte Vercel Analytics, web-vitals + seu provedor de analytics, ou PostHog Web Vitals desde o primeiro dia.

Qualidade e Testes (22–25)

22. Testando detalhes de implementação - Testes afirmam chamadas setState, nomes de métodos internos ou estado privado.

    • Por que acontece: Hábitos da era Enzyme e uso excessivo de snapshot-testing.
    • Correção: Teste o comportamento visível pelo usuário com Testing Library. Afirme o que o usuário vê e faz, não como o estado é atualizado.

23. Mockando a rede em testes de integração - jest.mock("axios") stubs espalhados pela suíte.

    • Por que acontece: MSW parece mais configuração inicial.
    • Correção: Use MSW (Mock Service Worker) uma vez - camada de rede real, manipuladores realistas, compartilhados entre unit e E2E.

24. Sem limites de erro - Um erro em tempo de execução desmonta todo o aplicativo.

    • Por que acontece: Limites de erro parecem uma preocupação "adicionaremos mais tarde".
    • Correção: Envolva o layout raiz, cada segmento de rota e qualquer widget arriscado (gráficos, embeds de terceiros) em limites de erro com fallbacks sensatos.

25. Sem orçamento de acessibilidade - Navegação por teclado nunca testada; axe-core / jsx-a11y nunca ativado.

    • Por que acontece: Acessibilidade é repriorizada atrás de funcionalidades até uma auditoria de conformidade.
    • Correção: Ative eslint-plugin-jsx-a11y desde o primeiro dia, execute axe-core em E2E e teste a navegação por teclado como parte da revisão de PR.

Equipe e Processo (26–30)

26. Escolhas de stack sem ADR - Cada novo contratado relitiga "por que não Remix?"

    • Por que acontece: As decisões vivem em threads do Slack que rolam para o esquecimento.
    • Correção: Confirme registros de decisões de arquitetura (ADRs) em docs/adr/ com contexto, decisão, consequências e uma data de revisão.

27. Monorepo como bala de prata - Turborepo/Nx adotados para um aplicativo e um pacote compartilhado.

    • Por que acontece: Conteúdo influenciador da FAANG faz monorepos parecerem universais.
    • Correção: Mantenha um único repositório até ter pelo menos duas superfícies implantáveis compartilhando código não trivial. A sobrecarga só compensa nesse ponto.

28. Reescrever em vez de migrar - "Vamos reescrever em Remix/TanStack Start/Next.js 15."

    • Por que acontece: Migrações parecem mais lentas do que greenfield, e os líderes subestimam o risco de regressão de funcionalidades.
    • Correção: Migre incrementalmente atrás de uma flag de recurso; prove paridade rota por rota antes de aposentar o código antigo.

29. Dívida de DX (Developer Experience) - Verificação de tipo lenta, HMR lento, testes instáveis - ignorados até que a velocidade da equipe colapse.

    • Por que acontece: DX não tem um PM pressionando por isso.
    • Correção: Reserve tempo explícito de DX a cada trimestre. Monitore o tempo de tsc --noEmit, a latência do HMR e a duração da suíte de testes como métricas visíveis.

30. Contratação por familiaridade com framework em vez de fundamentos - Um especialista em Next.js que não consegue explicar reconciliação, chaves ou memoização.

    • Por que acontece: Entrevistas supervalorizam o framework atual em alta.
    • Correção: Entreviste para o modelo mental do React (renderização, estado, efeitos, chaves) e uma habilidade sênior de JS/TS (tipos, assíncrono, performance). APIs de framework são aprendíveis em uma semana; fundamentos não são.

Aplicando a Lista

• Nível 1 (1–6): Estado e dados. Errar aqui é a principal causa de débito técnico frontend - corrija-os primeiro.
• Nível 2 (7–12): Forma do componente. Afeta a velocidade de cada nova funcionalidade - aborde durante qualquer refatoração importante.
• Nível 3 (13–17): RSC / higiene de limites. Crítico no Next.js 15 / App Router - não envie sem revisar.
• Nível 4 (18–21): Performance. Adicione orçamentos e telemetria antes que o bundle se torne impossível de corrigir.
• Nível 5 (22–25): Qualidade e testes. Barato de configurar em uma nova base de código; caro de refatorar.
• Nível 6 (26–30): Equipe e processo. Os itens de maior alavancagem - mas os mais fáceis de adiar.

Relacionados

• Checklist de Decisões de Arquitetura React - Decisões a serem tomadas antes que os erros comuns se apliquem.
• Melhores Práticas de Fundamentos React - Regras no nível do componente que previnem muitos desses erros.
• Fluxo de Decisão de Componentes - Como decidir onde um componente vive e o que ele possui.
• Performance - Técnicas concretas para os erros de performance acima.