animation-best-practices

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 →

https://github.com/user-attachments/assets/07cc88d9-9589-44c3-aa73-5d603cb1c570

How it works

React Doctor detects your framework (Next.js, Vite, Remix, etc.), React version, and compiler setup, then runs two analysis passes in parallel:

1. Lint: Checks 60+ rules across state & effects, performance, architecture, bundle size, security, correctness, accessibility, and framework-specific categories (Next.js, React Native). Rules are toggled automatically based on your project setup.
2. Dead code: Detects unused files, exports, types, and duplicates.

Diagnostics are filtered through your config, then scored by severity (errors weigh more than warnings) to produce a 0–100 health score (75+ Great, 50–74 Needs work, <50 Critical).

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 for your coding agent

Teach your coding agent all 47+ React best practice rules. Run this at your project root:

npx -y react-doctor@latest install

You'll be prompted to pick which detected agents to install for. Pass --yes to skip prompts and install for every detected agent.

Supports Claude Code, Codex, GitHub Copilot, Gemini CLI, Cursor, OpenCode, Factory Droid, and Pi.

GitHub Actions

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

Input	Default	Description
directory	.	Project directory to scan
verbose	true	Show file details per rule
project		Workspace project(s) to scan (comma-separated)
diff		Base branch for diff mode. Only changed files are scanned
github-token		When set on pull_request events, posts findings as a PR comment
fail-on	error	Exit with error code on diagnostics: error, warning, none
offline	false	Skip sending diagnostics to the react.doctor API
node-version	20	Node.js version to use

The action outputs a score (0–100) you can use in subsequent steps.

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
  -h, --help        display help for command

Browser API

Import react-doctor/browser to run the same diagnostics merge, config-based filtering, timing, and scoring pipeline as react-doctor/api’s diagnose, but with caller-supplied inputs: project metadata, a virtual projectFiles map (contents keyed by paths relative to rootDirectory) for ignore/suppression resolution, and a runOxlint callback that performs linting in your environment (for example a Web Worker with oxlint).

Git history, real filesystem discovery, knip, the CLI, staged-file detection, and interactive prompts are not available in the browser bundle; treat those as Node-only or supply equivalents yourself. react-doctor/worker re-exports the same browser-facing modules for worker targets.

If you call diagnoseCore yourself in the browser, pass calculateDiagnosticsScore from this package (re-exported as calculateScore on react-doctor/browser) so the bundle never pulls in Node-only proxy code.

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.
failOn	"error" | "warning" | "none"	"none"	Exit with error code on diagnostics of the given severity or above
customRulesOnly	boolean	false	Disable built-in react/jsx-a11y/compiler rules, keeping only react-doctor/* plugin rules
share	boolean	true	Show the share-your-results URL after scanning
textComponents	string[]	[]	React Native only. Component names whose children should not trigger rn-no-raw-text (e.g. ["MyText", "Label.Bold"])

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.