npm ERESOLVE after adding a package: upgrade the peer together, not --legacy-peer-deps

Symptom

npm i react-dom@19 in a react@18.3.1 project fails with npm error code ERESOLVE / Could not resolve dependency: peer react@"^19.3.1" from react-dom@19.3.1.

Environment and tested versions

Debian GNU/Linux 13 (trixie) x86_64, node 20.19.2, npm 11.21.1

• node 20.19.2
• npm 11.21.1
• react / react-dom 18.3.1 -> 19.3.1

Client used in the test: Tested with the npm CLI directly.

Root cause

The new package declares a peer dependency on a version the project doesn't have; npm 7+ enforces peer dependencies.

Fix steps

1. Upgrade the peer and the package together to compatible versions, e.g. npm i react@19 react-dom@19.
2. Check with npm ls.
3. Use --legacy-peer-deps only as a last resort: it installs anyway and leaves the mismatch in place.

Verification

Tested 31 Oct 2026 in a throwaway directory on a Linux box (fake credentials only). Before (A) and after the fix:

A: npm i react-dom@19 -> npm error code ERESOLVE ... exit=1
B: npm i react@19 react-dom@19 -> found 0 vulnerabilities
   npm ls -> react@19.3.1 deduped; tree OK

Sources

• https://docs.npmjs.com/cli/v11/using-npm/config (legacy-peer-deps, strict-peer-deps)