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.

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).

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

Teach your coding agent React best practices. 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 50+ coding agents via agent-install, including Claude Code, Codex, Cursor, Factory Droid, Gemini CLI, GitHub Copilot, Goose, OpenCode, Pi, Windsurf, Roo Code, Cline, Kilo Code, Warp, Replit, OpenHands, Continue, and many more. Detection is the union of CLI binaries on $PATH and config dirs in $HOME (~/.claude, ~/.cursor, ~/.codex, ~/.factory, ~/.pi, etc.).

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

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

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
  --json             output a single structured JSON report (suppresses other output)
  -y, --yes          skip prompts, scan all workspace projects
  --full             skip prompts, always run a full scan (decline diff-only)
  --project <name>   select workspace project (comma-separated for multiple)
  --diff [base]      scan only files changed vs base branch
  --offline          skip telemetry (anonymous, not stored, only used to calculate score)
  --staged           scan only staged (git index) files for pre-commit hooks
  --fail-on <level>  exit with error code on diagnostics: error, warning, none
  --annotations      output diagnostics as GitHub Actions annotations
  -h, --help         display help for command

Pass --json to get a single, parsable JSON object on stdout. All human-readable output, prompts, and the share link are suppressed; pipe straight into jq, node, or any other tool:

npx -y react-doctor@latest . --json | jq '.summary'

Exit code is 0 on success and 1 if the scan throws or --fail-on is triggered. Errors still produce a JSON object with ok: false, so the stdout is always a valid document.

interface JsonReport {
  schemaVersion: 1;
  version: string; // react-doctor version
  ok: boolean; // false when an error was thrown
  directory: string; // resolved root passed to the CLI
  mode: "full" | "diff" | "staged";
  diff: {
    baseBranch: string;
    currentBranch: string;
    changedFileCount: number;
    isCurrentChanges: boolean;
  } | null;
  projects: Array<{
    directory: string;
    project: ProjectInfo;
    diagnostics: Diagnostic[];
    score: { score: number; label: string } | null;
    skippedChecks: string[];
    elapsedMilliseconds: number;
  }>;
  diagnostics: Diagnostic[]; // flattened across all scanned projects
  summary: {
    errorCount: number;
    warningCount: number;
    affectedFileCount: number;
    totalDiagnosticCount: number;
    score: number | null; // worst project score, when available
    scoreLabel: string | null;
  };
  elapsedMilliseconds: number; // total wall time across all projects
  error: {
    message: string;
    name: string;
    chain: string[]; // outer error message first, every `error.cause`
    // unwrapped after; chain[0] always equals `message`
  } | null; // null on success, populated when ok=false
}

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.

Suppress a rule on a specific line with // react-doctor-disable-line or the next line with // react-doctor-disable-next-line:

// react-doctor-disable-next-line react-doctor/no-cascading-set-state
useEffect(() => {
  setA(value);
  setB(value);
  setC(value);
}, [value]);

const value = expensiveComputation(); // react-doctor-disable-line react-doctor/no-usememo-simple-expression

Block comments work too — useful inside JSX where // line comments aren't legal:

{/* react-doctor-disable-next-line react/no-danger */}
<div dangerouslySetInnerHTML={{ __html }} />

Comma- or space-separate multiple rule ids on the same comment. With no rule id, the comment suppresses every diagnostic on that line.

By default, React Doctor honors all of the ignore-style files your project already has, so you don't need to maintain a separate "what should react-doctor skip" list:

React Doctor also respects inline lint suppressions in source files:

• // oxlint-disable, // oxlint-disable-line, // oxlint-disable-next-line — with or without rule ids.
• // eslint-disable, // eslint-disable-line, // eslint-disable-next-line — oxlint reads both prefixes interchangeably.

Note: .editorconfig is intentionally NOT consulted. It describes editor settings (indent size, charset, end-of-line) and has no concept of "files to skip" — there's nothing in it that would change what react-doctor lints.

If you want React Doctor to ignore those inline suppressions and audit your codebase for everything (useful for one-off "what does my project actually score?" runs), set:

{ "respectInlineDisables": false }

This only neutralizes the inline // eslint-disable* / // oxlint-disable* comments — the file-level ignore lists above are always honored, even in audit mode, because they typically point at vendored or generated code that genuinely shouldn't be linted.

If your project already has a JSON-format oxlint or eslint config (.oxlintrc.json or .eslintrc.json), React Doctor merges it into the same scan via oxlint's extends field. Diagnostics from your existing rules count toward the React Doctor score alongside the curated React Doctor rule set — no separate oxlint / eslint invocation needed.

{
  "rules": {
    "no-debugger": "error",
    "no-empty": "warn"
  }
}

Detection runs at the project root and walks up to the nearest project boundary (.git directory or monorepo root), so a single .oxlintrc.json at the top of a monorepo is picked up by every workspace package below it. The first match wins (.oxlintrc.json is preferred over .eslintrc.json).

Behavior notes you may run into:

• Only JSON-format configs are pulled in. oxlint's extends cannot evaluate JS or TS, so flat configs (eslint.config.js), legacy JS configs (.eslintrc.js / .eslintrc.cjs), and TypeScript oxlint configs (oxlint.config.ts) are silently skipped.
• Rule-level severities ("rules": { "no-debugger": "error" }) flow through. Category-level enables ("categories": { "correctness": "error" }) do not — React Doctor explicitly disables every oxlint category to keep the rule set scoped to its curated surface, so your category opinions are dropped. Rewrite them as explicit rules: entries if you want them to count.
• Plugins from your config are unioned in, so "plugins": ["unicorn"] + "rules": { "unicorn/no-array-for-each": "error" } works.
• If oxlint can't load your config (broken JSON, missing plugin, unknown rule name), React Doctor logs the reason on stderr and retries once without extends so the scan still produces a useful score off the curated rule set.

To opt out completely, set:

{ "adoptExistingLintConfig": false }

customRulesOnly: true also implies adoptExistingLintConfig: false — that mode runs only the react-doctor/* plugin and ignores every external rule, including your own.

Upgrading from an earlier version? This feature is on by default. Projects with an existing .oxlintrc.json / .eslintrc.json will see new diagnostics flow into the score, and the score may drop. Set "adoptExistingLintConfig": false if you want to preserve the old behavior.

CLI flags always override config values.

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: "Great" } 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;
}

To produce the same structured output the --json CLI flag emits, use toJsonReport:

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

const result = await diagnose(".");

const report = toJsonReport(result, { version: "1.0.0" });
console.log(JSON.stringify(report, null, 2));

const counts = summarizeDiagnostics(result.diagnostics);
console.log(`${counts.errorCount} errors, ${counts.warningCount} warnings`);

react-doctor/api also re-exports the JsonReport, JsonReportSummary, JsonReportProjectEntry, and JsonReportMode types, plus the lower-level buildJsonReport and buildJsonReportError builders if you need to assemble reports from multiple diagnose() calls.

The same React Doctor rule set is shipped as both an oxlint plugin and an ESLint plugin so you can wire it into whichever lint engine your project already runs — no extra dependency on the react-doctor CLI.

Register the plugin directly in your .oxlintrc.json:

{
  "jsPlugins": [
    {
      "name": "react-doctor",
      "specifier": "react-doctor/oxlint-plugin",
    },
  ],
  "rules": {
    "react-doctor/no-fetch-in-effect": "warn",
    "react-doctor/no-derived-state-effect": "warn",
    // ...pick the rules you want
  },
}

// eslint.config.js
import reactDoctor from "react-doctor/eslint-plugin";

export default [
  reactDoctor.configs.recommended,
  // Framework presets are composable — pick the ones that match your stack:
  reactDoctor.configs.next,
  reactDoctor.configs["react-native"],
  reactDoctor.configs["tanstack-start"],
  reactDoctor.configs["tanstack-query"],
  // Or turn everything on at the same severities react-doctor uses:
  // reactDoctor.configs.all,
];

Cherry-pick instead of using a preset:

import reactDoctor from "react-doctor/eslint-plugin";

export default [
  {
    plugins: { "react-doctor": reactDoctor },
    rules: {
      "react-doctor/no-fetch-in-effect": "warn",
      "react-doctor/no-derived-state-effect": "warn",
    },
  },
];

Diagnostics from these rules surface inline through your editor's existing ESLint / oxlint integration — no separate react-doctor invocation needed.

The full rule list and default severities live in oxlint-config.ts.

See the live leaderboard at react.doctor/leaderboard for current scores across React projects.

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 build

Run locally:

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

React Doctor is MIT-licensed open-source software.