Peer dependencies semantics

[larixer]

I wonder what is semantic of peer dependencies? The official documentation explains peer dependencies only briefly as a way to install a plugin package along the compatible version of a host package. What does along mean in this context, does it mean that plugin can require host and should find a compatible version, or does it mean that the parent of plugin can require host and find a compatible version specified by plugin? What should you do to ensure a specific peer dependency version, should you provide host as a dependency only in the direct parent of a plugin, or you can do it by providing host in any parent up in the graph, or maybe you can provide host in an arbitrary place in the graph not necessarily in any of the parents?

The confusion around peer dependencies semantic is here with us from npm 1 and up to this day, the confusion only increases with changes around peer dependencies semantic from one npm version to the other and it is not clear what peer dependencies are really meant to be?

[ljharb]

A package's peerDependency requirement is hoisted up the tree (to the top, i think?). It is required to be present, and to satisfy the provided version range.

Plugin systems use peer deps, but it doesn't seem right to be to apply plugin terminology to peer deps themselves. Typically, the "core" of a plugin system is peerDepended-on by everything in the plugin ecosystem, except the top-level apps consuming them, which declare the "core" as a runtime or dev dep explicitly.

An example is react: nothing should runtime-depend on React except a top-level app, and anything else that interoperates with React must peer-depend on it.

[larixer]

A package's peerDependency requirement is hoisted up the tree (to the top, i think?). It is required to be present, and to satisfy the provided version range.

Does it mean that peerDependency requirements satisfaction are checked after hoisting was performed?

[travi]

except the top-level apps consuming them

small clarification that i think is worth making here. it isn't always a top-level app that leverages the "core" of the plugin system.

react typically would be the app, but when considering something like octokit, it isn't uncommon for a package to use octokit and some plugins to interact with the github api. the peer-dependency defined by the octokit plugins should be satisfied by the package using octokit directly in that case. since package directly imports/requires octokit, it should define a production dependency on octokit rather than passing the peer requirement on to the consumer of that package.

[ljharb]

That's exactly right, which is why i'm unsure about the "to the top" part - i think it actually hoists it up until it's satisfied.

however, octokit may still want to pass on the peer dep requirement to consumers, if "having two incompatible versions of the core in the app" would be a problem.

[larixer]

So, it seems, there is two semantics for peer dependencies in npm 7:

1. Legacy peer dependencies
   Npm hoists the dependency graph, then checks peer dependency requirements and warns about incompatibilities.

2. Auto-installed peer dependencies
   Npm checks if any of the transitive parents of the package with peer dependencies provides peer dependencies, if not - missing peer dependencies are added automatically (where? to the package that has requested them or to the top level?), then npm hoists the dependency graph, and then it checks peer dependency requirements and errors out on incompatibilities.

Can someone confirm, is this really the case?