Let coding agents diagnose and fix your React code.

One command scans your codebase for security, performance, correctness, and architecture issues, then outputs a 0–100 score with actionable diagnostics.

See it in action →

Main.mp4

Install

Run this at your project root:

npx -y react-doctor@latest .

Use --verbose to see affected files and line numbers:

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

Install as a skill

Add React Doctor's rules as a skill for your coding agent:

npx skills add millionco/react-doctor

This gives agents like Cursor, Claude Code, Copilot, and others access to all 47+ React best practice rules. The CLI will also prompt to install the skill on first run.

Options

Usage: react-doctor [directory] [options]

Options:
  -v, --version     display the version number
  --no-lint         skip linting
  --no-dead-code    skip dead code detection
  --verbose         show file details per rule
  --score           output only the score
  -y, --yes         skip prompts, scan all workspace projects
  --project <name>  select workspace project (comma-separated for multiple)
  --diff [base]     scan only files changed vs base branch
  --fix             open Ami to auto-fix all issues
  --prompt          copy latest scan output to clipboard
  -h, --help        display help for command

Configuration

Create a react-doctor.config.json in your project root to customize behavior:

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

You can also use the "reactDoctor" key in your package.json instead:

{
  "reactDoctor": {
    "ignore": {
      "rules": ["react/no-danger"]
    }
  }
}

If both exist, react-doctor.config.json takes precedence.

Config options

Key	Type	Default	Description
ignore.rules	string[]	[]	Rules to suppress, using the plugin/rule format shown in diagnostic output (e.g. react/no-danger, knip/exports, knip/types)
ignore.files	string[]	[]	File paths to exclude, supports glob patterns (src/generated/**, **/*.test.tsx)
lint	boolean	true	Enable/disable lint checks (same as --no-lint)
deadCode	boolean	true	Enable/disable dead code detection (same as --no-dead-code)
verbose	boolean	false	Show file details per rule (same as --verbose)
diff	boolean | string	—	Force diff mode (true) or pin a base branch ("main"). Set to false to disable auto-detection.

CLI flags always override config values.

Node.js API

You can also use React Doctor programmatically:

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

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

console.log(result.score); // { score: 82, label: "Good" } or null
console.log(result.diagnostics); // Array of Diagnostic objects
console.log(result.project); // Detected framework, React version, etc.

The diagnose function accepts an optional second argument:

const result = await diagnose(".", {
  lint: true, // run lint checks (default: true)
  deadCode: true, // run dead code detection (default: true)
});

Each diagnostic has the following shape:

interface Diagnostic {
  filePath: string;
  plugin: string;
  rule: string;
  severity: "error" | "warning";
  message: string;
  help: string;
  line: number;
  column: number;
  category: string;
}

Scores for popular open-source projects

Project	Score	Share
tldraw	84	view
excalidraw	84	view
twenty	78	view
plane	78	view
formbricks	75	view
posthog	72	view
supabase	69	view
onlook	69	view
payload	68	view
sentry	64	view
cal.com	63	view
dub	62	view

Contributing

Want to contribute? Check out the codebase and submit a PR.

git clone https://github.com/millionco/react-doctor
cd react-doctor
pnpm install
pnpm -r run build

Run locally:

node packages/react-doctor/dist/cli.js /path/to/your/react-project

License

React Doctor is MIT-licensed open-source software.