Why use peer dependencies in npm for plugins?

npm install peer dependency
npm check-peer dependencies
yarn add --peer dependency
yarn install peer dependencies
npm peer
npm resolve peer dependencies
npm save as peer dependency
npm peer dependency warning

Why does, for example, a Grunt plugin define its dependency on grunt as "peer dependencies"?

Why can't the plugin just have Grunt as its own dependency in grunt-plug/node_modules?

Peer dependencies are described here: https://nodejs.org/en/blog/npm/peer-dependencies/

But I don't really get it.


I'm working with AppGyver Steroids at the moment which uses Grunt tasks to build my source files into a /dist/ folder to be served on a local device. I'm quite new at npm and grunt so I want to fully comprehend what is going on.

So far I get this:

[rootfolder]/package.json tells npm it depends on the grunt-steroids npm package for development:

  "devDependencies": {
    "grunt-steroids": "0.x"

Okay. Running npm install in [rootfolder] detects the dependency and installs grunt-steroids in [rootfolder]/node_modules/grunt-steroids.

Npm then reads [rootfolder]/node_modules/grunt-steroids/package.json so it can install grunt-steroids own dependencies.:

"devDependencies": {
    "grunt-contrib-nodeunit": "0.3.0",
    "grunt": "0.4.4"
"dependencies": {
    "wrench": "1.5.4",
    "chalk": "0.3.0",
    "xml2js": "0.4.1",
    "lodash": "2.4.1"
"peerDependencies": {
    "grunt": "0.4.4",
    "grunt-contrib-copy": "0.5.0",
    "grunt-contrib-clean": "0.5.0",
    "grunt-contrib-concat": "0.4.0",
    "grunt-contrib-coffee": "0.10.1",
    "grunt-contrib-sass": "0.7.3",
    "grunt-extend-config": "0.9.2"

The "dependencies" packages are installed into [rootfolder]/node_modules/grunt-steroids/node_modules which is logical for me.

The "devDependencies" aren't installed, which I'm sure is controlled by npm detecting I'm just trying to use grunt-steroids, and not develop on it.

But then we have the "peerDependencies".

These are installed in [rootfolder]/node_modules, and I don't understand why there and not in [rootfolder]/node_modules/grunt-steroids/node_modules so that conflicts with other grunt plugins (or whatever) are avoided?

Peer Dependencies, There's one use case where this falls down, however: plugins. A plugin package is meant to be used with another "host" package, even though� The Solution: Peer Dependencies. What we need is a way of expressing these "dependencies" between plugins and their host package. Some way of saying, "I only work when plugged in to version 1.2.x of my host package, so if you install me, be sure that it's alongside a compatible host." We call this relationship a peer dependency.

I would recommend you to read the article again first. It's a bit confusing but the example with winston-mail shows you the answer why:

For example, let's pretend that winston-mail@0.2.3 specified "winston": "0.5.x" in its "dependencies" object because that's the latest version it was tested against. As an app developer, you want the latest and greatest stuff, so you look up the latest versions of winston and of winston-mail and put them in your package.json as

  "dependencies": {  
    "winston": "0.6.2",  
    "winston-mail": "0.2.3"  

But now, running npm install results in the unexpected dependency graph of

├── winston@0.6.2  
└─┬ winston-mail@0.2.3                
  └── winston@0.5.11

In this case, it is possible to have multiple versions of a package which would cause some issues. Peer dependencies allow npm developers to make sure that the user has the specific module (in the root folder). But you're correct with the point that describing one specific version of a package would lead to issues with other packages using other versions. This issue has to do with npm developers, as the articles states

One piece of advice: peer dependency requirements, unlike those for regular dependencies, should be lenient. You should not lock your peer dependencies down to specific patch versions.

Therefore developers should follow semver for defining peerDependencies. You should open an issue for the grunt-steroids package on GitHub...

Peer dependencies — NPM. A quick look into what are…, When should I use peerDependencies? When you are building a third party library/plugin; When the consumers of your library are using a� Peer Dependencies are used to specify that our package is compatible with a specific version of an npm package. Good examples are Angular and React . To add a Peer Dependency you actually need to

peerDependencies explained with the simplest example possible:

  "name": "myPackage",
  "dependencies": {
    "foo": "^4.0.0",
    "react": "^15.0.0"

  "name": "foo"
  "peerDependencies": {
    "react": "^16.0.0"

running npm install in myPackage will throw an error because it is trying to install React version ^15.0.0 AND foo which is only compatible with React ^16.0.0.

peerDependencies are NOT installed.

Common npm mistakes. One of the best things about node…, 0 as a peer dependency. Your module provides gulp tasks or plugins. The application using your module obviously “owns” the gulp dependency,� Why use peer dependencies in npm for plugins? (2) Why does, for example, a Grunt plugin define its dependency on grunt as " peer dependencies "? Why can't the plugin just have Grunt as its own dependency in grunt-plug/node_modules ?

Dependencies Done Right, Let's say we want to write a React plugin. Because of how the Node resolution works, Foo and Bar copies of HelloWorld To conclude, here's the rule on whether you should use dependencies or peer dependencies:. A command-line interface to install an NPM package and its peer dependencies automatically. Starting with NPM v3.0, peer dependencies are not automatically installed on npm install, and it can be a hassle to install them all manually. The install-peerdeps tool makes the process fast and easy.

Why use peer dependencies in npm for plugins? - node.js - html, Why does, for example, a Grunt plugin define its dependency on grunt as "peer dependencies"? Why can't the plugin just have Grunt as its own dependency in� On the other hand, if you're debugging an issue with the installer, you can use npm install --cache /tmp/empty-cache to use a temporary cache instead of nuking the actual one. npm ERR! npm ERR! If you're sure you want to delete the entire cache, rerun this command with --force.

Understanding the npm dependency model, Currently, npm is _the_ package manager for the frontend world. however, another, less-used key called "peerDependencies" , which has� Why use peer dependencies in npm for plugins? 0. algular-cli installation issue with rxjs. 6. Updating to Angular 4 from 2. “Unmet Peer Dependencies” for @Angular

  • One important thing I noticed and isn't said anywhere, when we're building a plugin, should we have a duplicate of package dependencies, for the peer dependencies? In the OP example, we can see that "grunt": "0.4.4" is both in devDependencies and peerDependencies, and it does make sense to me to have a duplicate there, because it means both that I need that grunt package for my own use, but also that the users of my library can use their own version, as long as it respects the peerDependencies version lock. Is that correct? Or is the OP example a very bad one?
  • I can imagine people creating a Grunt plugin being fans of Grunt :) As such it seems natural for them to use Grunt themselves for the build process of their plugin.... But why would they want to lock the Grunt version range their plugin works with to the build process they use to create it? Adding it as a dev dependency allows them to decouple this. Basically there are 2 phases: build time and run time. Dev dependencies are needed during build time. Regular and peer dependencies are needed at runtime. Of course with dependencies of dependencies everything becomes confusing fast :)
  • Thank you for this answer! Just to clarify, in your example, if JacksModule depends on JillsModule ^1.0.0 withJillsModule being a peer dependency of JacksModule and YourCoolProject were using JacksModule and JillsModule ^2.0.0, we will get the peer dependency warning by NPM, which will advise us to install JillsModule ^1.0.0 as well. But what happens then? YourCoolProject will now have two versions of JillsModule importable through import jillsModule from "..."? And how do I remember that when I use JacksModule I need to pass it an instance of JillsModule v1.0.0?
  • @tonix Well, it will indeed be a problem that you have a version incompatibility. peerDependencies does not solve that. But it does help to make the problem explicit. Because it will clearly show the version mismatch instead of using two versions silently. The app developer that is selecting the libraries will have to find a solution.
  • @tonix Or the third option: clone the JacksModule repo, upgrade it to depend on JillsModule ^2.0.0 and offer a PR to the project maintainer. It may help to submit a bug first saying this dependency is outdated and you would like to help update it. If you make a good PR, most library maintainers will merge it and thank you for it. If maintainers are unresponsive, you can publish your fork to NPM namespaced under your name and use your fork instead. In any way, there are solutions but peerDependencies does not solve it on it's own.
  • You say that multiple versions of a package which would cause some issues but isn't that the whole point of a package manager? They even discuss this further up in the same article where there are 2 versions of the same package in the project: one provided by the developer and one supplied by a 3rd party library.
  • I think I understand the point of peer dependency but in the winston example am I now just unable to use the winston-mail library because my version does not match the peer dependency? I would much rather have that temporary downgrade from latest and greatest for the 1 library than to not be able to use it at all.
  • for your first comment, as far as I understand and use it, it has to do with testing, e.g. if you have a package which has been tested by you on for a specific 3rd party package, you can't be sure that if one of your dependencies change ( bug fix, major feature update) that your package will work. Therefore, you can specify a specific plugin version and are save with your tests.
  • On your second comment: that's why they say in the docs that developers should be lenient with their package dependencies and should use semver, e.g. instead of "0.2.1", "~0.2.1"-> allows "0.2.x" but not "0.3.x" , or ">=0.2.1" -> everything from "0.2.x" to "1.x" or "x.2.". .. (but not really preferable for an npm package would go with ~
  • why not just put react 16 as a dep inside foo? that way both 15 and 16 will be avaiable and foo can use 16 and mypackage can use 15?
  • React is a framework that is bootstrapped at runtime, in order for both React 15 and React 16 to exist on the same page you would need both to be boostrapped simultaneously which would be extremely heavy and problematic for the end user. If foo works with both React 15 and React 16 then it could list its peerDependency as >=15 < 17.
  • nitinsh99 my answer was to explain the purpose of peerDependencies with the simplest example possible, not how to get rid of the error thrown by peerDependencies
  • @nitinsh99 adding react inside package dependency will provide issue like Hooks - Multiple reacts in a package