Dependency Conflict Resolver

Untangle and resolve package dependency conflicts.

When to Use

• Package installation fails
• Peer dependency warnings
• "Module not found" errors
• Duplicate package warnings
• Version mismatch errors
• Lock file conflicts

Common Error Types

1. Peer Dependency Conflicts

npm WARN ERESOLVE unable to resolve dependency tree
npm WARN peer react@"^17.0.0" from package-a@1.0.0
npm WARN   peer react@"^18.0.0" from package-b@2.0.0

Cause: Two packages require different versions of the same peer dependency.

2. Version Conflicts

npm ERR! Could not resolve dependency:
npm ERR! peer typescript@">=4.0 <5.0" from some-package@1.0.0
npm ERR! node_modules/some-package
npm ERR!   some-package@"^1.0.0" from the root project

Cause: Package requires a version range you're not using.

3. Duplicate Packages

warning "package-a" has unmet peer dependency "lodash@^4.0.0".
warning "package-b" has incorrect peer dependency "lodash@^3.0.0".

Cause: Multiple versions of the same package installed.

Diagnostic Commands

NPM

# See dependency tree
npm ls

# Find specific package
npm ls react

# Find why package is installed
npm why lodash

# Check for outdated packages
npm outdated

# Audit for issues
npm audit

Yarn

# See dependency tree
yarn list

# Find specific package
yarn why react

# Check for duplicates
yarn dedupe --check

# Interactive upgrade
yarn upgrade-interactive

PNPM

# See dependency tree
pnpm ls

# Find specific package
pnpm why react

# List all versions of a package
pnpm ls --depth Infinity | grep lodash

Resolution Strategies

Strategy 1: Update to Compatible Versions

# Find what versions are needed
npm ls react --all

# Update packages that need newer version
npm update package-a package-b

# Or install specific compatible version
npm install react@18.2.0

Strategy 2: Override/Resolution

NPM (package.json):

{
  "overrides": {
    "react": "18.2.0",
    "package-a": {
      "lodash": "4.17.21"
    }
  }
}

Yarn (package.json):

{
  "resolutions": {
    "react": "18.2.0",
    "**/lodash": "4.17.21"
  }
}

PNPM (package.json):

{
  "pnpm": {
    "overrides": {
      "react": "18.2.0",
      "lodash@^3.0.0": "4.17.21"
    }
  }
}

Strategy 3: Force Install (Last Resort)

# NPM - force through conflicts
npm install --legacy-peer-deps

# Or with force flag
npm install --force

# Yarn
yarn install --ignore-peer-deps

Warning: This can lead to runtime errors. Use only when you've verified compatibility.

Strategy 4: Deduplicate

# NPM
npm dedupe

# Yarn
yarn dedupe

# PNPM (automatic, but can force)
pnpm install

Debugging Deep Conflicts

Trace the Dependency Chain

# NPM - full tree
npm ls --all > deps.txt

# Find the conflict path
grep -B5 "lodash@3" deps.txt

Example output:

├─┬ package-a@1.0.0
│ └── lodash@4.17.21
├─┬ package-b@2.0.0
│ └─┬ old-dependency@0.5.0
│   └── lodash@3.10.1  <- Conflict source

Check Package Requirements

# View package.json of installed package
cat node_modules/package-name/package.json | jq '.peerDependencies'

# Or use npm view
npm view package-name peerDependencies

Common Scenarios

Scenario 1: React Version Mismatch

npm WARN react-dom@18.2.0 requires react@^18.2.0, but react@17.0.2 is installed

Solution:

# Upgrade React
npm install react@18 react-dom@18

# Or if you need React 17
npm install react-dom@17

Scenario 2: TypeScript Version

error TS2307: Cannot find module '@types/node' or its corresponding type declarations.

Solution:

# Check TypeScript version
npx tsc --version

# Install compatible types
npm install -D @types/node@ts$(npx tsc --version | cut -d' ' -f2 | cut -d'.' -f1-2)

# Or specific version
npm install -D @types/node@20

Scenario 3: Native Module Rebuild

npm ERR! node-pre-gyp ERR! build error

Solution:

# Rebuild native modules
npm rebuild

# Or for specific package
npm rebuild bcrypt

# Clear cache and reinstall
rm -rf node_modules package-lock.json
npm install

Scenario 4: Workspace Conflicts (Monorepo)

error Workspaces can only be enabled in private projects.

Solution in package.json:

{
  "private": true,
  "workspaces": [
    "packages/*"
  ]
}

Lock File Conflicts

Git Merge Conflicts in Lock Files

# Don't manually resolve - regenerate
git checkout --theirs package-lock.json
npm install

# Or
rm package-lock.json
npm install

Lock File Out of Sync

# NPM
rm package-lock.json
npm install

# Yarn
rm yarn.lock
yarn install

# PNPM
rm pnpm-lock.yaml
pnpm install

Prevention

Pin Versions

{
  "dependencies": {
    "lodash": "4.17.21",     // Exact version
    "react": "^18.2.0",      // Minor updates OK
    "express": "~4.18.0"     // Patch updates only
  }
}

Use Lock Files

# Always commit lock files
git add package-lock.json  # or yarn.lock, pnpm-lock.yaml

# CI should use ci command
npm ci  # instead of npm install

Regular Updates

# Check for updates regularly
npm outdated

# Update incrementally
npm update

# Use tools like renovate/dependabot

AI-Assisted Resolution

Help me resolve this dependency conflict:

**Error message:**

[paste full error]

**Current package.json dependencies:**
```json
[paste dependencies]

What I've tried:

• [list attempts]

Please:

1. Explain what's conflicting
2. Show the dependency chain causing it
3. Suggest the safest resolution
4. Note any potential runtime issues

## Best Practices

1. **Read the full error** - It usually tells you what's wrong
2. **Check compatibility** - Before installing new packages
3. **Use lock files** - For reproducible installs
4. **Update regularly** - Small updates are easier than big jumps
5. **Test after resolving** - Conflicts can cause runtime issues
6. **Document workarounds** - Future you will thank you
7. **Avoid force** - Unless you understand the consequences