npm ERR! ERESOLVE" only when installing with --omit=dev - peer dep conflict hidden in the dev tree

TL;DR

Fix the peer conflict in your devDependencies - the full install was masking it. Run a normal npm install and read the tree, find which dev packages disagree on a peer, align their versions, then verify npm install --omit=dev exits cleanly. With dev deps present npm can sometimes find a satisfying layout; without them the conflict has nowhere to hide.

Error

"npm ERR! ERESOLVE" only when installing with --omit=dev  -  peer dep conflict hidden in the dev tree

Steps

1. Reproduce both ways. Run npm install (full) and then npm install --omit=dev in a clean checkout. Expected: the full install succeeds and the omit-dev install fails with ERESOLVE, confirming the conflict lives in the dev tree.
2. Read the ERESOLVE output. It names the conflicting packages and the peer ranges involved. Expected: you can identify two dev packages (or a dev package and a root dep) demanding incompatible versions of the same peer.
3. Inspect the tree. Run npm ls [peer-package] to see who depends on what. Expected: a clear picture of which dev dependency pulls the conflicting peer range.
4. Align the versions. Upgrade or pin the dev packages so their peer requirements agree - usually bumping the older dev tool to a release that supports the newer peer. Expected: npm ls shows a single consistent version.
5. Verify the production install. Run npm install --omit=dev again. Expected: exit code 0, no ERESOLVE. Also run npm install --omit=dev --dry-run in CI to lock it in.

Use this when

• ERESOLVE shows up only with --omit=dev or --production
• CI fails to install while local development installs fine
• A dev tool (test runner, bundler plugin) disagrees with a root dependency on a peer version
• You need to find which dev package owns a hidden peer conflict

Not for this skill when

• ERESOLVE happens on a full install too - then the conflict is in the main tree, fix it there
• The error is EOVERRIDE or ELSPROBLEMS - different error families
• You actually want to keep the conflicting dev setup - use overrides deliberately instead

Variant phrasings

• npm ERESOLVE could not resolve dependency tree with omit dev
• peer dependency conflict only in production install
• npm install works locally but fails in CI with ERESOLVE
• devDependency peer conflict hidden from full install

Why it happens

npm's resolver treats the whole tree - including devDependencies - as one constraint problem on a full install, and peer conflicts can resolve when extra packages provide alternative satisfying versions. With --omit=dev, the dev packages vanish from the tree but their peer requirements on shared packages can still constrain resolution, and the previously working layout collapses. The conflict was always there; the dev tree was just papering over it.

Edge cases

• If aligning versions is impossible (a dev tool genuinely requires an old peer), add an override for the peer package - but scope it narrowly and document why.
• Check that CI and local use the same npm version; different resolvers can mask or reveal the same conflict.
• After fixing, delete node_modules and the lockfile and reinstall both ways to make sure the lockfile does not carry the old broken layout.
• Watch for the same pattern with optionalDependencies - they can mask conflicts the same way dev deps do.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_gv4HKoLS2yojTlDXA5MgRw