What are peer dependencies in a Node module?
A simple explanation of the peerDependencies field in the package.json file
In some package.json files, you might see a few lines like this:
{
//...
"peerDependencies": {
"libraryName": "1.x"
}
}
You might have already seen dependencies
and devDependencies
, but not peerDependencies
.
dependencies
are the packages your project depends on.
devDependencies
are the packages that are needed during the development phase. Say a testing framework like Jest or other utilities like Babel or ESLint.
In both cases, when you install a package, its dependencies and devDependencies are automatically installed by npm.
peerDependencies
are different. They are not automatically installed.
When a dependency is listed in a package as a peerDependency, it is not automatically installed. Instead, the code that includes the package must include it as its dependency.
npm
will warn you if you run npm install
and it does not find this dependency.
Example: let’s say package a
includes dependency b
:
a/package.json
{
//...
"dependencies": {
"b": "1.x"
}
}
Package b
in turn wants package c
as a peerDependency:
b/package.json
{
//...
"peerDependencies": {
"c": "1.x"
}
}
In package A, we must therefore add c
as a dependency, otherwise when you install package b
, npm will give you a warning (and the code will likely fail at runtime):
a/package.json
{
//...
"dependencies": {
"b": "1.x",
"c": "1.x"
}
}
The versions must be compatible, so if a peerDependency is listed as 2.x
, you can’t install 1.x
or another version. It all follows semantic versioning.
→ I wrote 17 books to help you become a better developer, download them all at $0 cost by joining my newsletter
→ JOIN MY CODING BOOTCAMP, an amazing cohort course that will be a huge step up in your coding career - covering React, Next.js - next edition February 2025