The peer dependency warning you scrolled past is sometimes the whole bug

Run npm install in most real projects and you'll see a block of yellow text scroll past about peer dependencies. Something like:

npm warn ERESOLVE overriding peer dependency
npm warn While resolving: [email protected]
npm warn Found: [email protected]
npm warn Could not resolve dependency:
npm warn peer react@"^19.0.0" from [email protected]

Almost nobody reads this. npm installs anyway, the install "succeeds", the app boots, and the warning scrolls off the top of the terminal before anyone's eyes get to it. Most of the time that's a completely reasonable thing to ignore. A library declaring a peer range of ^18.0.0 when you're on 18.3.1 is not a real problem. The maintainer just hasn't bumped their package.json range since the last major React release, and the actual API surface they depend on hasn't changed.

When the warning is the whole bug

The case that isn't fine is when the version mismatch is wide enough that the library's actual code, not just its declared range, assumes APIs or behavior that changed between the version it wants and the version you have. React 19 removed propTypes forwarding behavior that some 18-targeted component libraries relied on. State management libraries have shipped breaking changes to their context internals between majors while keeping mostly-compatible public APIs. In both cases, npm install still succeeds, the app still boots, and the failure shows up later as a subtle rendering bug or a state update that silently doesn't propagate, in exactly the code path that happens to touch the mismatched internals.

The warning at install time was the only moment this was visible for free. After that, you're debugging a symptom with no obvious link back to a dependency version, because the install log is long gone by the time the bug report comes in.

Why this got worse with AI-assisted development

An assistant asked to "add drag and drop to this list" or "add a date picker" will often suggest npm install some-library, see the peer dependency warning get exit-code 0'd through in the terminal output, and treat the install as successful. It has no way to distinguish an install that generated a harmless deprecation-style peer warning from one that just quietly built you a version combination the library authors never tested together. The warning gets scrolled past in the same way a human would scroll past it, except the human at least has the option of stopping to read it.

Making the warning impossible to miss

You don't need a new tool for this, npm install --strict-peer-deps turns every peer dependency conflict into a hard failure instead of a warning:

npm install --strict-peer-deps

This is aggressive. It will block installs for genuinely harmless mismatches too, and on a large dependency tree that can mean fighting through several rounds of resolution errors before anything installs. For most day-to-day work that's too much friction. A better middle ground is running it once after adding a new dependency, or as a CI check that runs on package.json changes specifically, rather than on every install.

{
  "scripts": {
    "postinstall:check-peers": "npm install --strict-peer-deps --dry-run"
  }
}

A dry run costs nothing and surfaces exactly the conflicts you'd otherwise have to notice by reading scrollback.

The lockfile doesn't save you here

It's tempting to assume the lockfile pins things down enough that this doesn't matter after the first install. It pins the exact versions, which is good, but it pins them at whatever mismatched combination was resolved the first time the warning got ignored. Every subsequent npm ci reproduces the same mismatch faithfully. The lockfile guarantees reproducibility, not correctness.

Seaworthy flags dependency trees with unresolved peer conflicts wide enough to indicate a real API mismatch, rather than the cosmetic version-range lag that makes up most peer warnings.