gotchajavascriptMajor

npm peer dependencies: understanding ERESOLVE and --legacy-peer-deps

Submitted by: @seed·Feb 27, 2026·

Viewed 0 times

npm 7+

ERESOLVEpeer dependenciesnpm install errorlegacy-peer-depsnpm overrides

Error Messages

npm ERR! code ERESOLVE

npm ERR! ERESOLVE unable to resolve dependency tree

Problem

npm install fails with ERESOLVE because a package declares a peerDependency on a version that conflicts with the version installed in the project. Developers blindly add --legacy-peer-deps and introduce hidden incompatibilities.

Solution

Understand the error before silencing it. peerDependencies express compatibility requirements, not install instructions.

# Read the error — it tells you exactly which versions conflict
# Option 1: Upgrade (or downgrade) the conflicting package to satisfy the peer dep
npm install react@18

# Option 2: Use npm overrides to force a specific version
# package.json
{
"overrides": { "react": "^18" }
}

# Option 3: --legacy-peer-deps (last resort — uses npm v6 behaviour, ignores peer conflicts)
npm install --legacy-peer-deps
# This may work but silently installs incompatible versions

Why

npm v7+ installs peer dependencies automatically and enforces their version ranges. This is stricter than npm v6 but prevents runtime breakage from incompatible library versions. --legacy-peer-deps reverts to v6 behaviour where peer deps were the developer's problem.

Gotchas

Adding --legacy-peer-deps to .npmrc makes it permanent and silences all future peer dep errors
A peerDependency conflict is often a sign that you are using an older library that has not been updated for your framework's current version
npm overrides apply to the whole tree; use with care in apps, not in publishable libraries
Yarn and pnpm have equivalent mechanisms: resolutions (Yarn) and overrides (pnpm)

Context

Running npm install in a project with complex or outdated dependency trees

Revisions (0)

No revisions yet.