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

``bash


Run directly with npx (recommended)

npx dep-why react

Or install globally

npm install -g dep-why
`

Usage

$3

`bash


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
`

$3

`bash


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:

react@18.2.0 (1 instance)
└─ (direct dependency in package.json)

react@17.0.2 (2 instances)
├─ react-datepicker@4.8.0
└─ some-ui-library@2.1.0

react@16.14.0 (1 instance)
└─ legacy-component@1.0.0

💡 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
react-datepicker@4.8.0 requires react@17.0.2. A newer version may support react@18.2.0

⚡ Update legacy-component to a newer version
legacy-component@1.0.0 requires react@16.14.0. A newer version may support react@18.2.0

💭 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
`

$3

`bash
$ npx dep-why --all

📦 Found 5 packages with multiple versions:

• react
• lodash
• tslib
• semver
• debug

Run dep-why 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) | ✅ | ✅ | ✅ |

$3

`bash


npm why output (confusing)

$ npm why react
react@17.0.2
node_modules/react-datepicker/node_modules/react
react@"^17.0.0" from react-datepicker@4.8.0
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:

react@18.2.0 (1 instance)
└─ (direct dependency in package.json)

react@17.0.2 (1 instance)
└─ react-datepicker@4.8.0

💡 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

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

`typescript
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

$3

`bash
npm dedupe
`

Attempts to reduce duplication by moving packages up the tree.

$3

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

`bash
npm outdated
npm update
`

$3

Force a specific version across all dependencies:

`json
{
"overrides": {
"react": "18.2.0"
}
}
`

$3

`json
{
"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