How do peerDependencies work?

In a nutshell, peerDependencies are a way to “warn” projects that might use your, let's say, plugin, that this plugin requires specific dependencies to be able to work properly, and these dependencies have to be installed in your root project.

WTH does it mean in practice?

Let’s say you’re creating a plugin written in React, and you decided to use Hooks, which was officially released in react 16.8.0. Since Hooks is not available to previous versions of React, we need to be careful about this detail.

Now, imagine a project wants to use your plugin, but this “host project” is still using React 16.3 (which means, Hooks API is not available).

When you install the plugin, NPM will create a new dependency in the node modules, introducing your plugin with the new react version and it will conflict in the project, as you can’t have two versions of React running on the same project.

How do you solve it?

In your plugin, you must introduce the peerDependencies section in the package.json, and add the React version that it requires to work.

This will work as a sort of validation so that when this situation happens, a warning will be thrown while installing the project dependencies and whoever is doing it will know that to get this working, the react version of the “host project” will have to be updated.

Note that, in old versions of node, it used to have a different behavior as per related in their doc:

NOTE: npm versions 1 and 2 will automatically install peerDependencies if they are not explicitly depended upon higher in the dependency tree. In the next major version of npm (npm@3), this will no longer be the case. You will receive a warning that the peerDependency is not installed instead.

By the time I'm writing this post, we already have v6.9.0 as the latest stable version of NPM.