Escanea tu código React en busca de anti-patrones con React Doctor

Las aplicaciones React rara vez se desmoronan de golpe. Se degradan gradualmente: un useEffect innecesario aquí, algunas capas adicionales de prop drilling allá, un atributo de accesibilidad que falta silenciosamente. Para cuando estos problemas aparecen en producción, solucionarlos resulta costoso.

React Doctor es una herramienta CLI de código abierto diseñada para detectar estos problemas antes de que se acumulen. Ejecuta un comando, obtén una puntuación de salud del código de 0 a 100 y recibe diagnósticos accionables en toda tu base de código.

Lo que React Doctor realmente hace (y lo que no hace)

React Doctor es una herramienta de análisis estático, no un perfilador en tiempo de ejecución. No mide tiempos de renderizado ni rastrea re-renderizados de componentes en una aplicación en vivo. En cambio, lee tu código fuente e identifica problemas estructurales antes de que ejecutes la aplicación.

Esta distinción es importante. Herramientas como el React DevTools Profiler te muestran qué es lento en tiempo de ejecución. React Doctor te muestra por qué tu código es estructuralmente frágil: prop drilling que hace doloroso el refactoring, efectos que no deberían existir, exportaciones muertas que inflan tu bundle y violaciones de accesibilidad que afectan a usuarios reales.

También es más que un linter. Herramientas como ESLint detectan problemas de sintaxis y aplican reglas de estilo. React Doctor analiza la salud general del proyecto escaneando categorías como arquitectura, tamaño del bundle, seguridad, código muerto y patrones específicos del framework. Detecta tu framework y configuración de React automáticamente, y luego activa las reglas relevantes.

Cómo escanear tu proyecto React en 30 segundos

No requiere instalación. Navega a la raíz de tu proyecto y ejecuta:

npx -y react-doctor@latest .

Agrega --verbose para ver las rutas exactas de archivos y números de línea para cada problema:

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

React Doctor ejecuta dos pasadas en paralelo: una pasada de lint a través de las reglas activas, y una pasada de código muerto que marca archivos, exportaciones, tipos y duplicados no utilizados. Los resultados se califican por severidad —los errores pesan más que las advertencias— produciendo una puntuación final de salud: 75+ es Excelente, 50–74 necesita trabajo, menos de 50 es Crítico.

Los anti-patrones de React que detecta

Estos son los tipos de problemas estructurales que React Doctor comúnmente identifica:

Uso innecesario de useEffect — Cuando las derivaciones de estado ocurren dentro de efectos en lugar de durante el renderizado, obtienes bugs de datos obsoletos y lógica más difícil de seguir. La propia guía de React recomienda cada vez más derivar valores durante el renderizado cuando sea posible en lugar de depender de efectos.

Paso profundo de props — Pasar props a través de muchas capas de componentes es una señal de advertencia estructural. La solución suele ser Context, composición o co-localización de estado.

Keys de listas que pueden causar renderizado inestable — Usar identificadores inestables (como índices de arrays) puede llevar a bugs sutiles de UI cuando las listas se reordenan.

Importaciones pesadas de librerías — Importar librerías completas puede inflar los bundles. React Doctor puede resaltar patrones donde la división de código mediante React.lazy() o herramientas de framework como next/dynamic pueden ayudar.

Brechas de accesibilidad — Atributos faltantes como alt en imágenes u otras omisiones de accesibilidad pueden pasar desapercibidas durante el desarrollo pero afectan a usuarios reales.

Posibles secretos en el código fuente — El escaneo estático puede detectar patrones que se asemejan a claves API o tokens comprometidos en un repositorio.

Integrando React Doctor en el flujo de trabajo de tu equipo

Para equipos, la integración más valiosa es el flujo de trabajo de GitHub Actions:

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

La opción diff escanea solo los archivos modificados en un pull request, manteniendo el CI rápido. Cuando se proporciona github-token, los hallazgos se publican directamente como un comentario en el PR —sin necesidad de revisar logs.

Para flujos de trabajo asistidos por IA, puedes enseñar a agentes de codificación como Cursor o Claude Code las reglas de mejores prácticas de React utilizadas por React Doctor:

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

Esto permite que tu agente diagnostique problemas y proponga correcciones usando el mismo conjunto de reglas que aplica React Doctor.

Puntuaciones de salud en el mundo real

React Doctor se ha ejecutado contra varios proyectos React de código abierto conocidos:

Incluso los proyectos maduros y bien mantenidos tienen margen de mejora. Estos problemas se acumulan silenciosamente, y el escaneo automatizado es una de las formas más simples de detectarlos temprano.

Conclusión

React Doctor no reemplaza la revisión de código, pero elimina las partes tediosas de ella. Los problemas estructurales, brechas de accesibilidad, código muerto y riesgos de seguridad se detectan automáticamente, permitiendo que los revisores humanos se enfoquen en decisiones de lógica y diseño.

Ejecútalo una vez en tu proyecto actual. La puntuación que obtengas te dirá más sobre la salud de tu base de código que una semana de revisión manual.

Preguntas frecuentes

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.