npm-doctor-live 🔍

A Node.js CLI tool that monitors npm install processes in real-time and provides intelligent diagnostics when installations hang or fail.

🎯 Motivation

Developers frequently experience npm install hanging with zero visibility into what's happening. npm-doctor-live solves that problem by wrapping npm install, monitoring it in real-time, and showing you exactly which package is being processed at any moment.

✨ Features

• ✅ Real-time Monitoring: Track npm install progress with live package name updates
• ✅ Live Spinner: Beautiful ora spinner showing current package, status icon, and elapsed time
• ✅ Timeout Detection: Automatically detect when installation is stuck (configurable, default: 30s)
• ✅ Smart Diagnostics: Identify common issues and suggest fixes:
  • ✅ node-gyp build failures → suggests build tools
  • ✅ Large binary downloads (puppeteer/playwright) → notes this is normal
  • ✅ Network issues → suggests cache clean and registry check
• ✅ Color-coded Status: Cyan (downloading), Yellow (resolving), Green (complete), Red (stuck)
• ✅ Verbose Mode: Detailed npm output logging for debugging
• ✅ Graceful Cleanup: Proper Ctrl+C handling and process cleanup

🚀 Installation

npx npm-doctor-live install [package-name]

📖 Usage

Install all dependencies with monitoring

npx npm-doctor-live install

Install a specific package

npx npm-doctor-live install express

Custom timeout (default: 30 seconds)

npx npm-doctor-live install --timeout 60

Verbose mode for debugging

npx npm-doctor-live install --verbose

Combined options

npx npm-doctor-live install lodash --timeout 60 --verbose

New in Phase 3: Enhanced Options

JSON output for scripting

npx npm-doctor-live install express --json

Debug mode with detailed logging

npx npm-doctor-live install --debug

Save log to custom file

npx npm-doctor-live install --save-log ./install.log

Silent mode (minimal output)

npx npm-doctor-live install --silent

Skip installation summary

npx npm-doctor-live install --no-summary

🛠️ Development

Setup

# Clone the repository
git clone https://github.com/Aniketxmishra/npm-doctor.git
cd npm-doctor-live

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run in development mode
npm run dev -- install express

Project Structure

npm-doctor-live/
├── src/
│   ├── index.ts          # CLI entry point
│   ├── types.ts          # TypeScript type definitions
│   ├── monitor.ts        # (Phase 2) Process monitoring
│   ├── parser.ts         # (Phase 2) Output parsing
│   ├── ui.ts             # (Phase 3) UI components
│   └── diagnostics.ts    # (Phase 4) Smart diagnostics
├── dist/                 # Compiled JavaScript
├── package.json
└── tsconfig.json

🔬 Technical Details

• TypeScript: Full type safety
• Cross-platform: Windows, macOS, Linux
• npm Support: Versions 7, 8, 9, 10
• Dependencies:
  • chalk - Terminal colors
  • cli-progress - Progress bars
  • ora - Spinners
  • commander - CLI argument parsing

⚙️ Configuration File

Create .npm-doctor-liverc.json in your project root or home directory:

{
  "timeout": 60,
  "showSummary": true,
  "debug": false,
  "silent": false,
  "suggestions": {
    "showNodeGyp": true,
    "showNetworkFixes": true
  }
}

Configuration priority: CLI arguments > config file > defaults

📋 Development Roadmap

• [x] Phase 1: Project structure and TypeScript setup
• [x] Phase 2: Process monitoring and output parsing with timeout detection
• [x] Phase 3: Production features (summaries, logging, config files)
  • [x] Installation summary with metrics
  • [x] Enhanced CLI options (--debug, --json, --silent, --save-log, --no-summary)
  • [x] Configuration file support
  • [x] Auto-save logs on failure
• [ ] Phase 4: Additional diagnostics (peer dependencies, cache issues)
• [ ] Phase 5: Unit tests and npm package publication

📄 License

MIT License - feel free to use this tool in your projects!

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Built with ❤️ to make npm install debugging easier