Who react-doctor is for#
Team adding React quality gate to CI
Adds react-doctor to CI with `--diff main` so every PR only fails when it introduces new React health regressions, not for pre-existing baseline issues.
Developer pre-PR self-review
Runs `npx react-doctor@latest` before submitting a PR to get a prioritized issue list without waiting for reviewer feedback.
Tech lead with AI coding tools
Runs `npx react-doctor@latest install` into their Cursor setup so AI-generated code gets validated against React best practices before it is committed.
Agency scoping a React refactor
Does a quick health check on a client's inherited codebase to scope a React refactor engagement before committing to a timeline.
Solo developer on Next.js project
Monitors health score over time as a lightweight code quality signal while building a Next.js app without a full SonarQube setup.
The problem it solves#
Coding agents and junior developers routinely introduce React anti-patterns: effects that run too often, components with too many responsibilities, missing accessibility attributes, and performance-killing render patterns. Standard ESLint configurations catch syntax-level issues but miss architectural patterns that only become visible when you look at the full component tree. Manual code reviews for React best practices are time-consuming, inconsistent, and do not run automatically in CI.
How it solves it#
0-100 health score with severity breakdown
Outputs a 0-100 health score with severity breakdown: 75+ is great, 50-74 needs work, under 50 is critical
Five diagnostic surfaces
Covers five diagnostic surfaces: state and effects, performance, architecture, security, and accessibility
Automatic framework detection
Detects your framework (Next.js, Vite, React Native) and adjusts its rule set automatically
GitHub Actions integration with PR comments
GitHub Actions composite action ships in the repo with sticky PR comments, configurable fail-on threshold, and a score output for downstream steps
--diff mode for incremental CI
`--diff <base>` mode scopes diagnostics to changed files only, catching new regressions without requiring a clean baseline
Agent install mode prevents future violations
`npx react-doctor@latest install` writes best-practice rules into your coding agent's config files so it stops writing the bad patterns in the first place
Strengths and trade-offs#
Strengths
- Zero configuration, one commandZero configuration required; works at the project root with one npx command
- Drop-in CI integrationCI integration is drop-in: a composite GitHub Actions workflow ships in the repo with documented fail-on thresholds
- Closes detection-to-prevention loop for agentsThe agent-install mode puts rules where agents read them, closing the loop between detection and prevention
- MIT licensed and actively maintainedMIT licensed and actively maintained
Trade-offs
- -React-only, no other frameworksFocused exclusively on React; not useful for Vue, Svelte, Angular, or other frontend frameworks
- -Dead-code detection removed in v0.2Dead-code detection was removed in v0.2 (knip integration dropped); run `npx knip` separately if you need it
- -Heuristic scores, some false positivesHealth score thresholds are heuristics, not definitive quality guarantees; context-dependent rules may flag valid patterns as issues
react-doctor vs alternatives#
react-doctor is an MIT-licensed React quality scanner for teams using coding agents to generate or modify React code.
vs CodeRabbit: CodeRabbit reviews pull requests across hosted Git platforms and IDE or CLI workflows, with AI comments and paid team plans. react-doctor is narrower and local-first: it runs through the npx react-doctor latest command, scores React code from 0 to 100, and flags issues across state, effects, performance, architecture, security, and accessibility.
vs Snyk Code: Snyk Code focuses on static application security testing and security findings across supported languages. react-doctor should not replace a security scanner; it is better for React-specific regressions, framework-aware rules, agent instruction installation, and PR score gates in Next.js, Vite, and React Native projects.
vs SonarQube Cloud: SonarQube Cloud is broader code quality and security governance for many languages and repositories. react-doctor is better when the immediate problem is AI-generated React code that violates framework patterns, but SonarQube is still the stronger choice for organization-wide quality gates, centralized reporting, and cross-language policy.
Install and self-host#
Setup from the root of a React project:
npx react-doctor@latest install
Run an audit locally:
npx react-doctor@latestWhat it's built on#
- Languages
- JavaScriptTypeScript
- Frameworks
- React
FAQ#
Will react-doctor break my CI if my current score is low?
Only if you configure it to. By default, --fail-on error exits non-zero when error-severity rules fire. Set --fail-on none for advisory mode that reports findings but never blocks a build.
Does it work with React Native?
Yes. React Doctor detects your project framework and applies React Native-specific rules automatically. Framework detection is based on your installed packages and project structure.
What does the `install` command do?
npx react-doctor@latest install writes React best-practice rules into the config files for your detected coding agents (Claude Code, Cursor, Codex, and 50+ others). This teaches the agent the rules upfront so it avoids writing code that react-doctor would flag.
Similar open-source tools#
Grit
Automate code migrations at scale using a pattern-matching DSL
deer-flow
Build super agents with DeerFlow's powerful framework
page-agent
AI-powered GUI Agent for your website
iroh
Connect devices seamlessly without relying on the cloud.
orca
The ultimate IDE for coding agents
CLI-Anything
Empower AI agents with agent-native CLIs