dep-why

Understand why you have multiple versions of a package - human-friendly dependency analysis

Problem

"Why do I have 3 versions of React in node_modules?"

npm why output is confusing. npm ls is overwhelming. You just want to know why and how to fix it.

Solution

dep-why shows you exactly why you have multiple versions with clear dependency chains and actionable suggestions.

Features

• Human-readable output - Clear dependency chains, not nested JSON
• Grouped by version - See all paths to each version at once
• Actionable suggestions - Dedupe, update, or override recommendations
• Find all duplicates - Scan entire project with --all
• Color-coded - Newest version green, oldest red
• Works everywhere - npm, yarn, pnpm projects

Installation

# Run directly with npx (recommended)
npx dep-why react

# Or install globally
npm install -g dep-why

Usage

Analyze a Specific Package

# Why do I have multiple versions of lodash?
npx dep-why lodash

# Analyze in a different directory
npx dep-why react --path ./my-project

# Output as JSON
npx dep-why lodash --json

Find All Duplicates

# List all packages with multiple versions
npx dep-why --all

# Or just run without arguments
npx dep-why

Example Output

📦 Why you have 3 versions of react:

[email protected] (1 instance)
  └─ (direct dependency in package.json)

[email protected] (2 instances)
  ├─ [email protected]
  └─ [email protected]

[email protected] (1 instance)
  └─ [email protected]

💡 Suggestions:

🔥 Run npm dedupe to reduce duplicates
   npm dedupe attempts to simplify the dependency tree by moving packages up

⚡ Update react-datepicker to a newer version
   [email protected] requires [email protected]. A newer version may support [email protected]

⚡ Update legacy-component to a newer version
   [email protected] requires [email protected]. A newer version may support [email protected]

💭 Use npm overrides to force a single version
   Add to package.json:
   "overrides": {
     "react": "18.2.0"
   }

──────────────────────────────────────────────────
Solved dependency hell? Consider supporting:
☕ https://buymeacoffee.com/willzhangfly

Find All Duplicates

$ npx dep-why --all

📦 Found 5 packages with multiple versions:

  • react
  • lodash
  • tslib
  • semver
  • debug

Run `dep-why <package-name>` to see details for a specific package.

Comparison with Alternatives

| Feature | dep-why | npm why | npm ls | yarn why | |---------|---------|---------|--------|----------| | Human-readable | ✅ | ❌ | ❌ | ⚠️ | | Grouped by version | ✅ | ❌ | ❌ | ❌ | | Actionable suggestions | ✅ | ❌ | ❌ | ❌ | | Find all duplicates | ✅ | ❌ | ⚠️ | ❌ | | Color-coded output | ✅ | ❌ | ❌ | ⚠️ | | Works with any PM | ✅ | npm only | npm only | yarn only | | No install needed | ✅ (npx) | ✅ | ✅ | ✅ |

Why Not npm why?

# npm why output (confusing)
$ npm why react
[email protected]
node_modules/react-datepicker/node_modules/react
  react@"^17.0.0" from [email protected]
  node_modules/react-datepicker
    react-datepicker@"^4.8.0" from the root project

# dep-why output (clear)
$ npx dep-why react
📦 Why you have 2 versions of react:

[email protected] (1 instance)
  └─ (direct dependency in package.json)

[email protected] (1 instance)
  └─ [email protected]

💡 Suggestions:
🔥 Run npm dedupe to reduce duplicates
⚡ Update react-datepicker to a newer version

CLI Options

Usage: dep-why [options] [package]

Arguments:
  package              Package name to analyze

Options:
  -p, --path <dir>     Project directory (default: current directory)
  --json               Output results as JSON
  --all                Show all packages with duplicates
  -V, --version        Output version number
  -h, --help           Display help

Programmatic Usage

import { analyzePackage, findDuplicates } from 'dep-why';

// Analyze a specific package
const result = analyzePackage('react', '/path/to/project');
console.log(result.versions);
console.log(result.suggestions);

// Find all duplicates
const duplicates = findDuplicates('/path/to/project');
console.log(duplicates); // ['react', 'lodash', ...]

How It Works

1. Runs npm ls --json to get the full dependency tree
2. Finds all instances of the target package
3. Groups by version and traces dependency chains
4. Generates actionable suggestions based on patterns

Common Solutions

1. npm dedupe

npm dedupe

Attempts to reduce duplication by moving packages up the tree.

2. Update Dependencies

Check if parent packages have newer versions that support your desired version:

npm outdated
npm update <package-name>

3. Use npm overrides (npm 8.3+)

Force a specific version across all dependencies:

{
  "overrides": {
    "react": "18.2.0"
  }
}

4. Use yarn resolutions

{
  "resolutions": {
    "react": "18.2.0"
  }
}

Requirements

• Node.js 18.0.0 or higher
• npm, yarn, or pnpm project with node_modules

Support

This project is maintained in my free time. If it helped you escape dependency hell, I'd really appreciate your support:

• ⭐ Star the repo—it helps others discover this tool
• 📢 Share with your team or on social media
• 🐛 Report bugs or suggest features
• ☕ Buy me a coffee if you'd like to support development

Thank you to everyone who has contributed, shared feedback, or helped spread the word!

License

MIT

Made with ❤️ for cleaner node_modules