Debug: npm/yarn install fails with ERESOLVE or peer dependency errors

npm install fails with ERESOLVE, peer dependency conflicts, or 'Could not resolve dependency' errors.

Fix npm dependency resolution failures:

# 1. Understand the error
npm install 2>&1 | head -50
# Look for: ERESOLVE, peer dep, conflicting versions

# 2. See the full dependency tree
npm ls --all 2>&1 | grep -i 'ERR\|invalid\|missing'
npm ls <package-name>  # Show where a specific package is used

# 3. Quick fixes (try in order):

# Fix A: Force install (skips peer dep checks)
npm install --legacy-peer-deps
# npm 7+ is stricter than npm 6 about peer deps
# This flag restores npm 6 behavior

# Fix B: Force resolution
npm install --force
# Accepts any version conflicts (use with caution)

# Fix C: Clean install
rm -rf node_modules package-lock.json
npm install
# Sometimes lock file gets corrupted

# Fix D: Deduplicate
npm dedupe
# Reduces duplicate packages in tree

# 4. For specific conflicts:
# If package A needs react@17 and package B needs react@18:

# Option 1: Update the conflicting package
npm install package-a@latest  # Might support newer react

# Option 2: Use npm overrides (npm 8.3+)
# package.json:
{
  "overrides": {
    "package-a": {
      "react": "$react"  # Use root react version
    }
  }
}

# For yarn:
# package.json:
{
  "resolutions": {
    "react": "18.2.0"
  }
}

# 5. Nuclear option: fresh start
rm -rf node_modules package-lock.json
npm cache clean --force
npm install

Prevention:

• Pin major versions in package.json
• Update dependencies regularly (small increments)
• Use npm outdated to check for updates
• Test with npm ci in CI (uses lock file exactly)

npm 7+ enforces peer dependency requirements strictly (npm 6 just warned). Most ERESOLVE errors come from packages that haven't updated their peer deps for newer versions.

JavaScript project dependency management