Why do some packages need to be peerDependencies of my components

[benjgil]

This is a question which arises again and again among Bit customers - understandably because this is an aspect of component-driven development which is very different to regular application-driven dev, and revolves around the very reason for the concept of peer dependencies. Here's an explanation for why peer dependencies are so key to components, and how the process works.

Singletons
In order to understand peer dependencies, we need to understand what problem they solve.

There are libraries/packages which require only a single version of the library to be installed in an application. This can be due to a number of reasons, among them the need to have only a single version of the framework (react, angular), or some communication requirements of context components or UI libraries. Whatever the reasons, this is a hard requirement and if there are multiple versions of these packages in your application you will inevitably experience odd behaviour and most likely errors which break your app.

The problem this throws up is that when you install packages in an app, npm will automatically install their dependencies too.
For instance if packageA has packageB in its dependencies list, an application installing A will also automatically install B as well.
If each react-specific package has react as a regular dependency then, each time you install one of those packages your application will also install react. And if they list different versions of react, multiple versions of react will be installed...
But, as stated above react requires that only one version of it is installed in an application for the app to function correctly.

And this is an issue for all components, including bit components, as components by definition are only ever going to be consumed by an application (or another component).

So, how does a react-specific packageA (or componentA) tell an application that it depends on react, but not to install another version of react when it installs packageA?

That's where peerDependencies comes in.

Peer Dependencies
The way to ensure that only one version of a package is installed in the consuming application is to transfer the responsibility of installing that package over to the consuming application itself. That way, it can ensure that only a single version of that package is installed.

And the way to tell a consuming application not to install a specific dependency, is to list it as a peerDependency. The peerDependencies field lists the dependencies which packageA requires in order to function properly, but which shouldn't be automatically installed when installing packageA.

The peer dependencies do still need to be installed, so they'll need to be added to the dependencies section of your application. But in that way your application will only ever install one version of those packages, and they will therefore by definition be singletons and will function as required.

Bit components and Peer Dependencies
Bit components are always consumed packages, so the above is relevant to all bit components.
Some packages which are required to be set as peerDependencies for bit components are react, Angular (and its various core packages), MUI-related packages (inc. @emotion packages), react context components, among others.

Peer Dependency Versions
One more issue that this throws up is that the various packages in your application which depend on that same peerDependency - e.g. back to our example of react-specific components/packages which each depend on react - may have specific versions, or a range of versions which they are compatible with. Some may be compatible with both react 16 and 17, others only react 17, and others only react 15.

This means that you need to be careful in your consuming application to have a version of a peerDependency (in our example, react) installed which is compatible with all the application's other dependencies. Or, more to the point, make sure that your app is depending only on packages which are compatible with the specific version of react (peerDependency) that your application has installed.

It also means that it's important to define as relaxed (i.e. inclusive) a version policy for your component's peer dependencies as possible so that they can be consumed by as many relevant applications as possible - obviously making sure that your component's code is compatible with all versions in your policy.

In Summary
peerDependencies take a some time to get your head around, in general and as part of the move to thinking about components rather than applications. But they are a very important part of component dependency configuration, and understanding them can go a long way to making sure your dependency tree is configured as required.