npm peer dependency warning — how to handle

Quick Answer

# Install missing peer dependency explicitly
npm install react@18 react-dom@18

# Suppress warnings by installing with --legacy-peer-deps
npm install --legacy-peer-deps

# See all peer dependency issues
npm ls 2>&1 | grep "peer dep"

When this happens

npm warn peer dep missing: react@>=16.8.0, required by some-component@1.0.0
npm warn deprecated some-component@1.0.0: Use new-component instead

A package lists another package as a peer dependency, meaning you are expected to install that dependency separately at the right version.

Other causes & fixes

What is a peer dependency?

Peer dependencies are packages that a library needs you to provide, rather than bundling itself. Common pattern: a plugin that requires the host library (e.g. a React component requiring React).

// A package.json might say:
{
  "peerDependencies": {
    "react": ">=17.0.0 <19.0.0"
  }
}
// You must have react installed at a compatible version

Auto-install peer deps (npm 7+)

npm 7+ installs peer deps automatically. This can cause ERESOLVE errors when versions conflict. npm 6 only warned.

# Revert to npm 6 behavior (warn, do not block)
npm install --legacy-peer-deps

Check which peers are missing

npm ls
# Packages with "peer dep unmet" or missing entries need attention