What is React Doctor?

React Doctor is an open-source CLI tool that scans your entire React codebase and returns a health score from 0 to 100, with file-level diagnostics and actionable recommendations all from a single command. It works with Next.js, Vite, Remix, and React Native, and requires no installation.

In professional Front-end development projects, code quality tends to degrade gradually. New features land, refactors get half-finished, and architectural decisions that made sense two years ago become liabilities. The tricky part is that this kind of decay is hard to see until it causes actual problems.

React Doctor gives you a number. Run it on any React project and you get a score between 0 and 100, a categorized list of issues, and the file paths where they live. That makes the problem visible and measurable.

What React Doctor analyzes? Fast diagnosis and a reliable code health metric

React Doctor analyzes more than 60 quality rules across performance, security, architecture, bundle size, accessibility, and dead code. The scoring works like this:

  • ≤ 50 → Critical issues
  • 50–75 → Needs improvement
  • ≥ 75 → Good code health

What makes it practical for CI/CD is the speed. Under the hood, React Doctor uses Oxlint, a linter built in Rust, which can process tens of thousands of lines of code in milliseconds. That’s fast enough to run on every pull request without adding meaningful latency to your pipeline.

The tool was built by Aiden Bai, the creator of Million.js. It has accumulated over 6,000 GitHub stars and 6,400 weekly npm installs since its release in February 2026.

Installation and basic usage

React Doctor works as a CLI tool that you run from the root directory of your project. No installation needed.

# Scan the project
npx -y react-doctor@latest .

Add –verbose to get a detailed report including file paths and line numbers:

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

React Doctor auto-detects your framework (Next.js, Vite, Remix, etc.), your React version, and whether you’re using the React compiler, then runs two analysis passes in parallel: a lint pass and a dead code pass.

1. Correctness and security

  • Detects hardcoded secrets in client-side code
  • Identifies suspicious patterns such as eval() usage
  • Warns about common React anti-patterns (e.g., using array index as a key)

2. Performance and usage patterns

  • Evaluates misuse of hooks, such as unnecessary useEffect
  • Flags patterns that cause excessive re-renders
  • Identifies heavy library imports that should be lazy-loaded (e.g., importing all of recharts instead of individual components)
  • Suggests using useTransition for loading states where appropriate

3. Architecture and structure

  • Identifies overly large components and low-cohesion modules
  • Detects improper imports (e.g., import _ from 'lodash' instead of modular imports)
  • Detects and reports dead code: unused files, unexported functions, duplicate types

GitHub actions integration

React Doctor can be integrated into GitHub Actions to automatically evaluate pull requests:

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

The action outputs a numeric score you can reference in subsequent pipeline steps. This lets teams enforce quality thresholds directly at the PR level architectural regressions get caught before they reach production. When combined with a structured Test automation strategy, React Doctor becomes part of a quality engineering layer that protects your frontend at scale.

AI-Powered Integrations

React Doctor can be installed as a skill for AI coding agents, including Cursor, Claude Code, GitHub Copilot, Gemini CLI, Amp Code, OpenCode, and Windsurf. This gives the agent direct access to React Doctor’s diagnostic rules, it can run an audit and then apply fixes automatically. For teams already using AI-assisted development, this significantly reduces the manual effort involved in codebase cleanup.

When should you use React Doctor?

React Doctor is a natural fit if:

  • You maintain a large or rapidly evolving React project
  • You want enforceable quality standards across your team
  • You’re about to do a refactor and want a baseline before you start
  • You care about CI/CD integration with a measurable output

Thanks to its simplicity and comprehensive diagnostic capabilities, React Doctor is worth considering as a core part of your code quality assurance process in any serious React project.