NPM peerDependencies in Depth: A Comprehensive Introduction

As Javascript developers, we all know two different dependencies in our projects, dependencies and devDependencies, but what about peerDependencies?

In this series, we will examine this less common dependency in Javascript. We will study what they are, what I need to know about as a library user, and what best practices are for library authors.

What are dependencies in NPM

Let’s recap the different common types:

• dependencies: these are the tools used in your application; a good example is react, angular, and express. When your application is in production, the code of the libraries on dependencies will run under the hood and power your application.

• devDependencies: You will use these utilities to build your application. Here, you will find libraries to compile or parse your code and libraries to run your test.

What are peerDependencies

Authors specify specific libraries as peerDependency when they require them to be installed in the workspace/project for everything to work as expected. They tell NPM (and the developers installing the library) that the package requires another package’s specific version (or range of versions) to function correctly. Still, the user is responsible for installing and managing that dependency.

Let’s imagine an example: You are creating a utility for your favorite framework, which should be installed in the environment where your library will be running. The way to accurately specify this scenario is using the NPM peerDependency feature. It provides a clear guideline for the seamless integration of your library.

This practice is particularly common in libraries that function as “plugins,” as they need to indicate the workspace requirements for proper functionality.

Real Example of peerDependency

Let’s analyze a popular React library, react-datepicker; if we look at how its package.json looks today, we can tell that we require at least React version ^16.9.0 for react-date picker to work correctly.

"peerDependencies": {
  "react": "^16.9.0 || ^17 || ^18",
  "react-dom": "^16.9.0 || ^17 || ^18"
},

If we fail to comply with this requirement, unexpected behavior will arise.

The Challenges peerDependencies Address

Version conflicts occur when packages in a project rely on different versions of the same library. This can lead to errors, especially for libraries like React, where sharing the same instance is crucial for state management and component communication. Without peerDependencies, multiple library versions could be installed, resulting in unexpected behavior.

To prevent these issues, peerDependencies allow package authors to specify which version of a dependency their package requires without directly installing it. This shifts the responsibility to the developer using the package, ensuring they install a single, compatible dependency version. For example, libraries like react-datepicker and react-router use peerDependencies to ensure they work seamlessly with the same version of React in the project.

Another Example

Imagine this scenario: You’re creating a library to share a fancy operator for rxjs. If you set rxjs as a dependency instead of a peerDependency, your library will install its own version of rxjs. This might not seem like a big deal at first, but in reality, it can lead to version conflicts.

If the project that installs your library already uses a different version of rxjs, it could cause significant issues. The application might end up with two instances of rxjs (one from your library and one from the project itself). Since rxjs relies heavily on shared observables and subscriptions, having two versions running simultaneously can result in unpredictable behavior, such as streams not synchronizing properly or missing events.

By using peerDependencies instead, you can avoid this problem. Your package will signal to the project that it expects a specific version (or a range) of rxjs to be present, but it won’t install its own version. This way, the project will use a single version of rxjs shared by your library and other parts of the codebase, ensuring everything runs smoothly and in harmony.

Conclusion

peerDependencies may not be as commonly discussed as dependencies or devDependencies, but they play a critical role in ensuring compatibility and avoiding version conflicts in complex projects. By clearly defining which version of a shared dependency a library needs without directly installing it, peerDependencies allow developers to maintain control over their project environment.

The goal of this first post is to create a good understanding foundation of peerDependencies. In the next chapter of this series, we will explore in a more practical way the different aspects of peerDependencies as a user of libraries with peerDependencies, how to overcome common problems, and how they behave in different javascript package managers.