A peer dependency says "I work with this package, but I expect you to supply it." Plugins use them to declare compatibility with a host. Since npm 7, peer dependencies are installed by default, which changed behaviour and surfaced conflicts that older versions only warned about.
What a peer dependency is
Think of a plugin for a build tool. The plugin does not want its own private copy of the tool. It wants to run inside the copy your project already has. A peer dependency expresses that relationship without making the plugin install the host itself.
{
"name": "my-plugin",
"peerDependencies": {
"host-tool": "^1.0"
}
}
What changed in npm 7
The npm documentation states that as of npm v7, peerDependencies are installed by default. In npm versions 3 through 6, they were not installed automatically and only produced a warning when the installed version was invalid.
Two effects follow:
- Installs that used to succeed with a warning can now fail with a conflict error.
- The dependency tree is more complete, because the host is guaranteed to be present.
Optional peers
Sometimes a plugin supports an integration only if the host has it. The peerDependenciesMeta field marks a peer as optional.
{
"peerDependencies": {
"soy-milk": "1"
},
"peerDependenciesMeta": {
"soy-milk": { "optional": true }
}
}
The documentation notes that npm will not automatically install optional peer dependencies.
Writing a good peer range
The guidance in the docs is to make the requirement as broad as possible, so it does not collide with other plugins. Since only a major change in the host is expected to break the plugin, a range such as ^1.0 or 1.x is suggested.
Narrow peer ranges are a common cause of install failures in large projects, because two plugins may demand incompatible host versions.
Handling conflicts as a consumer
When an install fails on a peer conflict:
- Read which two packages disagree and which host version each one wants.
- Check whether a newer release of the plugin widens the range.
- Prefer upgrading or replacing the plugin over forcing the install.
- Be wary of flags that skip peer checks. They hide the conflict instead of resolving it, and the failure can move to runtime.
A quick way to see what you have
Run npm ls with a package name to see which copies of it exist and who asks for them. If a plugin and its host disagree, that output shows both sides of the conflict, which is usually enough to decide whether to upgrade the plugin or the host.
Why this is a hygiene topic
Peer dependencies decide which version of a shared package your code actually runs. If a vulnerable host version is allowed by a loose range, a scanner will flag it, and the fix is often a coordinated upgrade of host and plugins together.
Safeguard's dependency scanning reports vulnerable packages in the resolved tree. You can try a free scan at gold.safeguard.sh/scan.
Quick check
Are peer dependencies installed automatically?
Yes, since npm 7. Before that, in npm 3 through 6, they only produced a warning.
What range should a plugin declare for its host?
As broad as is honest. Since only host major changes are expected to break a plugin, something like ^1.0 or 1.x is suggested.
Sources
Last reviewed: 19 October 2026.
