React Doctor: Is This the Missing Health Check for Your React Codebase?

If you have ever inherited a messy React codebase, or simply wondered whether your own project has drifted into bad patterns over time, React Doctor is a tool worth knowing about. One command, a score between 0 and 100, and a list of problems to fix. That is the pitch. Let us dig into whether it lives up to it.

What Is React Doctor?

React Doctor is an open-source CLI tool from the team behind Million.js. It scans your React project and produces a health score alongside a structured list of issues. Think of it as a linter on steroids — one that understands React patterns specifically, rather than just generic JavaScript rules.

npx -y react-doctor@latest .

That is all it takes to run it. No installation, no config file required to get started.

How It Works Under the Hood

When you run React Doctor against your project, it does two things in parallel.

1. Lint pass

It checks 60+ rules organized into categories: state and effects, performance, architecture, bundle size, security, correctness, accessibility, and framework-specific concerns (Next.js, React Native). Importantly, it detects your framework, React version, and compiler setup automatically, and toggles rules accordingly. So if you are on Next.js, it will apply Next.js-specific rules without you having to configure anything.

2. Dead code detection

It runs a separate pass to find unused files, unused exports, unused types, and duplicates across your codebase.

After both passes, it filters the results through any config you have set, then computes a score weighted by severity:

• 75 and above: Great
• 50 to 74: Needs work
• Below 50: Critical

Errors weigh more than warnings, so a single serious issue pulls the score down more than a pile of minor ones.

Getting Verbose Output

By default you get a summary. Add --verbose and you see the exact files and line numbers involved:

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

This is the mode you actually want when fixing things, since the summary alone does not tell you where to look.

Real-World Scores on Popular Projects

The repo includes a leaderboard of scans against well-known open-source React projects. Here is a snapshot:

Even tldraw and excalidraw — projects maintained by experienced teams — score in the mid-80s, not 100. This is a useful calibration. Do not expect to hit a perfect score; the goal is identifying what actually matters in your specific project.

Plugging It Into CI With GitHub Actions

React Doctor ships a GitHub Action you can drop into any 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 is particularly useful — it tells the action to only scan files that changed relative to your base branch. This means in a pull request, it only flags new problems introduced by that PR, not pre-existing issues across the whole repo. The action also posts findings as a PR comment when github-token is set.

The action outputs a score value you can use in subsequent steps — for example, failing the build if a PR drops the score below a threshold you define.

Config File

You can suppress specific rules or exclude files via a react-doctor.config.json at the project root:

{
  "ignore": {
    "rules": ["react/no-danger", "jsx-a11y/no-autofocus"],
    "files": ["src/generated/**"]
  }
}

Or, if you prefer not to add another config file, you can put the same config under a "reactDoctor" key in your package.json.

Using It Programmatically

If you want to integrate React Doctor into a custom script or tooling pipeline, there is a Node.js API:

import { diagnose } from "react-doctor/api";

const result = await diagnose("./path/to/your/react-project");

console.log(result.score);       // { score: 82, label: "Good" }
console.log(result.diagnostics); // Array of Diagnostic objects
console.log(result.project);     // Framework, React version, compiler info

Each diagnostic object tells you the file, plugin, rule, severity, message, help text, line, and column. Clean enough to build your own reporting on top of.

Teaching Your AI Coding Agent React Best Practices

One underrated feature: React Doctor can install a "skill" into your coding agent — Cursor, Claude Code, Windsurf, Copilot, and others are supported:

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

This teaches the agent 47+ React best practice rules so it can catch issues proactively while you write code, not just after the fact.

Is It Worth Adding to Your Project?

Here is an honest assessment.

Where it genuinely helps:

• Onboarding onto a legacy codebase. Run it once and you immediately get a map of the biggest problems, organized by category.
• Enforcing standards across a team. The CI integration with diff mode means new PRs cannot silently introduce new antipatterns without someone noticing.
• Dead code. Most linters do not catch unused files and exports across the entire project. React Doctor does this out of the box.
• Framework-specific rules. If you are on Next.js, generic linters miss a lot. React Doctor knows about Next.js patterns and flags them appropriately.

Where you should temper expectations:

• It is not a replacement for a well-configured ESLint setup. It is a complement. If you already have strict ESLint rules, some overlap is inevitable.
• The score is a rough guide, not a precise metric. A score of 72 versus 75 does not mean much. Focus on the specific diagnostics, not the number.
• It is relatively new (still under active development with open issues and PRs). Some rules may be noisy or context-dependent, which is why the config ignore list exists.
• The --fix flag hands off to an AI agent (Ami) to auto-fix issues. This part is more experimental and depends on external tooling.

Bottom line: if you run npx -y react-doctor@latest . --verbose on your project right now and nothing surprises you, you probably did not need it. But if it surfaces 50 unused exports, three components with missing keys in lists, and a handful of useEffect dependency issues you forgot about, that is a morning of tech debt cleanup you would not have found otherwise.

For the CI use case alone — automatically flagging React-specific regressions in PRs with zero config — it earns its place in a frontend workflow.

Getting Started in 60 Seconds

# Run against your project
npx -y react-doctor@latest . --verbose

# If you use workspaces, select specific packages
npx -y react-doctor@latest . --project my-app

# Only scan changed files vs main
npx -y react-doctor@latest . --diff main

# Output just the score (useful in scripts)
npx -y react-doctor@latest . --score

The GitHub repo is at github.com/millionco/react-doctor.