Fork of aidenybai/react-doctor — adapted for offline use and direct GitHub installation as a project dependency. Third-party network calls removed, runtime dependencies restructured for npm install github:cherijs/react-doctor support.

Scans your React codebase for security, performance, correctness, and architecture issues, then outputs a 0-100 score with actionable diagnostics.

The core scanning engine, rules, and scoring are unchanged from upstream.

As a project devDependency (recommended for teams):

npm install -D github:cherijs/react-doctor

Then run:

npx react-doctor . --verbose --offline

Or run without installing:

npx -y react-doctor@latest .

Note: npx react-doctor@latest pulls from the upstream npm registry, not this fork. Use the GitHub install for the fork version.

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

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
  --offline         skip network requests
  -h, --help        display help for command

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.

CLI flags always override config values.

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.

This fork includes a Claude Code skill at skills/react-doctor/SKILL.md. Install it globally:

npx skills add cherijs/react-doctor@react-doctor -g -y

Or reference it from your project's .claude/skills/ directory.

git clone https://github.com/cherijs/react-doctor
cd react-doctor
pnpm install
pnpm -r run build
node packages/react-doctor/dist/cli.js /path/to/your/react-project

Built on react-doctor by Aiden Bai. Original project is MIT-licensed.

MIT