Is Your React Code Sick? Let the 12.4K‑Star react‑doctor Diagnose It in One Command

What It Scans

react-doctor comes from the Million.js team, the group behind the React optimization compiler, so they know React performance pitfalls. The tool examines a project across dimensions such as state management, side effects, performance, architecture, security, and accessibility—areas where AI‑generated code often slips.

The scan output lists each issue with file name and line number. Example warnings include:

New object created every render : creating a new object each render changes the reference passed to child components, causing unnecessary re‑renders.

useState synced from prop : initializing state from a prop means later prop changes won’t update the state, leading to stale data.

Fetch in useEffect without race guard : issuing a request in useEffect without protecting against race conditions allows an earlier response to overwrite a newer one.

Missing error boundary : without an error boundary a single component crash can blank the whole page.

Large component (300+ lines) : components exceeding 300 lines should be split.

Individually these issues are not fatal, but accumulated they become maintenance headaches, especially when introduced by AI code generators.

How to Use

Run a single command at the project root: npx react-doctor@latest The tool scans the entire codebase, sorts findings by severity (errors before warnings), and returns an overall score out of 100. To see file and line details, add the --verbose flag: npx react-doctor@latest --verbose For a diff‑only scan that checks only files changed from the base branch, use --diff (often combined with --verbose) before committing: npx react-doctor@latest --verbose --diff A perfect score shows a celebratory animation.

Agent Skill Integration

Beyond a CLI, react‑doctor can be installed as a skill for AI coding assistants such as Claude Code, Cursor, Codex, or OpenCode. After installing with: npx react-doctor@latest install you can invoke it in the chat window with /react-doctor fix my code. The agent then runs the scan, selects relevant findings, applies a vetted fix recipe, and verifies the result, forming a closed loop of scan → triage → repair → validation.

This design lets one AI tool automatically correct the anti‑patterns commonly produced by another AI, and the fixing agent learns from each correction.

Team and CI Integration

For collaborative projects, react‑doctor offers a GitHub Actions integration that automatically reviews each pull request. It reports only newly introduced issues, avoiding a flood of legacy warnings.

Rules are configurable via doctor.config.ts; each rule can be explained with npx react-doctor@latest rules explain <rule>, allowing teams to enable or disable checks as needed.

react‑doctor complements ESLint by targeting React‑specific mental‑model violations that have become more prevalent with AI‑generated code. It is written in TypeScript, MIT‑licensed, and claims compatibility with Next.js, Vite, TanStack, React Native, and Expo.

Limitations: it is a static, rule‑based scanner, so it cannot catch business‑logic bugs; a high score does not guarantee perfect code. By default it reports crashes and usage data to Sentry, though this can be disabled.

Nevertheless, for developers who rely heavily on AI to write React components, having an automated gate before code reaches production can prevent costly runtime issues. A single npx command is a low‑cost safeguard worth trying.