React Doctor

React Doctor (Million)

Run an automated audit of a React/Next.js codebase and turn the diagnostics into a prioritized fix list.

Quick Start

In this repository, use the repo-owned first-party helper from the repo root:

bun run react-doctor:first-party -- --full --offline --fail-on none

The human guide is docs/guides/development/react-doctor.md. It is the source of truth for configured ignores, advisory blocking behavior, and PR wording.

Workflow

1. Confirm you are at the project root (the directory containing package.json).
2. Read docs/guides/development/react-doctor.md.
3. Run the configured repo audit:
   • bun run react-doctor:first-party -- --full --offline --fail-on none
4. Convert the output into an actionable plan:
   • Capture the overall score (0-100).
   • List the top issues by severity (errors first).
   • For each issue, include the file path, what to change, and why it matters.
5. Fix issues starting with highest severity and highest leverage (security/correctness before perf polish).
6. Re-run the configured audit and confirm the result for apps and packages.
7. Report results honestly as the configured first-party audit. Do not imply that ignored rules were fixed.

Next.js App Router Notes

When triaging results for Next.js App Router projects, prioritize:

• Async Client Components (often accidental "use client" leaks)
• Client-side fetching for server-owned data (prefer Server Components / Route Handlers)
• Missing or incorrect metadata exports
• Server Actions without auth checks
• Excessive client bundle growth (barrel imports, large dependencies)

Expected Output

When reporting results back, format as:

React Doctor score: <number>/100

Top findings:

- <severity> <short title> -- <path(s)>
- ...

Fix plan:

1. <most important fix> (why)
2. ...

Verification:

- bun run react-doctor:first-party -- --full --offline --fail-on none

Triggers

• User mentions react-doctor, React Doctor, or millionco/react-doctor
• User asks for a React or Next.js audit covering performance, correctness, security, or architecture
• User wants a focused code health pass on suspicious React patterns or bundle growth

Checklist

• Read docs/guides/development/react-doctor.md
• bun run react-doctor:first-party -- --full --offline --fail-on none
• Findings summarized with file paths
• Fixes applied in severity order
• Audit re-run and configured-audit score verified
• Known ignores and advisory blocking behavior reported honestly