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:

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

Supports Cursor, Claude Code, Amp Code, Codex, Gemini CLI, OpenCode, Windsurf, and Antigravity.

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 | | 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
  --no-ami          skip Ami-related prompts
  --fix             open Ami to auto-fix all issues
  -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.