# React Doctor

Diagnose React codebase health. React Doctor scans for security, performance, correctness, and architecture issues, then outputs a 0-100 score with actionable diagnostics.

Note: dead-code detection was removed in v0.2. For dead-code analysis, run `npx knip` directly.

# Markdown Docs

Use these markdown docs when you need product, setup, configuration, CI, or API guidance.

- [Docs sitemap](/docs/sitemap.md): structured table of contents for every doc page.

## Overview

- [What Is React Doctor?](/docs/overview/what-is-react-doctor.md): A deterministic scanner for React security and performance issues.
- [Quickstart](/docs/overview/quickstart.md): Find security and performance issues locally, then check every pull request.
- [CLI to CI](/docs/getting-started/install-for-coding-agents.md): Run React Doctor locally, then gate security and performance in CI.
- [How to Fix Issues](/docs/getting-started/how-to-fix-issues.md): Work through diagnostics and suppressions safely.

## CI & PRs

- [GitHub Actions Setup](/docs/ci-and-prs/github-actions-setup.md): Add the Action and scan every pull request.
- [Updating CI](/docs/ci-and-prs/updating-ci.md): Get updates automatically, or bump a pinned Action and scanner.
- [Other CI Providers](/docs/ci-and-prs/other-ci-providers.md): Run the CLI on GitLab, CircleCI, Jenkins, or Buildkite.
- [Migrating to CI v2](/docs/ci-and-prs/migrating-to-ci-v2.md): Upgrade the GitHub Action from v1 to v2.

## Configuration

- [Config Files](/docs/configuration/config-files.md): Configure rules, categories, surfaces, and scan behavior.
- [ESLint & oxlint Plugins](/docs/configuration/eslint-and-oxlint-plugins.md): Run React Doctor rules inside existing lint tools.

## Reference

- [CLI Reference](/docs/reference/cli-reference.md): Commands and flags for the React Doctor CLI.
- [GitHub Action Reference](/docs/reference/github-action-reference.md): Inputs, outputs, and permissions for the Action.
- [Node.js API](/docs/reference/node-api.md): Use React Doctor from scripts and services.

## Community

- [Changelog](/docs/community/changelog.md): Release notes for the React Doctor CLI, pulled from the GitHub changelog.

## Legal

- [Modified MIT License](/docs/legal/license.md): React Doctor is free for most uses. AI training and large-scale commercial use require a written license from Million Software, Inc.
- [Terms of Service](/docs/legal/terms.md): Terms governing access to and use of React Doctor and Million Software services.
- [Privacy Policy](/docs/legal/privacy.md): Privacy information for React Doctor and Million Software services.
- [Data Use](/docs/legal/data-use.md): How React Doctor handles GitHub repository data during pull request analysis.
- [Security](/docs/legal/security.md): How React Doctor handles your code and data, and how to report security issues.

## Company

- [Support](/docs/company/support.md): Get support for React Doctor.

# Prompts

Fetchable, agent-ready markdown prompts. Edit at the source and every consumer (GitHub Actions, coding agents, CLIs) picks up the new version on its next fetch.

- [Prompts sitemap](/prompts/sitemap.md): structured table of contents for every prompt.
- [Prompts index](/prompts.md): all prompt categories with links.
- [Bot playbook](/prompts/react-doctor-bot.md): daily CI triage for the React Doctor GitHub Actions bot.
- [Agent playbook](/prompts/react-doctor-agent.md): local triage for coding agents (Cursor, Claude Code, Codex). Same loop, edits the working tree.
- [Rule index](/prompts/rules.md): every engine rule grouped by category, with links to each per-rule prompt (validation + fix).
- Individual rule: `/prompts/rules/{plugin}/{rule}.md` (e.g. [`/prompts/rules/effect/no-derived-state.md`](/prompts/rules/effect/no-derived-state.md)).

# CLI Quick Reference

Run this at your project root:

```bash
npx react-doctor@latest
```

Use `--verbose` to see affected files and line numbers:

```bash
npx react-doctor@latest --verbose
```

Use `--diff [base]` to scan only files changed vs a base branch. On the default branch, scans uncommitted working-tree changes; on a feature branch, scans changes vs the base.

```bash
npx react-doctor@latest --verbose --diff
```

Use `--score` to output only the numeric score:

```bash
npx react-doctor@latest --score
```

Use `--json` for a single structured JSON report:

```bash
npx react-doctor@latest --json | jq '.summary'
```

Use `--category <category>` to show one diagnostic category. Repeat the flag to include more categories:

```bash
npx react-doctor@latest --category performance --category accessibility
```

Category filters narrow normal output, verbose output, workspace summaries, handoff prompts, and JSON reports. They do not change which files React Doctor scans. Unknown categories fail before report output.

Use `-y` to skip prompts in non-interactive environments like CI or coding agents:

```bash
npx react-doctor@latest -y
```

Use `--staged` for pre-commit hooks:

```bash
npx react-doctor@latest --staged
```

Use `--annotations` to emit GitHub Actions annotations:

```bash
npx react-doctor@latest --annotations
```

Use `--fail-on <level>` to control exit codes (`error`, `warning`, `none`):

```bash
npx react-doctor@latest --fail-on error
```

Use `--offline` to skip the score API and the share URL:

```bash
npx react-doctor@latest --offline
```

Install the skill into your coding agent:

```bash
npx react-doctor@latest install
```