react-doctor-cli-dev
v1.0.18
Published
React performance analyzer with static analysis, runtime profiling, rule engine, and dashboard upload
Maintainers
ozmaReadme
🩺 React Doctor
📋 Table of Contents
- 🚀 Quick Start
- ✨ Features
- 📊 Dashboard
- 📦 Installation
- 🎯 Usage
- ⚙️ Options Reference
- 📁 Project Structure
- 🧪 Example Output
- 🛠 Development
- 🤝 Contributing
- 📄 License
🚀 Quick Start
# Install globally
npm install -g react-doctor-cli-dev
# Run a full diagnostic with dashboard upload
react-doctor full ./my-react-app --upload
# The dashboard will open automatically at http://localhost:3000/report/1✨ Features
🔍 Static Code Analysis
- Detects performance anti-patterns (missing
memo,useCallback,useMemo) - Identifies prop drilling, inline styles, console logs in production
- Large component detection & dead code analysis
- JSX/TSX parsing with Babel AST traversal
- 9 specialized detectors for common React issues
⚡ Runtime Performance Profiling
- Real browser profiling via Puppeteer (Chrome)
- Core Web Vitals: LCP, FCP, CLS, INP, TTFB
- React commit timing & component render tracking
- Desktop (1280×720) & Mobile (390×844) viewport support
- CPU throttling (1×, 4×, 6×) & network simulation (3G, Slow 4G)
- Screenshot capture at key load moments
🧠 Intelligent Rule Engine
- 25+ built-in rules combining static + runtime insights
- Cross rules that fire only when both conditions are met
- Context-aware suggestions with severity levels (critical/warning/info)
- Affected component identification & fix recommendations
- Deduplicated suggestions across routes/devices
📊 Interactive Dashboard
- Performance Score with visual ring indicator
- Core Web Vitals displayed as color-coded cards
- Route comparison charts for LCP, FCP, TTFB
- Component re-render analysis with counts
- Screenshot filmstrip with timing labels
- Filterable issues & suggestions by severity
- Historical tracking with trend charts
- Zero configuration — auto-starts backend on first use
📈 Report Generation & Upload
- Structured JSON reports saved to
.react-doctor/ - Auto-start backend server when
--uploadis used - Secure API key authentication (
x-api-keyheader) - SQLite-backed database for historical tracking
- Screenshots uploaded as base64 to the backend
🛠 Developer Experience
- Zero-config CLI with intuitive flags
- Beautiful terminal output with spinners, colors, and badges
- Works with any React project (Vite, CRA, Next.js, etc.)
- Cross-platform: Windows, macOS, Linux
- Live dashboard with real-time data
📊 Dashboard
When you run react-doctor full ./my-app --upload, the dashboard automatically opens at http://localhost:3000/report/{id}.
What You'll See:
| Page | Content | | --------------------- | -------------------------------------------------------------------- | | Overview | Performance score, Web Vitals summary, routes table, top suggestions | | Web Vitals | Detailed metrics per route, component re-renders, screenshots | | Code Issues | All static issues with severity filters and pagination | | Suggestions | Actionable recommendations with code fixes | | History | Score trends and historical runs |
Dashboard Features:
- ✅ Responsive design — works on desktop and mobile
- ✅ Dark theme — easy on the eyes
- ✅ Interactive charts — visualize performance data
- ✅ Screenshot viewer — see what users see
- ✅ Filter & search — find issues quickly
📦 Installation
Via npm (Recommended)
# Install globally
npm install -g react-doctor-cli-dev
# Verify installation
react-doctor --versionVia npx (No Installation)
# Run without installing globally
npx react-doctor-cli-dev full ./my-app --upload🎯 Usage
Full Diagnostic (All-in-One)
# Basic usage (desktop only)
react-doctor full ./my-react-app
# Profile on mobile viewport
react-doctor full ./my-react-app --mobile
# Profile on both desktop + mobile
react-doctor full ./my-react-app --desktop --mobile
# Simulate slow Android device (4× CPU + Slow 4G)
react-doctor full ./my-react-app --cpu 4 --throttle slow4g
# Upload results to dashboard (RECOMMENDED)
react-doctor full ./my-react-app --uploadStatic Analysis Only (No Browser Required)
# Quick code scan
react-doctor analyze ./my-react-app
# Include runtime profiling in analysis
react-doctor analyze ./my-react-app --fullRuntime Profiling Only
# Profile desktop performance
react-doctor profile ./my-react-app
# Profile with network throttling
react-doctor profile ./my-react-app --throttle 3g⚙️ Options Reference
Global Options
| Flag | Description | Default |
| ----------------- | --------------------- | ------- |
| -V, --version | Output version number | — |
| -h, --help | Display help | — |
full Command Options
| Flag | Description | Default |
| ----------------------- | ---------------------------------------------------------- | --------------------------------------- |
| [projectPath] | Path to React project | process.cwd() |
| --desktop | Profile on desktop viewport (1280×720) | true (if no device flag) |
| --mobile | Profile on mobile viewport (390×844) | false |
| --cpu <rate> | CPU throttle:1 (real), 4 (mobile), 6 (low-end) | 1 |
| --throttle <preset> | Network:none, slow4g, 3g | none |
| --upload | Upload report to backend dashboard | false |
| --api-url <url> | Backend API URL | http://localhost:3000 |
| --api-key <key> | API key for backend auth | react-doctor-secret-key-change-this |
| --no-banner | Skip the startup banner | false |
analyze Command Options
| Flag | Description | Default |
| ----------------- | ----------------------------------- | ----------------- |
| [projectPath] | Path to React project | process.cwd() |
| --full | Include runtime + rules in analysis | false |
profile Command Options
| Flag | Description | Default |
| ---------------------------- | ---------------------- | ----------------- |
| [projectPath] | Path to React project | process.cwd() |
| --desktop / --mobile | Viewport to profile | desktop |
| --cpu / --throttle | Performance simulation | 1 / none |
dashboard Command Options
| Flag | Description | Default |
| ----------------- | ---------------------- | -------- |
| --port <port> | Port for the dashboard | 3000 |
🔐 Backend Authentication
When using --upload, secure your reports with an API key:
# Via CLI flag
react-doctor full ./app --upload --api-key my-secret-key
# Via environment variable
export REACT_DOCTOR_API_KEY=my-secret-key
react-doctor full ./app --uploadBackend expects: x-api-key: <your-key> header
Default key: react-doctor-secret-key-change-this (change for production!)
📁 Project Structure
React_Doctor/
├── cli/ # Command-line interface
│ ├── src/
│ │ ├── commands/ # full.ts, analyze.ts, profile.ts
│ │ ├── ui.ts # Terminal UI helpers (spinners, colors)
│ │ └── index.ts # CLI entry point
│ ├── dist/ # Compiled output
│ └── package.json
│
├── backend/ # Express API + SQLite dashboard
│ ├── src/
│ │ ├── routes/reports.ts # Upload & query endpoints
│ │ ├── middleware/auth.ts # API key validation
│ │ ├── db.ts # SQLite setup
│ │ └── index.ts # Server entry
│ ├── public/ # Built dashboard (served statically)
│ │ ├── index.html
│ │ ├── assets/
│ │ ├── favicon.svg
│ │ └── icons.svg
│ ├── data/ # SQLite database & screenshots
│ └── package.json
│
├── dashboard/ # React dashboard source
│ ├── src/
│ │ ├── pages.js
│ │ ├── api.js
│ │ ├── utils.js
│ │ └── main.js
│ ├── public/
│ └── package.json
│
├── core/ # Shared analysis engines
│ ├── static-ana/ # Babel-based code scanner
│ ├── runtime/ # Puppeteer profiler + metrics
│ ├── rule-engine/ # Suggestion generator
│ └── report-compiler/ # Final report merger
│
├── shared/ # TypeScript types & schemas
├── package.json # Root config
└── README.md🧪 Example Output
┌─────────────────────────────────┐
│ 🩺 React Doctor │
│ React Performance Analyzer │
└─────────────────────────────────┘
── Full Diagnostic ──────────────────
Project ./my-react-app
Device desktop + mobile
CPU 4x
Network slow4g
── Step 1 / 4 — Static Analysis ─────
✔ Static analysis complete — 42 files scanned
● Files analyzed 42
● Total issues 18
● Critical 2
● Warnings 5
● Info 11
● Health grade B
── Step 2 / 4 — Runtime Profiler ────
✔ Profiling complete — 6 route/device combination(s)
/ [desktop] Score: 94/100 Excellent
/ [mobile] Score: 87/100 Good
...
── Step 3 / 4 — Rule Engine ─────────
✔ Rule Engine complete — 14 suggestion(s) generated
❌ Unmemoized component is re-rendering excessively [ProductCard]
⚠️ React commits are exceeding 16ms budget
...
── Step 4 / 4 — Report Compiler ─────
✔ Final report compiled
· Overall score 91/100 Excellent
● Report saved ./.react-doctor/finalreport.json
── Uploading to Backend ─────────────
✔ Backend started successfully!
✔ Report uploaded successfully (2 screenshots)
📊 Opening dashboard: http://localhost:3000/report/1
✅ Full diagnostic finished.🛠 Development
Prerequisites
- Node.js 18+
- npm 10+
- Git
Setup
# Clone the repository
git clone https://github.com/softar-dev/React_Doctor.git
cd React_Doctor
# Install dependencies
npm install
# Build all packages
npm run buildScripts
| Command | Description |
| --------------------------- | ------------------------------- |
| npm run build | Build CLI + backend + dashboard |
| npm run build:cli | Build CLI only |
| npm run build:backend | Build backend only |
| npm run build:dashboard | Build dashboard only |
| npm run dev:cli | Run CLI in watch mode |
| npm run dev:backend | Run backend with nodemon |
| npm run dev:dashboard | Run dashboard with Vite |
Testing the Upload Flow Locally
# Terminal 1: Start backend manually
cd backend && npm run dev
# Terminal 2: Run CLI with upload
npx ts-node cli/src/index.ts full ./my-app \
--upload \
--api-key react-doctor-secret-key-change-this \
--api-url http://localhost:3000🤝 Contributing
Contributions are welcome! Here's how to get started:
- Fork the repository
- Create a feature branch:
git checkout -b feat/amazing-feature - Commit your changes:
git commit -m 'feat: add amazing feature' - Push to the branch:
git push origin feat/amazing-feature - Open a Pull Request
Guidelines
- Follow existing code style (Prettier + ESLint)
- Add tests for new functionality
- Update documentation for user-facing changes
- Use Conventional Commits for commit messages
Reporting Issues
- Use the GitHub Issues tab
- Include: Node version, OS, React version, and steps to reproduce
- Attach logs or screenshots when helpful
📄 License
Distributed under the ISC License. See LICENSE for more information.
🙏 Acknowledgments
- Puppeteer — Headless Chrome automation
- Babel — JavaScript compiler & AST parsing
- Express — Backend framework
- better-sqlite3 — Fast SQLite bindings
- Chart.js — Dashboard charts
- Vite — Dashboard build tool
- Chalk — Terminal string styling
- Commander — CLI framework
📬 Support
- 🐛 Bug Reports: GitHub Issues
- 💬 Discussions: GitHub Discussions
- ✉️ Contact: Open an issue or reach out via GitHub
Made with ❤️ Helping React developers build faster, cleaner, smarter apps. 🚀
📊 Quick Reference
# Install
npm install -g react-doctor-cli-dev
# Full diagnostic with dashboard
react-doctor full ./my-app --upload
# Full diagnostic with all options
react-doctor full ./my-app --desktop --mobile --cpu 4 --throttle slow4g --upload
# Static analysis only
react-doctor analyze ./my-app
# Runtime profiling only
react-doctor profile ./my-app --mobile
# Open dashboard
react-doctor dashboard
# Version
react-doctor --version
# Help
react-doctor --help