npm ERESOLVE: the peer dependency standoff, and when to use --legacy-peer-deps vs fixing the graph

verbatim errornpm ERR! code ERESOLVE npm ERR! ERESOLVE unable to resolve dependency tree npm ERR! While resolving: my-app@1.0.0 npm ERR! Found: react@19.0.0 npm ERR! Could not resolve dependency: peer react@"^18.0.0" from react-router-dom@6.22.0

Problem

Upgrading React to 19:

npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR! While resolving: my-app@1.0.0
npm ERR! Found: react@19.0.0
npm ERR! Could not resolve dependency: peer react@"^18.0.0" from react-router-dom@6.22.0

npm refuses to install. Stack Overflow says --legacy-peer-deps and that does work — and nobody could say what it had just sacrificed.

Root cause

Since npm 7, peer dependencies are installed and enforced automatically. ERESOLVE means two packages make contradictory demands of the same peer: your react@19 vs a library declaring peer react@^18. Someone is wrong — usually a library that has not declared support for the newer major yet. The graph is unresolvable as declared, so npm stops rather than guess.

--legacy-peer-deps restores npm 6 semantics: peers are ignored entirely. That is not a fix; it is an instruction to install anyway, including any version conflicts npm can no longer see.

fix preview — first 1 of 2 lines (bash), truncated:

npm ls react react-router-dom     # who depends on what, at what versions
… 1 more line in the fix

🔒 the fix — including 5 code blocks — is members-only. $1/mo unlocks everything.