> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/millionco/react-doctor/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start

> Get up and running with React Doctor in under 5 minutes

## Your First Scan

Navigate to your React project directory and run:

```bash theme={null}
npx -y react-doctor@latest .
```

<Steps>
  <Step title="React Doctor starts scanning">
    React Doctor will detect your framework, React version, and begin analyzing your codebase.

    ```bash theme={null}
    react-doctor v0.0.29

    Detected: Next.js 15.1.0, React 19.0.0
    Running lint checks...
    Running dead code detection...
    ```
  </Step>

  <Step title="Get your health score">
    Within seconds, you'll receive a 0-100 score and summary of issues.

    ```bash theme={null}
    ✓ Scan complete

    Score: 84 (Great)

    📊 Results:
      2 errors, 196 warnings
      80 unused files detected

    Run with --verbose to see file details
    ```
  </Step>

  <Step title="Review diagnostics">
    React Doctor will show a summary by category. Add `--verbose` to see specific files and line numbers.
  </Step>
</Steps>

## Understanding Your Score

React Doctor calculates a health score based on the severity and number of issues:

<CardGroup cols={3}>
  <Card title="75+ Great" icon="circle-check" color="#10b981">
    Your codebase is in excellent shape. Minor improvements may still be possible.
  </Card>

  <Card title="50-74 Needs Work" icon="circle-exclamation" color="#f59e0b">
    Some issues to address. Focus on errors first, then warnings.
  </Card>

  <Card title="<50 Critical" icon="circle-xmark" color="#ef4444">
    Significant problems detected. Prioritize fixing errors and major warnings.
  </Card>
</CardGroup>

<Note>
  Errors weigh more heavily than warnings in the score calculation.
</Note>

## Verbose Output

For detailed diagnostics with file paths and line numbers:

```bash theme={null}
npx -y react-doctor@latest . --verbose
```

<CodeGroup>
  ```bash Output theme={null}
  react-doctor v0.0.29

  Detected: Next.js 15.1.0, React 19.0.0
  Running lint checks...
  Running dead code detection...

  ✓ Scan complete

  Score: 84 (Great)

  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  📊 Errors (2)

  react-hooks/exhaustive-deps (2 files)
    src/components/Dashboard.tsx:45:3
    src/hooks/useData.ts:12:5

  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ⚠️  Warnings (196)

  react/no-unused-state (12 files)
    src/components/Form.tsx:20:3
    src/pages/Settings.tsx:35:5
    ...

  knip/exports (80 files)
    src/utils/legacy.ts
    src/components/OldButton.tsx
    ...

  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ```
</CodeGroup>

## Common Options

### Diff Mode

Scan only changed files compared to your main branch:

```bash theme={null}
npx -y react-doctor@latest . --diff main
```

<Info>
  Diff mode is perfect for CI/CD pipelines and large codebases. It dramatically speeds up scans by focusing only on what changed.
</Info>

### Score Only

Output just the numeric score (useful for scripting):

```bash theme={null}
npx -y react-doctor@latest . --score
```

<CodeGroup>
  ```bash Output theme={null}
  84
  ```
</CodeGroup>

### Skip Lint or Dead Code

Disable specific analysis types:

```bash theme={null}
# Skip linting, only run dead code detection
npx -y react-doctor@latest . --no-lint

# Skip dead code detection, only run linting
npx -y react-doctor@latest . --no-dead-code
```

### Silent Mode (No Prompts)

Skip all interactive prompts:

```bash theme={null}
npx -y react-doctor@latest . --yes
```

<Tip>
  Use `--yes` in CI/CD environments to prevent the build from hanging on prompts.
</Tip>

## Understanding Diagnostics

Each diagnostic includes:

* **Plugin/Rule**: The source of the diagnostic (e.g., `react-hooks/exhaustive-deps`, `knip/exports`)
* **Severity**: Either `error` or `warning`
* **File Path**: Location of the issue
* **Line & Column**: Exact position in the file
* **Message**: Description of the issue
* **Category**: Type of issue (performance, security, correctness, etc.)

### Rule Categories

React Doctor checks 60+ rules across these categories:

<CardGroup cols={2}>
  <Card title="State & Effects" icon="arrows-rotate">
    useState, useEffect, useCallback, useMemo usage
  </Card>

  <Card title="Performance" icon="gauge-high">
    Re-renders, bundle size, lazy loading
  </Card>

  <Card title="Security" icon="shield">
    XSS, dangerouslySetInnerHTML, unsafe patterns
  </Card>

  <Card title="Correctness" icon="check">
    Prop types, key props, fragment usage
  </Card>

  <Card title="Accessibility" icon="universal-access">
    ARIA attributes, semantic HTML, keyboard nav
  </Card>

  <Card title="Architecture" icon="sitemap">
    Dead code, unused exports, duplicate code
  </Card>

  <Card title="Next.js" icon="n">
    Image optimization, Link usage, metadata
  </Card>

  <Card title="React Native" icon="mobile">
    Platform-specific issues and optimizations
  </Card>
</CardGroup>

## Auto-Fix with Ami

React Doctor integrates with Ami, a coding agent built for React:

```bash theme={null}
npx -y react-doctor@latest . --fix
```

Ami will:

1. Read your React Doctor report
2. Understand your codebase
3. Fix issues one by one
4. Re-run the scan to verify improvements

<Info>
  Ami is free to use and supports all React Doctor diagnostics. Learn more at [ami.app](https://ami.app)
</Info>

## Next Steps

<CardGroup cols={2}>
  <Card title="Configuration" icon="gear" href="/usage/configuration">
    Customize rules and ignore patterns for your project
  </Card>

  <Card title="GitHub Actions" icon="github" href="/usage/github-actions">
    Set up React Doctor in your CI/CD pipeline
  </Card>

  <Card title="API Reference" icon="code" href="/api/diagnose">
    Use React Doctor programmatically in Node.js
  </Card>

  <Card title="Rules Reference" icon="book" href="/rules/overview">
    Explore all 60+ rules and their examples
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="React Doctor isn't detecting my framework">
    Make sure you're running the command from your project root where `package.json` is located.
  </Accordion>

  <Accordion title="Scan is taking too long">
    Try using `--diff` mode to scan only changed files, or use `--no-dead-code` to skip dead code detection.
  </Accordion>

  <Accordion title="Too many false positives">
    Create a `react-doctor.config.json` file to ignore specific rules or file patterns. See the [Configuration guide](/usage/configuration).
  </Accordion>

  <Accordion title="Getting TypeScript errors">
    React Doctor requires TypeScript 5.0.4 or higher. Update your TypeScript version:

    ```bash theme={null}
    npm install typescript@latest
    ```
  </Accordion>
</AccordionGroup>