🧠 npm-doctor-ai

Your project's doctor. Fast, offline-first dependency health analyzer for Node.js projects.

npm audit + depcheck + bundle analyzer — combined into one lightning-fast tool. No API keys. No internet required. Just answers.

⚡ Quick Start

npx npm-doctor-ai

That's it. Run it in any Node.js / React / Next.js project.

Sample output:

  ⚛️ React project detected

  🧠 Health Score: 61/100 🟠

  ╭────────────────────────────╮
  │  📦 Total Dependencies: 94 │
  │  ❌ Unused: 23             │
  │  ⚠️  Risky: 5              │
  │  🚀 Suggestions: 8         │
  ╰────────────────────────────╯

  💡 Suggestions:
    ✗ moment → moment is 4.2MB → Switch to dayjs (2KB, same API)
    💡 lodash → You only use lodash for a few functions → Replace with native JS

  🔮 Potential Improvements:
    - Remove 23 deps → -345KB bundle
    - Faster install time (~2.3s)

  👉 Run: npx npm-doctor-ai fix

🔥 What It Does

| Feature | Description | |---------|-------------| | 🧠 Health Score | 0–100 score based on dependency quality | | ❌ Unused Detection | Finds packages in package.json not imported anywhere | | ⚠️ Risk Analysis | Deprecated, compromised, typosquatting, install scripts | | 🚀 Smart Suggestions | Package-specific actionable advice (not generic) | | 🔄 Duplicate Detection | Finds overlapping dependencies | | 🎯 Framework Detection | Auto-detects Next.js, React, Vue, Angular, Express | | 🔮 Impact Metrics | Bundle size savings and install time improvements | | 💀 Dead Package Detector | Finds abandoned/unmaintained packages | | 🚀 Startup Time Impact | Estimates ms delay from heavy dependencies |

📦 Commands

Default Scan

npx npm-doctor-ai

Full analysis: health score, unused deps, risks, smart suggestions, and impact metrics.

npx npm-doctor-ai --simple     # Beginner-friendly output
npx npm-doctor-ai --json       # Machine-readable JSON output
npx npm-doctor-ai --ignore-tests  # Skip test files

Fix Mode

npx npm-doctor-ai fix          # Interactively remove unused deps
npx npm-doctor-ai fix --dry    # Preview what would be fixed

--dry output:

  ✏️ Fix Preview:

  ✔ Will remove:
    - monaco-editor
    - tailwindcss-animate

  ✔ Will improve score:
    83 → 91

Quick Scan

npx npm-doctor-ai quick

Fast scan — only unused dependencies.

Explain a Package

npx npm-doctor-ai explain moment         # Technical explanation
npx npm-doctor-ai explain moment --eli5  # Simple "Explain Like I'm 5" mode

--eli5 output:

  moment is old and heavy.
  It makes your app slower.
  Use dayjs instead (same features, smaller size).

Why Is This Installed?

npx npm-doctor-ai why react-dom

  react-dom is required by:
    → next
    → react

Share Report

npx npm-doctor-ai share

Generates a shareable summary for LinkedIn / Twitter:

  🧠 My Project Health Score: 83/100 🟡

  ❌ 6 unused packages (you're wasting space)
  ⚠️ 1 risky dependency

  👉 Run: npx npm-doctor-ai fix

  #npm #javascript #webdev #react

Scary Mode

npx npm-doctor-ai scare

  ⚠️ This project has 3 dependencies that could expose sensitive data.
  Run audit to fix immediately.

Before vs After Comparison

npx npm-doctor-ai compare

  Before:
    - 94 deps
    - 1.4MB bundle

  After fix:
    - 61 deps
    - 915KB bundle

  🔥 Improvement: -35% size
     Score: 61 → 89

Dependency Story

npx npm-doctor-ai story

  Your project depends on 94 packages.

  Top chain:
    react → scheduler → loose-envify → object-assign

  ⚠️ 8 layers deep dependencies detected

Impact Metrics

npx npm-doctor-ai impact

  🔮 Potential Improvements:

    - Remove 6 deps → -120KB bundle
    - Faster install time (~0.8s)

  ⚡ Heavy packages:
    - moment (~4.2MB)
    - webpack (~15MB)

Framework Detection

npx npm-doctor-ai framework

  ⚛️ React project detected

  💡 Suggestions:
    - Remove prop-types if using TypeScript
    - Use React.lazy() for code splitting heavy components

Dead Package Detector

npx npm-doctor-ai dead

  💀 Dead / Abandoned Packages:

  ⚠️ Package xyz:
    - Last updated: 4 years ago
    - No repository or homepage
    👉 Consider replacing

Startup Time Impact

npx npm-doctor-ai startup

  🚀 Estimated startup delay:
  +220ms due to heavy dependencies

  Top offenders:
    - electron: +250ms
    - webpack: +120ms
    - moment: +50ms

Badge Generator

npx npm-doctor-ai badge

Outputs a Shields.io badge to add to your README:

![Health Score](https://img.shields.io/badge/health-82-green)

CI Mode

npx npm-doctor-ai ci

Exits with code 1 if high-risk packages or too many unused deps are found:

  🚨 CI FAILED — Project is NOT safe to deploy

  ⚠️ 1 high-risk dependency detected
  ❌ 6 unused dependencies (waste + risk)

  👉 Fix now: npx npm-doctor-ai fix

Perfect for GitHub Actions, GitLab CI, etc.

🎛️ All Flags

| Flag | Applies To | Description | |------|-----------|-------------| | --json | Most commands | Output results as JSON | | --ignore-tests | Scan, fix, quick | Skip test files during scanning | | --simple | Default scan | Beginner-friendly simplified output | | --dry | fix | Preview changes without modifying anything | | --eli5 | explain | Simple plain-English explanation |

🏗️ How It Works

1. Parses all .js, .ts, .jsx, .tsx files using fast-glob
2. Extracts require() and import statements via regex
3. Compares against package.json dependencies
4. Scores your project using a rule-based engine
5. Reports findings with beautiful CLI output

No AI APIs. No network calls. Pure static analysis.

🤝 Contributing

PRs welcome! This project is designed to be modular and extensible.

npm-doctor-ai/
├── bin/cli.js           # CLI entry point (all commands registered)
├── core/
│   ├── scan.js          # Main orchestrator + all command runners
│   ├── unused.js        # Unused dependency detector
│   ├── risk.js          # Risk analysis engine
│   ├── optimize.js      # Optimization suggestions
│   ├── score.js         # Health score calculator
│   ├── share.js         # Shareable report generator
│   ├── why.js           # Dependency chain lookup
│   ├── explain.js       # ELI5 package explainer
│   ├── scare.js         # Security scare report
│   ├── compare.js       # Before/after comparison
│   ├── story.js         # Dependency chain story
│   ├── impact.js        # Impact metrics calculator
│   ├── framework.js     # Framework detection + suggestions
│   ├── dead.js          # Dead/abandoned package detector
│   ├── startup.js       # Startup time impact estimator
│   ├── badge.js         # README badge generator
│   └── suggestions.js   # Smart per-package suggestions
├── utils/
│   ├── logger.js        # CLI output formatting
│   └── file.js          # File system utilities
└── package.json

📄 License

MIT © npm-doctor-ai