Analise Seu Código React em Busca de Anti-Padrões com React Doctor

Aplicações React raramente desmoronam de uma vez só. Elas se degradam gradualmente—um useEffect desnecessário aqui, algumas camadas extras de prop drilling ali, um atributo de acessibilidade silenciosamente ausente. Quando esses problemas aparecem em produção, corrigi-los é caro.

React Doctor é uma ferramenta CLI de código aberto criada para detectar esses problemas antes que se acumulem. Execute um comando, obtenha uma pontuação de saúde do código de 0 a 100 e receba diagnósticos acionáveis em toda a sua base de código.

O Que o React Doctor Realmente Faz (e o Que Não Faz)

React Doctor é uma ferramenta de análise estática, não um profiler de runtime. Ele não mede tempos de renderização ou rastreia re-renderizações de componentes em uma aplicação em execução. Em vez disso, ele lê seu código-fonte e identifica problemas estruturais antes mesmo de você executar a aplicação.

Essa distinção é importante. Ferramentas como o React DevTools Profiler mostram o que está lento em tempo de execução. React Doctor mostra por que seu código é estruturalmente frágil—prop drilling que torna a refatoração dolorosa, effects que não deveriam existir, exportações mortas que inflam seu bundle e violações de acessibilidade que afetam usuários reais.

É também mais do que um linter. Ferramentas como ESLint detectam problemas de sintaxe e aplicam regras de estilo. React Doctor analisa a saúde mais ampla do projeto ao escanear categorias como arquitetura, tamanho do bundle, segurança, código morto e padrões específicos de frameworks. Ele detecta seu framework e configuração React automaticamente, depois ativa as regras relevantes.

Como Analisar Seu Projeto React em 30 Segundos

Nenhuma instalação necessária. Navegue até a raiz do seu projeto e execute:

npx -y react-doctor@latest .

Adicione --verbose para ver caminhos de arquivo exatos e números de linha para cada problema:

npx -y react-doctor@latest . --verbose

React Doctor executa duas passagens em paralelo: uma passagem de lint através das regras ativas, e uma passagem de código morto que sinaliza arquivos, exportações, tipos e duplicatas não utilizados. Os resultados são pontuados por severidade—erros pesam mais que avisos—produzindo uma pontuação final de saúde: 75+ é Ótimo, 50–74 é Precisa Melhorar, abaixo de 50 é Crítico.

Os Anti-Padrões React Que Ele Identifica

Aqui estão os tipos de problemas estruturais que o React Doctor comumente identifica:

Uso desnecessário de useEffect — Quando derivações de estado acontecem dentro de effects em vez de durante a renderização, você obtém bugs de dados obsoletos e lógica mais difícil de acompanhar. A própria orientação do React cada vez mais recomenda derivar valores durante a renderização sempre que possível, em vez de depender de effects.

Passagem profunda de props — Passar props através de muitas camadas de componentes é um sinal de alerta estrutural. A solução geralmente é Context, composição ou co-localização de estado.

Keys de lista que podem causar renderização instável — Usar identificadores instáveis (como índices de array) pode levar a bugs sutis de UI quando listas são reordenadas.

Importações pesadas de bibliotecas — Importar bibliotecas inteiras pode inflar bundles. React Doctor pode destacar padrões onde divisão de código via React.lazy() ou ferramentas de framework como next/dynamic podem ajudar.

Lacunas de acessibilidade — Atributos ausentes como alt em imagens ou outras omissões de acessibilidade podem passar despercebidos no desenvolvimento, mas afetam usuários reais.

Potenciais secrets no código-fonte — A análise estática pode detectar padrões que se assemelham a chaves de API ou tokens commitados em um repositório.

Integrando React Doctor ao Fluxo de Trabalho da Sua Equipe

Para equipes, a integração mais valiosa é o workflow do GitHub Actions:

- uses: actions/checkout@v5
  with:
    fetch-depth: 0
- uses: millionco/react-doctor@main
  with:
    diff: main
    github-token: ${{ secrets.GITHUB_TOKEN }}

A opção diff analisa apenas arquivos alterados em um pull request, mantendo o CI rápido. Quando github-token é fornecido, os resultados são publicados diretamente como um comentário no PR—sem precisar vasculhar logs.

Para fluxos de trabalho assistidos por IA, você pode ensinar agentes de codificação como Cursor ou Claude Code as regras de boas práticas React usadas pelo React Doctor:

curl -fsSL https://react.doctor/install-skill.sh | bash

Isso permite que seu agente diagnostique problemas e proponha correções usando o mesmo conjunto de regras que o React Doctor aplica.

Pontuações de Saúde do Mundo Real

React Doctor foi executado em vários projetos React de código aberto conhecidos:

Mesmo projetos maduros e bem mantidos têm espaço para melhorar. Esses problemas se acumulam silenciosamente, e a análise automatizada é uma das maneiras mais simples de detectá-los cedo.

Conclusão

React Doctor não substitui a revisão de código, mas remove as partes tediosas dela. Problemas estruturais, lacunas de acessibilidade, código morto e riscos de segurança são detectados automaticamente, para que revisores humanos possam focar em decisões de lógica e design.

Execute-o uma vez em seu projeto atual. A pontuação que você recebe de volta dirá mais sobre a saúde da sua base de código do que uma semana de revisão manual.

Perguntas Frequentes

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers. Check our GitHub repo and join the thousands of developers in our community.