What is a peer dependency in npm?

A peer dependency is a package that a library needs but expects the project using it to install, so that the library and the project share one copy. Plugins and framework bindings use them: react-dom declares react as a peer, because two copies of React in one app do not work.

See a package's peer dependencies

npm view react-dom@19.0.0 peerDependencies

{ react: '^19.0.0' }

How npm treats them

• npm 7 and later install peer dependencies automatically and fail with ERESOLVE when the range cannot be satisfied.
• npm 3 to 6 only printed a warning and left installing the peer to you.
• peerDependenciesMeta can mark a peer as optional: { "some-peer": { "optional": true } }.

In package.json

{
  "name": "my-react-widget",
  "peerDependencies": {
    "react": "^18.0.0 || ^19.0.0"
  }
}

A wide range like ^18.0.0 || ^19.0.0 lets the plugin work in projects on either major version, which avoids most ERESOLVE conflicts.