Quick Start
Add React Doctor to your GitHub Actions workflow:
.github/workflows/react-doctor.yml
name: React Doctor
on:
pull_request:
push:
branches: [main]
jobs:
diagnose:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: millionco/react-doctor@latest
Project directory to scan
Show file details per rule. Enabled by default in GitHub Actions for better visibility.
Workspace project(s) to scan. Comma-separated for multiple projects.
Base branch for diff mode (e.g., main). Only files changed vs this branch are scanned.
GitHub token for posting PR comments. When set on pull_request events, findings are posted as a PR comment.
Exit with error code on diagnostics: error, warning, none
Node.js version to use for the scan
Action Outputs
Health score (0-100). Available even if the scan fails.
- uses: millionco/react-doctor@latest
id: doctor
- name: Check score
run: |
echo "Health score: ${{ steps.doctor.outputs.score }}"
Common Workflows
Basic CI Check
Fail the build if errors are detected:
name: CI
on:
pull_request:
push:
branches: [main]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: millionco/react-doctor@latest
with:
fail-on: error
.github/workflows/pr-check.yml
name: PR Check
on:
pull_request:
jobs:
diagnose:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: millionco/react-doctor@latest
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
fail-on: error
The action automatically updates existing comments rather than creating new ones on each run.
Diff Mode for PRs
Scan only changed files in pull requests:
.github/workflows/pr-diff.yml
name: PR Diff Check
on:
pull_request:
jobs:
diagnose:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0 # Required for diff mode
- uses: millionco/react-doctor@latest
with:
diff: main
github-token: ${{ secrets.GITHUB_TOKEN }}
verbose: true
Monorepo Support
Scan specific workspace projects:
.github/workflows/monorepo.yml
name: Monorepo Check
on:
pull_request:
push:
branches: [main]
jobs:
scan-web:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: millionco/react-doctor@latest
with:
project: web,mobile
fail-on: error
Score Tracking
Track health scores over time:
.github/workflows/score.yml
name: Health Score
on:
push:
branches: [main]
jobs:
track-score:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: millionco/react-doctor@latest
id: doctor
with:
fail-on: none
- name: Log score
run: |
echo "Current health score: ${{ steps.doctor.outputs.score }}"
- name: Comment on commit
uses: peter-evans/commit-comment@v3
with:
body: |
## React Doctor Score: ${{ steps.doctor.outputs.score }}/100
Multiple Node Versions
Test with different Node.js versions:
.github/workflows/matrix.yml
name: Matrix Test
on:
pull_request:
jobs:
test:
runs-on: ubuntu-latest
strategy:
matrix:
node-version: [18, 20, 22]
steps:
- uses: actions/checkout@v4
- uses: millionco/react-doctor@latest
with:
node-version: ${{ matrix.node-version }}
fail-on: error
Advanced Configuration
Conditional Execution
Run only on specific file changes:
.github/workflows/conditional.yml
name: Conditional Check
on:
pull_request:
paths:
- 'src/**/*.tsx'
- 'src/**/*.ts'
- 'package.json'
jobs:
diagnose:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: millionco/react-doctor@latest
with:
fail-on: error
Custom Directory
Scan a specific subdirectory:
.github/workflows/subdirectory.yml
name: Subdirectory Scan
on:
pull_request:
jobs:
diagnose:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: millionco/react-doctor@latest
with:
directory: ./packages/web
fail-on: error
Combine with Other Actions
Integrate with testing and linting:
.github/workflows/full-ci.yml
name: Full CI
on:
pull_request:
push:
branches: [main]
jobs:
quality:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
- name: Install dependencies
run: npm ci
- name: Run tests
run: npm test
- name: Run React Doctor
uses: millionco/react-doctor@latest
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
fail-on: error
- name: Build
run: npm run build
github-token on pull requests, React Doctor posts a comment with this format:
✗ useEffect dependencies array is missing dependencies (2)
Ensure all dependencies are included in the array
src/components/Header.tsx: 45, 67
⚠ Avoid using array index as key (1)
Use a unique identifier instead
src/pages/List.tsx: 89
┌──────────────────────────────────────────┐
│ ┌─────┐ │
│ │ • • │ │
│ │ ─ │ │
│ └─────┘ │
│ React Doctor (www.react.doctor) │
│ │
│ 78 / 100 Needs Improvement │
│ │
│ ███████████████████████████░░░░░░░░░░ │
│ │
│ ✗ 5 errors ⚠ 12 warnings across 8/142 │
│ files in 2.3s │
└──────────────────────────────────────────┘
The comment is automatically updated on subsequent runs rather than creating duplicates.
Troubleshooting
Action Fails with “No React dependency found”
Ensure React is listed in your package.json:
{
"dependencies": {
"react": "^18.0.0"
}
}
Diff mode not detecting changes
Use fetch-depth: 0 to fetch full git history:
- uses: actions/checkout@v4
with:
fetch-depth: 0
permissions:
pull-requests: write
contents: read
Best Practices
- Use diff mode for PRs: Scan only changed files to reduce CI time
- Enable PR comments: Provide immediate feedback to developers
- Set fail-on appropriately: Use
error for CI, none for reporting
- Track scores: Monitor codebase health over time
- Combine with existing checks: Integrate into existing CI workflows