Repair an npm dependency tree without hiding conflicts

Identify range, peer, lockfile and runtime mismatches before making a reviewed dependency change.

Preserve the failing state

Record node --version, npm --version, the first meaningful error and the manifest/lockfile diff. Work in a disposable checkout when reproducing installations, which can run dependency scripts. Do not delete the lockfile as a first response: it records the tree that needs explanation.

Find who requests the version

Use npm explain package-name and npm ls package-name to identify the declaring parent. Compare dependencies, peers, overrides and engines separately. A plugin's host peer contract is different from its own private dependency. An override can change resolution without making the plugin compatible.

Check the actual range semantics

A caret range below 1.0 is narrower than many expect, and stable ranges do not automatically opt into prereleases. Run the following only where semver is already installed; these are local parser checks, not evidence that a package works with the selected version.

const semver = require('semver');
console.assert(semver.satisfies('0.2.9', '^0.2.3'));
console.assert(!semver.satisfies('0.3.0', '^0.2.3'));
console.assert(!semver.intersects('^18.0.0', '^19.0.0'));
console.assert(!semver.satisfies('2.0.0-beta.1', '>=1.0.0 <3.0.0'));

Make a small resolution change

Select a mutually supported plugin and host pair, or migrate one dependency deliberately. Regenerate the lock with the intended npm version and review the diff. npm ci requires an existing consistent lock and compatible install flags; it is a verification step, not a lock repair command. Avoid --force or legacy-peer-deps as proof of compatibility.

Verify the deployed shape

Test a clean installation and the application's meaningful behavior. Build with development tools available, then verify the production artifact with development dependencies omitted. Check Node exports and explicit ESM paths if installation succeeds but imports fail. Use npm pack --dry-run --json to confirm package contents before any publication. Native binaries must be tested on the target runtime and architecture; semver assertions alone cannot validate them.

Verification scope

Authored npm/Node cases. Offline Node semver fixtures exercise actual installed semver code; no registry install, native build, audit remediation or application compatibility is claimed.