A code clinic examination room with a health score dashboard and a gray cat on a shelf

React Doctor: A One-Command Health Check for Your Entire React Codebase

The Gray Cat
The Gray Cat

Every React project starts healthy. The components are small, the dependencies are few, and the hooks follow the rules. Then time passes. Someone hardcodes an API key. A useEffect does the job of a derived variable. Three files stop being imported by anything. An image tag loses its alt text. Nobody notices because nothing breaks -- until the bundle is 4 MB, the Lighthouse score is in free fall, and a security audit finds a Stripe key sitting in a utility file.

react-doctor is a CLI tool that scans your React codebase and produces a 0-100 health score based on 60+ rules across security, performance, architecture, accessibility, correctness, and bundle size. It detects your framework, your React version, and your compiler setup automatically, then runs lint checks and dead code detection in parallel. Built by Aiden Bai of Million.js fame, it is powered by Oxlint under the hood, making it 50-100x faster than an equivalent ESLint setup.

What the Doctor Ordered

React Doctor covers a lot of ground with a single command:

  • 60+ lint rules across 8 categories: state and effects, performance, architecture, bundle size, security, correctness, accessibility, and framework-specific checks
  • Dead code detection powered by Knip, finding unused files, exports, types, and duplicates
  • Automatic framework detection for Next.js, Vite, Remix, React Native, and more
  • 0-100 health score weighted by severity, so errors count more than warnings
  • Diff mode to scan only changed files against a base branch
  • Monorepo support with workspace-aware project selection
  • GitHub Action for automated PR comments with score changes
  • AI agent integration as a skill for Cursor, Claude Code, Gemini CLI, and others

Scrub In

Install via your package manager:

npm install -g react-doctor

or

yarn global add react-doctor

Or skip the install entirely and run it with npx:

npx -y react-doctor@latest .

Your First Checkup

Running the Scan

Point React Doctor at your project directory and let it work:

// From the command line:
// npx -y react-doctor@latest .

The output groups diagnostics by category, shows a count of errors and warnings for each rule, and ends with your overall health score. A score of 75 or above means your project is in good shape. Between 50 and 74, there is work to do. Below 50, consider it critical.

For more detail on exactly which files are affected, add the verbose flag:

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

This shows file paths and line numbers for every diagnostic, making it straightforward to locate and fix each issue.

Selective Surgery

Not every scan needs to cover everything. If you only care about lint rules and want to skip dead code detection, or vice versa:

// Skip dead code analysis
// npx -y react-doctor@latest . --no-dead-code

// Skip lint checks, only find dead code
// npx -y react-doctor@latest . --no-lint

For monorepos, React Doctor auto-detects workspace projects and prompts you to select which ones to scan. To skip the prompt and scan everything:

// npx -y react-doctor@latest . --yes

Or target a specific project:

// npx -y react-doctor@latest . --project my-app

Configuring the Rules

Not every rule applies to every project. Maybe you intentionally use dangerouslySetInnerHTML in a sandboxed component, or you have generated files that should not be analyzed. Create a react-doctor.config.json at your project root:

// react-doctor.config.json
const config = {
  ignore: {
    rules: ["react/no-danger", "jsx-a11y/no-autofocus", "knip/exports"],
    files: ["src/generated/**", "src/legacy/**"]
  }
};

You can also add a "reactDoctor" key in your package.json instead of creating a separate config file. Either way, ignored rules will not count against your score, and ignored files will be excluded from scanning entirely.

Advanced Diagnostics

The Programmatic API

React Doctor is not just a CLI. It exposes a Node.js API for building custom tooling, dashboards, or integrations:

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

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

console.log(result.score);
// { score: 82, label: "Good" }

console.log(result.project);
// { framework: "next", reactVersion: "19.1.0", compiler: true }

console.log(result.diagnostics.length);
// 47

for (const diagnostic of result.diagnostics) {
  console.log(
    `[${diagnostic.severity}] ${diagnostic.category}/${diagnostic.rule}: ${diagnostic.message}`
  );
  console.log(`  ${diagnostic.filePath}:${diagnostic.line}:${diagnostic.column}`);
  if (diagnostic.help) {
    console.log(`  Fix: ${diagnostic.help}`);
  }
}

Each diagnostic includes the file path, plugin, rule name, severity, message, help text, line, column, and category. This gives you everything you need to build a custom reporting pipeline, feed results into a monitoring system, or create a Slack bot that posts the health score after every deploy.

Guarding the Gates with CI

The --score flag outputs only the numeric score, which makes it perfect for CI pipelines:

// In a GitHub Actions workflow or any CI script:
// npx -y react-doctor@latest . --score
// Output: 78

For GitHub specifically, React Doctor ships as a GitHub Action that can comment on pull requests with the scan results:

// .github/workflows/react-doctor.yml
// name: React Doctor
// on: [pull_request]
// jobs:
//   scan:
//     runs-on: ubuntu-latest
//     steps:
//       - uses: actions/checkout@v4
//       - uses: millionco/react-doctor@main
//         with:
//           github-token: ${{ secrets.GITHUB_TOKEN }}

The diff mode is especially useful in CI. Instead of scanning the entire codebase on every PR, scan only the files that changed:

// Only scan changes relative to main branch
// npx -y react-doctor@latest . --diff main

This keeps scan times fast even on large codebases and focuses the review on what actually changed.

Teaching Your AI to Heal

One of the more unusual features of React Doctor is its integration with AI coding agents. You can install it as a "skill" for tools like Cursor, Claude Code, Windsurf, and others:

// Install the React Doctor skill for your AI agent
// curl -fsSL https://react.doctor/install-skill.sh | bash

Once installed, the AI agent can run diagnostics, understand the results, and propose fixes directly in your editor. The --fix flag takes this further by connecting to Ami, React Doctor's own AI assistant, to auto-fix detected issues. This is an early feature and the project is still pre-1.0, but it represents an interesting direction: linting tools that do not just find problems but collaborate with AI to resolve them.

How It Compares

The traditional approach to React linting is ESLint with eslint-plugin-react and eslint-plugin-react-hooks. That setup is highly configurable and has a massive plugin ecosystem, but it is slow (JavaScript-based), requires manual configuration, and does not provide a unified health score. React Doctor bundles an opinionated set of rules, runs them through Oxlint's Rust-based engine, and adds dead code detection via Knip -- all in one command.

Biome is another fast Rust-based alternative, but it positions itself as a general-purpose linter and formatter rather than a React-specific diagnostic tool. It has no scoring system and no dead code analysis. Knip itself handles only the dead code side of things, with no React-specific lint rules. React Doctor effectively wraps both Oxlint and Knip into a single cohesive experience.

The Prognosis

React Doctor is still young -- first published in February 2026, it reached version 0.0.29 in its first week and gathered over 5,000 GitHub stars in under two weeks. That kind of velocity signals genuine demand for a tool that makes React code health visible and measurable without a 45-minute ESLint configuration session.

The value proposition is simple: one command, one score, sixty rules, zero configuration. It catches the security leaks, the performance anti-patterns, the dead exports piling up in your codebase, and the accessibility gaps that slip through code review. Whether you run it locally, wire it into CI, or hand it to an AI agent, react-doctor gives your React project a checkup it probably needs.