Skip to main content

​
Basic Usage

Run React Doctor in your project directory: 
npx react-doctor@latest
Scan a specific directory: 
npx react-doctor@latest ./my-project

​
Commands

​
Main Command

The main command scans your React codebase for issues. 
react-doctor [directory] [options]
​
directory
string
default:"."
Project directory to scan

​
Fix Command

Open Ami to automatically fix detected issues. 
react-doctor fix [directory]

​
Install Ami Command

Install Ami and open it to fix issues. 
react-doctor install-ami [directory]

​
Options

​
Linting Options

​
--lint
boolean
default:"true"
Enable linting checks using oxlint
​
--no-lint
boolean
Skip linting checks
Example: 
npx react-doctor --no-lint

​
Dead Code Detection

​
--dead-code
boolean
default:"true"
Enable dead code detection using Knip
​
--no-dead-code
boolean
Skip dead code detection
Example: 
npx react-doctor --no-dead-code

​
Output Options

​
--verbose
boolean
default:"false"
Show file details per rule, including line numbers for each diagnostic
​
--score
boolean
default:"false"
Output only the score (0-100) without diagnostics
Examples: 
# Show detailed file information
npx react-doctor --verbose

# Get just the score
npx react-doctor --score

​
Project Selection

​
--project
string
Select workspace project(s) to scan. Comma-separated for multiple projects.
​
-y, --yes
boolean
default:"false"
Skip prompts and scan all workspace projects
Examples: 
# Scan a specific project in a monorepo
npx react-doctor --project web

# Scan multiple projects
npx react-doctor --project web,mobile

# Skip all prompts
npx react-doctor -y

​
Diff Mode

​
--diff [base]
boolean | string
Scan only files changed vs base branch. If no base branch is specified, compares against uncommitted changes or the default base branch.
Examples: 
# Scan only changed files vs main
npx react-doctor --diff main

# Auto-detect changes
npx react-doctor --diff
Diff mode automatically disables dead code detection since it requires a full codebase scan.

​
Error Handling

​
--fail-on
string
default:"none"
Exit with error code on diagnostics. Valid values: error, warning, none
Examples: 
# Fail only on errors
npx react-doctor --fail-on error

# Fail on warnings and errors
npx react-doctor --fail-on warning

# Never fail (useful for CI reporting)
npx react-doctor --fail-on none

​
Telemetry

​
--offline
boolean
default:"false"
Skip telemetry. Telemetry is anonymous, not stored, and only used to calculate your health score.
Example: 
npx react-doctor --offline

​
Ami Integration

​
--fix
boolean
default:"false"
Open Ami to auto-fix all detected issues
​
--no-ami
boolean
default:"false"
Skip Ami-related prompts
Examples: 
# Scan and immediately open Ami to fix
npx react-doctor --fix

# Disable Ami prompts in CI
npx react-doctor --no-ami

​
Version

​
-v, --version
boolean
Display the version number
Example: 
react-doctor --version

​
Common Workflows

# Basic scan with default settings
npx react-doctor@latest

​
Exit Codes

React Doctor uses exit codes to indicate scan results:
  • 0: Success (or no failures based on --fail-on setting)
  • 1: Diagnostics detected that match the --fail-on level
Example CI usage: 
npx react-doctor --fail-on error
if [ $? -eq 0 ]; then
  echo "No errors found"
else
  echo "Errors detected, failing build"
  exit 1
fi

​
Environment Variables

React Doctor detects automated environments and adjusts behavior accordingly:
  • CI: Continuous Integration
  • CLAUDECODE: Claude Code
  • CURSOR_AGENT: Cursor Agent
  • OPENCODE: OpenCode
  • AMI: Ami environment
When these are set, React Doctor:
  • Skips interactive prompts
  • Scans all workspace projects automatically
  • Disables Ami installation prompts

​
Output

​
Standard Output

A typical scan produces:
  1. Project Detection: Framework, React version, TypeScript/JavaScript
  2. Diagnostics: Grouped by rule with severity, message, and help text
  3. Summary: Health score, error/warning counts, affected files
  4. Full Report: Diagnostics written to /tmp/react-doctor-{uuid}/

​
Verbose Output

With --verbose, each diagnostic includes:
  • File paths
  • Line numbers for each occurrence
  • Detailed context
Example: 
  ✗ useEffect dependencies array is missing dependencies (2)
    Ensure all dependencies are included in the array
    src/components/Header.tsx: 45, 67
    src/pages/Dashboard.tsx: 123

​
Score-Only Output

With --score, outputs a single number (0-100): 
$ npx react-doctor --score
87

Build docs developers (and LLMs) love

Get started for freeTalk to us