Victor's room

Executive Summary & Root Cause Analysis: The error npm ERR! code ERESOLVE (unable to resolve dependency tree) occurs when running npm install or npm ci in npm v7 and newer. Starting with npm v7, the package manager enforces strict automatic peer dependency resolution by default. When two packages in your project declare incompatible version ranges for a shared peer dependency (for example, a UI library expecting React 17 while your project uses React 18), npm halts installation rather than silently installing mismatched versions. Common triggers include: (1) upgrading a major framework version before third-party plugins update their peerDependencies, (2) stale package-lock.json files from older npm versions, and (3) conflicting transitive dependencies across plugins.

Step 1: Quick Fix – Bypass Strict Peer Checks via CLI Flags

If you need to unblock your local build or install a package whose peer dependency warning is benign (such as a minor version mismatch in React or TypeScript), pass the --legacy-peer-deps flag. This restores npm v6 behavior by ignoring peer dependency conflicts during resolution.

# Install packages while ignoring peer dependency conflicts (Recommended quick fix)
npm install --legacy-peer-deps

# Or when installing a specific package:
npm install <package-name> --legacy-peer-deps

# Alternative: Force installation even with conflicting dependencies (Use cautiously)
npm install --force

Note: Prefer --legacy-peer-deps over --force. While --legacy-peer-deps skips installing conflicting peer packages, --force fetches and installs duplicate or incompatible versions alongside each other, which can bloat your bundle or introduce runtime bugs.

Step 2: Project Configuration – Persist Resolution Rules in .npmrc or package.json

To prevent teammates and CI/CD pipelines from hitting the same ERESOLVE error without needing custom CLI flags, configure resolution rules directly in your repository.

# Option A: Add legacy-peer-deps to your project-level .npmrc file
echo "legacy-peer-deps=true" >> .npmrc

# Then run standard install or CI commands cleanly:
npm install

If you want to keep strict peer checking enabled while pinning a specific conflicting transitive dependency to a compatible version, use the overrides field in package.json (supported in npm v8.3+):

{
  "name": "your-project",
  "dependencies": {
    "some-plugin": "^2.0.0"
  },
  "overrides": {
    "some-plugin": {
      "conflicting-peer-pkg": "^18.2.0"
    }
  }
}

Step 3: Clean Dependency Resolution – Inspect and Align Package Versions

For production applications, the cleanest long-term fix is identifying the exact conflicting package and upgrading or aligning its version:

1. Inspect the dependency tree to locate the conflict:

   # List installed versions of the conflicting peer package
   npm ls <conflicting-package-name>
   
   # Check for newer compatible releases of your outdated dependencies
   npm outdated

2. Clear stale lockfiles and npm cache before reinstalling:

   # Remove node_modules and lockfile
   rm -rf node_modules package-lock.json
   
   # Verify and clean npm cache
   npm cache verify
   
   # Update the conflicting package to a compatible release and reinstall
   npm install <outdated-package>@latest

Verification & Testing Steps

Confirm that dependencies install cleanly without ERESOLVE errors and that your application builds and passes tests as expected:

# Test clean CI-style installation if package-lock.json was updated
npm ci

# Verify zero unmet peer dependency issues in the tree
npm ls --depth=0

# Run your build or test suite to ensure runtime compatibility
npm run build && npm test

Summary Comparison Table

Resolution Method	How It Works	Team & CI/CD Persistence	Best Used For
--legacy-peer-deps	Skips automatic peer dependency installation (npm v6 behavior)	Temporary (CLI flag only)	Quick local testing & unblocking
.npmrc (legacy-peer-deps=true)	Applies legacy peer resolution across all repo installs	High (Committed to Git)	Teams working with unmaintained plugins
overrides in package.json	Forces a specific version for nested/peer dependencies	High (Committed to Git)	Targeted fixes without disabling all checks
Upgrade & Regenerate Lockfile	Aligns packages to mutually compatible versions	Permanent	Production apps prioritizing stability