react-doctor-cli-dev

v1.2.2

Published

7 days ago

React performance analyzer with static analysis, runtime profiling, rule engine, and dashboard upload

0High
0Medium
0Low

react react-performance react-performance-analyzer react-analyzer react-profiler static-analysis runtime-analysis web-vitals performance performance-analysis cli developer-tools

🩺 React Doctor

A TypeScript CLI for diagnosing React performance issues through static code analysis and real browser profiling.

React Doctor combines static analysis, runtime profiling, and a rule engine to connect what is happening in your React code with what actually happens in the browser.

Instead of reporting isolated warnings, React Doctor can correlate a code pattern with runtime evidence and turn it into a more actionable diagnosis.

Example: A component is missing React.memo() → runtime profiling shows it re-rendering repeatedly → React Doctor reports the relationship and recommends a targeted fix.

Note: React Doctor is not affiliated with react.doctor. They are separate, unrelated projects.

Why React Doctor?

React performance problems often require looking at multiple layers of an application.

A static analyzer can identify a suspicious code pattern. A browser profiler can show that something is actually happening at runtime. But connecting those two pieces of evidence is often left to the developer.

React Doctor brings them together:

        React source code
               │
               ▼
      ┌─────────────────┐
      │ Static Analysis │
      └────────┬────────┘
               │
       Code-level findings
               │
               ▼
      ┌─────────────────┐
      │ Runtime Profiler│
      └────────┬────────┘
               │
      Browser measurements
               │
               ▼
      ┌─────────────────┐
      │   Rule Engine   │
      └────────┬────────┘
               │
               ▼
      Correlated diagnosis
               │
               ▼
          Dashboard

This lets React Doctor move from:

"This component might have a performance problem."

to:

"This component has a performance-related code pattern, and runtime profiling shows evidence that it is affecting rendering."

🚀 Quick Start

1. Install

npm install -g react-doctor-cli-dev

2. Run a diagnostic

react-doctor full ./my-react-app --upload

React Doctor analyzes the project, profiles it in a real browser, combines the results, and opens the local dashboard.

3. Or use `npx`

npx react-doctor-cli-dev full ./my-react-app --upload

No global installation required.

✨ What React Doctor Does

🔍 Static Code Analysis

React Doctor parses JSX/TSX using Babel's AST tooling and looks for React-specific performance patterns.

Current detectors include:

Missing React.memo() opportunities
Missing useCallback() opportunities
Missing useMemo() opportunities
Prop drilling
Inline functions
Inline styles
Console statements
Large/complex components
Dead code

Static findings provide the code-level context needed by the rule engine.

⚡ Runtime Performance Profiling

React Doctor launches Chrome through Puppeteer and measures the application under controlled conditions.

It collects:

LCP — Largest Contentful Paint
FCP — First Contentful Paint
CLS — Cumulative Layout Shift
INP — Interaction to Next Paint
TTFB — Time to First Byte
React commit durations
Component re-render counts
Screenshots during page loading
Route-level performance information

You can also profile different environments using viewport, CPU, and network settings.

🧠 Correlation & Rule Engine

The rule engine combines static and runtime evidence.

React Doctor currently includes 25 rules covering different performance scenarios.

For example:

Static finding
└── ProductCard is not memoized
          +
Runtime evidence
└── ProductCard re-rendered 13 times
          ↓
Correlated suggestion
└── Excessive re-renders may be caused by
    missing memoization

Rules can use:

Static findings
Runtime measurements
Component information
Route information
Device information

Not every rule requires runtime evidence. Some findings are useful from static analysis alone, while correlation rules become more specific when runtime evidence is available.

📊 Dashboard

Use:

react-doctor full ./my-app --upload

The report is uploaded to the local dashboard and opened automatically.

Dashboard includes

| Section | Purpose | | --------------------- | --------------------------------------------------------------- | | Overview | Overall performance score, Web Vitals, routes, and top findings | | Web Vitals | Runtime metrics by route and device | | Code Issues | Static analysis findings with severity filtering | | Suggestions | Actionable recommendations from the rule engine | | History | Previous runs and performance trends |

The dashboard also provides:

Performance score
Route comparisons
Component re-render analysis
Screenshot filmstrip
Severity filters
Search and filtering
Historical performance tracking
Responsive interface
Dark theme

Screenshot: Add a real dashboard screenshot or short GIF here before publishing. For a developer tool, showing the actual result is more useful than another feature list.
docs/dashboard.png
![React Doctor dashboard](docs/dashboard.png)

🧩 How the Analysis Works

A full diagnostic runs through several stages:

1. Static Analysis

React Doctor scans JSX/TSX files and builds an AST-based representation of the source code.

Project
  ↓
JSX / TSX files
  ↓
Babel AST
  ↓
Static detectors
  ↓
Static findings

2. Runtime Profiling

The application is launched and inspected through a real browser.

React application
  ↓
Chrome / Puppeteer
  ↓
Routes + browser metrics
  ↓
Web Vitals + React runtime data

3. Rule Engine

Static findings and runtime measurements are evaluated together.

Static findings ─────┐
                     ├──► Rule Engine ───► Suggestions
Runtime evidence ────┘

4. Report Compilation

The results are merged into a structured report.

Static + Runtime + Rules
          ↓
    Final Report
          ↓
   JSON / Dashboard

📦 Installation

Global installation

Recommended when using React Doctor as a CLI:

npm install -g react-doctor-cli-dev

Verify the installation:

react-doctor --version

Using `npx`

npx react-doctor-cli-dev full ./my-app --upload

Local project installation

You can also install it as a development dependency:

npm install --save-dev react-doctor-cli-dev

Then add a script:

{
  "scripts": {
    "diagnose": "react-doctor full . --upload"
  }
}

Run:

npm run diagnose

⚙️ Requirements

Node.js: 18+
Google Chrome: installed locally
React project: a project containing package.json
Operating systems: Windows, macOS, and Linux

React Doctor uses Chrome for runtime profiling.

🎯 Usage

Full diagnostic

The full command runs the complete analysis pipeline.

react-doctor full ./my-react-app

With dashboard:

react-doctor full ./my-react-app --upload

Desktop and mobile:

react-doctor full ./my-react-app --desktop --mobile

CPU and network simulation:

react-doctor full ./my-react-app \
  --cpu 4 \
  --throttle slow4g

Full example:

react-doctor full ./my-react-app \
  --desktop \
  --mobile \
  --cpu 4 \
  --throttle slow4g \
  --upload

Static analysis

Run only the source-code analysis:

react-doctor analyze ./my-react-app

This is useful when you want fast feedback without launching the browser profiler.

Runtime profiling

Run the browser profiling stage independently:

react-doctor profile ./my-react-app

Mobile profiling:

react-doctor profile ./my-react-app --mobile

Network simulation:

react-doctor profile ./my-react-app \
  --mobile \
  --throttle 3g

Dashboard

Open the local dashboard:

react-doctor dashboard

Use a different port:

react-doctor dashboard --port 4000

Help

react-doctor --help

Command-specific help:

react-doctor full --help
react-doctor analyze --help
react-doctor profile --help
react-doctor dashboard --help

🖥️ CLI Options

`full`

| Option | Description | Default | | ----------------------- | -------------------------------------------------- | ----------------------------------- | | [projectPath] | React project path | Current directory | | --desktop | Profile desktop viewport (1280×720) | Enabled when no device is specified | | --mobile | Profile mobile viewport (390×844) | Disabled | | --cpu <rate> | CPU throttling:1, 4, or 6 | 1 | | --throttle <preset> | Network simulation:none, slow4g, or 3g | none | | --upload | Upload the report and open dashboard | false | | --api-url <url> | Backend API URL | http://localhost:3000 | | --api-key <key> | API key for backend authentication | Default key | | --no-banner | Disable startup banner | false |

`analyze`

| Option | Description | Default | | ----------------- | -------------------------------------- | ----------------- | | [projectPath] | React project path | Current directory | | --full | Include the extended analysis pipeline | false |

`profile`

| Option | Description | Default | | ----------------------- | -------------------- | ----------------- | | [projectPath] | React project path | Current directory | | --desktop | Use desktop viewport | true | | --mobile | Use mobile viewport | false | | --cpu <rate> | CPU throttling | 1 | | --throttle <preset> | Network simulation | none |

`dashboard`

| Option | Description | Default | | ----------------- | -------------- | -------- | | --port <port> | Dashboard port | 3000 |

For the complete and most up-to-date option list, use:

react-doctor <command> --help

🔐 Backend Authentication

When using --upload, reports are sent to the local React Doctor backend.

API key via CLI

react-doctor full ./app \
  --upload \
  --api-key my-secret-key

API key via environment variable

Linux/macOS:

export REACT_DOCTOR_API_KEY=my-secret-key
react-doctor full ./app --upload

Windows PowerShell:

$env:REACT_DOCTOR_API_KEY="my-secret-key"
react-doctor full ./app --upload

Security: Change the default API key before using the backend in a shared or publicly accessible environment.

📄 Reports

React Doctor generates structured reports locally.

Typical output:

.react-doctor/
└── finalreport.json

The JSON report contains the compiled analysis results and can be used for further processing or integration with other tooling.

When --upload is used, the report is also made available through the local dashboard.

🧪 Example

A simplified example of a full diagnostic:

  ┌─────────────────────────────────┐
  │       🩺  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

  ── Step 2 / 4 — Runtime Profiler ────
  ✔ Profiling complete
    / [desktop]  Score: 94/100
    / [mobile]   Score: 87/100

  ── Step 3 / 4 — Rule Engine ─────────
  ✔ Rule Engine complete — 14 suggestions
    ❌ 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
    ● Report saved ./.react-doctor/finalreport.json

  ── Dashboard ─────────────────────────
  ✔ Backend started successfully
  ✔ Report uploaded successfully
    Opening dashboard http://localhost:3000/report/1

  ✅ Full diagnostic finished.

🏗️ Architecture

React Doctor is organized as a pipeline:

┌──────────────────┐
│   React Project  │
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│   File Scanner   │
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│ Static Analyzer  │◄──── Babel AST
└────────┬─────────┘
         │
         ├──────────────────────┐
         │                      │
         ▼                      ▼
┌──────────────────┐   ┌──────────────────┐
│ Runtime Profiler │   │ Static Findings  │
│ Puppeteer/Chrome │   │                  │
└────────┬─────────┘   └────────┬─────────┘
         │                      │
         └──────────┬───────────┘
                    ▼
          ┌──────────────────┐
          │   Rule Engine    │
          │   25 rules       │
          └────────┬─────────┘
                   ▼
          ┌──────────────────┐
          │ Report Compiler  │
          └────────┬─────────┘
                   ▼
          ┌──────────────────┐
          │ JSON + Dashboard │
          └──────────────────┘

Repository structure

React_Doctor/
├── cli/                       # Command-line interface
│   ├── src/
│   │   ├── commands/
│   │   │   ├── full.ts
│   │   │   ├── analyze.ts
│   │   │   ├── profile.ts
│   │   │   └── dashboard.ts
│   │   ├── ui.ts
│   │   ├── uploader.ts
│   │   └── index.ts
│   └── package.json
│
├── backend/                   # Express API + SQLite
│   ├── src/
│   │   ├── routes/
│   │   ├── middleware/
│   │   ├── db.ts
│   │   └── index.ts
│   ├── public/
│   └── package.json
│
├── core/                      # Analysis engines
│   ├── static-ana/
│   ├── runtime/
│   ├── rule-engine/
│   └── report-compiler/
│
├── shared/                    # Shared types and schemas
├── package.json
├── tsconfig.json
├── README.md
└── LICENSE

🛠️ Development

Clone the repository

git clone https://github.com/softar-dev/React_Doctor.git
cd React_Doctor

Install dependencies

npm install

Build

npm run build

Available development scripts

| Command | Description | | ------------------------- | ---------------------------- | | npm run build | Build the CLI and backend | | npm run build:cli | Build the CLI | | npm run build:backend | Build the backend | | npm run dev:backend | Run the backend with nodemon |

Test the upload flow

Terminal 1:

cd backend
npm run dev

Terminal 2:

react-doctor full ./my-app \
  --upload \
  --api-key react-doctor-secret-key-change-this

🤝 Contributing

Contributions are welcome.

Before opening a pull request:

Fork the repository.
Create a feature or fix branch.
Make your changes.
Test the affected functionality.
Update documentation when necessary.
Open a pull request with a clear description.

Example branch names:

git checkout -b feat/custom-rule
git checkout -b fix/runtime-profile
git checkout -b docs/update-installation

Commit messages

Use Conventional Commits where possible:

feat: add new performance detector
fix: resolve runtime profiling issue
docs: update CLI reference
refactor: simplify rule evaluation

Reporting bugs

Open an issue and include:

Node.js version
Operating system
React version
React Doctor version
Command used
Steps to reproduce
Expected behavior
Actual behavior
Relevant logs or report output

For feature ideas and broader discussions, use GitHub Discussions.

🗺️ Roadmap

Potential future improvements include:

[ ] Next.js App Router support
[ ] Custom rule creation
[ ] GitHub Actions integration
[ ] Performance budgets and thresholds
[ ] Automated pull request comments
[ ] CI performance regression detection
[ ] Additional framework support

Roadmap items are subject to change as the project evolves.

Have an idea? Open a GitHub Discussion.

🔗 Links

Documentation: https://react-doctor-cli.web.app
npm: https://www.npmjs.com/package/react-doctor-cli-dev
GitHub: https://github.com/softar-dev/React_Doctor
Issues: https://github.com/softar-dev/React_Doctor/issues
Discussions: https://github.com/softar-dev/React_Doctor/discussions
Support: https://react-doctor-cli.web.app/support

🙏 Built With

React Doctor is built with:

📄 License

React Doctor is released under the MIT License.