Scan Your React Code for Anti-Patterns with React Doctor

React applications rarely fall apart all at once. They degrade gradually—one unnecessary useEffect here, a few extra layers of prop drilling there, an accessibility attribute quietly missing. By the time these issues surface in production, fixing them is expensive.

React Doctor is an open-source CLI tool built to catch these problems before they compound. Run one command, get a 0–100 code health score, and receive actionable diagnostics across your entire codebase.

What React Doctor Actually Does (and What It Doesn’t)

React Doctor is a static analysis tool, not a runtime profiler. It doesn’t measure render times or track component re-renders in a live app. Instead, it reads your source code and identifies structural problems before you ever run the application.

This distinction matters. Tools like the React DevTools Profiler show you what’s slow at runtime. React Doctor shows you why your code is structurally fragile—prop drilling that makes refactoring painful, effects that shouldn’t exist, dead exports that inflate your bundle, and accessibility violations that affect real users.

It’s also more than a linter. Tools like ESLint catch syntax issues and enforce style rules. React Doctor analyzes broader project health by scanning categories like architecture, bundle size, security, dead code, and framework-specific patterns. It detects your framework and React configuration automatically, then activates the relevant rules.

How to Scan Your React Project in 30 Seconds

No installation required. Navigate to your project root and run:

npx -y react-doctor@latest .

Add --verbose to see exact file paths and line numbers for each issue:

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

React Doctor runs two passes in parallel: a lint pass across active rules, and a dead code pass that flags unused files, exports, types, and duplicates. Results are scored by severity—errors weigh more than warnings—producing a final health score: 75+ is Great, 50–74 is Needs Work, below 50 is Critical.

The React Anti-Patterns It Surfaces

Here’s the type of structural issues React Doctor commonly identifies:

Unnecessary useEffect usage — When state derivations happen inside effects instead of during render, you get stale data bugs and harder-to-follow logic. React’s own guidance increasingly recommends deriving values during render where possible rather than relying on effects.

Deep prop passing — Passing props through many component layers is a structural warning sign. The fix is often Context, composition, or state co-location.

List keys that may cause unstable rendering — Using unstable identifiers (such as array indexes) can lead to subtle UI bugs when lists reorder.

Heavy library imports — Importing entire libraries can inflate bundles. React Doctor can highlight patterns where code splitting via React.lazy() or framework tools like next/dynamic may help.

Accessibility gaps — Missing attributes such as alt on images or other accessibility oversights can slip through development unnoticed but affect real users.

Potential secrets in source code — Static scanning can detect patterns that resemble API keys or tokens committed to a repository.

Integrating React Doctor into Your Team Workflow

For teams, the most valuable integration is the GitHub Actions workflow:

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

The diff option scans only files changed in a pull request, keeping CI fast. When github-token is provided, findings are posted directly as a PR comment—no digging through logs.

For AI-assisted workflows, you can teach coding agents like Cursor or Claude Code the React best-practice rules used by React Doctor:

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

This lets your agent diagnose issues and propose fixes using the same rule set React Doctor applies.

Real-World Health Scores

React Doctor has been run against several well-known open-source React projects:

Even mature, well-maintained projects have room to improve. These issues accumulate quietly, and automated scanning is one of the simplest ways to catch them early.

Conclusion

React Doctor doesn’t replace code review, but it removes the tedious parts of it. Structural problems, accessibility gaps, dead code, and security risks get caught automatically, so human reviewers can focus on logic and design decisions.

Run it once on your current project. The score you get back will tell you more about your codebase’s health than a week of manual review.

FAQs

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.