react-doctor
CLI Toolmillionco/react-doctor
Scan React codebases and output a health score with actionable diagnostics.
Overview
React Doctor is a CLI tool that scans React codebases to produce a 0-100 health score with actionable diagnostics. It checks state, performance, accessibility, security, and dead code, supporting Next.js, Vite, and React Native. It can be integrated into CI/CD pipelines and coding agents to enforce best practices.
README Preview
\n \n \n \n\n\n[](https://npmjs.com/package/react-doctor)\n[](https://npmjs.com/package/react-doctor)\n\nYour agent writes bad React, this catches it.\n\nOne command scans your codebase and outputs a **0 to 100 health score** with actionable diagnostics.\n\nWorks with Next.js, Vite, and React Native.\n\n### [See it in action →](https://react.doctor)\n\n## Install\n\nRun this at your project root:\n\n```bash\nnpx -y react-doctor@latest .\n```\n\nYou'll get a score (75+ Great, 50 to 74 Needs work, under 50 Critical) and a list of issues across state & effects, performance, architecture, security, accessibility, and dead code. Rules toggle automatically based on your framework and React version.\n\nhttps://github.com/user-attachments/assets/07cc88d9-9589-44c3-aa73-5d603cb1c570\n\n## Install for your coding agent\n\nTeach your coding agent React best practices so it stops writing the bad code in the first place.\n\n```bash\nnpx -y react-doctor@latest install\n```\n\nYou'll be prompted to pick which detected agents to install for. Pass `--yes` to skip prompts.\n\nWorks with Claude Code, Cursor, Codex, OpenCode, and 50+ other agents.\n\n## GitHub Actions\n\nA composite action ships with this repository. Drop it into `.github/workflows/react-doctor.yml`:\n\n```yaml\nname: React Doctor\n\non:\n pull_request:\n push:\n branches: [main]\n\npermissions:\n contents: read\n pull-requests: write # required to post PR comments\n\njobs:\n react-doctor:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v5\n with:\n fetch-depth: 0 # required for `diff`\n - uses: millionco/react-doctor@main\n with:\n diff: main\n github-token: ${{ secrets.GITHUB_TOKEN }}\n```\n\nWhen `github-token` is set on `pull_request` events, findings are posted (and updated) as a PR comment. The action also exposes a `score` output (0–100) you can use in subsequent steps.\n\n**Inputs:** `directory`, `verbose`, `project`, `diff`, `githFAQ (4)
TroubleshootingWhy does react-doctor's unused-file rule flag almost every file as unused on Windows?
This is a known path separator mismatch bug in deslop-js on Windows (backslash vs forward slash causing import graph edges to be dropped). The fix has been merged in deslop-js main (PR #16) and will be included in the next react-doctor release. Until then, as a temporary workaround, run react-doctor inside WSL or a Unix environment, or manually apply the patch from millionco/deslop-js#16.
TroubleshootingHow to select all items in the interactive CLI checklist?
Press the 'a' key to toggle select all options in the current list. This keyboard shortcut works in the interactive interface.
securityIs using @main branch in GitHub Actions workflows a security risk, and how can I pin actions safely?
Yes, referencing actions by mutable branches like @main allows supply-chain attacks if the upstream repository is compromised. Instead, pin to a specific release tag (e.g., @v1.2.3) or a full commit SHA. For react-doctor, use uses: millionco/react-doctor@<tag-or-sha> rather than @main.
TroubleshootingHow to fix "Cannot find package 'oxc-parser'" error when running npx react-doctor@latest?
This bug affects react-doctor@0.2.14, where oxc-parser is mistakenly listed under devDependencies instead of dependencies. Workaround: manually install oxc-parser in your project (npm install oxc-parser or pnpm add oxc-parser) before running react-doctor. Alternatively, downgrade to react-doctor@0.2.3 or earlier. Track issue #629 for the permanent fix.