npm link and multiple levels of peerDependencies = psychedelic mess

[mpj]

So npm link behaves in (what I think is) an unexpected way when you multiple levels of packages that depend on the same peerDependency.

Look at the dependency chain below. I have a Knockout app, spotify-app, that relies on a spotify-framework module that in turn relies on a spotify-library module. All three depend on knockout and it's very important that there is only one instance of Knockout in the app because reasons. Thus, spotify-app requires knockout as a normal dependency, and the spotify-framework and spotify-library module both list it as a peerDependency. This dependency chain works fine, until you decide to do development on the spotify-framework module and try to use npm link - then the mad hatter comes in and gives you spiked cookies and everything goes pink fluffy unicorns dancing on rainbows.

This is what happens: You happily clone the spotify-framework from git, and then you run npm link in its directory, in preparation of linking it in from spotify-app. The problem here is that npm link will run spm install (I think) under the hood. npm will look at the peerDependencies of spotify-library, and then install an instance of knockout inside the node_modules of spotify-framework, because it thinks that spotify-framework is the top-level module. This will silently cause _duplicate versions_ on knockout, because spotify-app will install another instance of knockout itself. It's obvious what happens when I write it down like this, but it was extremely confusing to figure out what happened here, I tell you.

I'm not sure how this should be solved, but I'm leaning towards that npm link should never install peerDependencies on it's own, because it's most likely not the top-level module if it's being linked.

{
  "name": "spotify-app",
  "version": "0.0.1",
  "private": "true",
  "dependencies": {
    "knockout": "~3.0.0",      
    "spotify-framework": "0.0.1"
  }
}

{
  "name": "spotify-framework",
  "version": "0.0.1",
  "private": "true",
  "peerDependencies": {
        "knockout": "^3.0.0",
  },
  "dependencies": {
    "spotify-library": "0.0.1"
  }
}

{
  "name": "spotify-library",
  "version": "0.0.1",
  "private": "true",
  "peerDependencies": {
        "knockout": "^3.0.0",     
  }
}

[mpj]

Hopefully @domenic can chime in on this.

[domenic]

Thus, spotify-app requires knockout as a normal dependency, and the spotify-framework and spotify-library module both list it as a peerDependency.

This is not a correct use of peerDependencies. spotify-framework and spotify-library should list knockout in their dependencies list, and then you should use npm dedupe to ensure there is only one copy.

People make this mistake often enough that we should probably add it to the peer dependencies documentation.

[isaacs]

I'm tempted more and more all the time to say that peerDependencies was just a mistake. It's a departure from The npm Way. It introduces dependency hell, which was so common in every platform except npm, because of how it does things. It is an exposure of that which ought to be encapsulated.

dependencies are things you require(). devDependencies are things you require() for tests and prepublish compilation. If you don't require() it, then it shouldn't be a dependency.

peerDependencies only works for modules like express or grunt that expect to be a singleton monolith. In those cases, one could argue, it's appropriate for them to be singleton monoliths, since they're frameworks that expose some shared plugin surface. However, they're rare enough that they ought to just one-off their checks.

A module like express or grunt should set a global, and throw if it's already set by some other version of the lib. Then plugins can write in their documentation which versions of the core thing they work with. The inherent friction in this approach will guide people towards writing simpler, more modular programs, which encapsulate their dependencies and expose independently useful API surfaces.

[isaacs]

Another option for plugins would be for the plugin host to document some specific means for determining what version of the host the plugin works with. Then it can do something like this:

var hostVersion = require('./package.json').version;
var semver = require('semver');

exports.addPlugin = function(plugin) {
  var supported = plugin.supported;
  if (!supported)
    throw new TypeError('wtf, doesnt say what it wants: ' + plugin.name);
  if (!semver.satisfies(hostVersion, plugin.supported))
    throw new TypeError('plugin not supported by this host. Wants: ' + plug.supported + ' actual=' + hostVersion);
  this.plugins.push(plugin);
};

[mikeal]

+1 to deprecation. people have been writing more and more about alternative patterns for what people are using peerDeps for and I've been convinced.

[matteofigus]

"However, they're rare enough that they ought to just one-off their checks" -- agree, +1 for deprecation

[max-mapper]

enthusiastic +1 for deprecation. peerDeps have only caused trouble in my experience

[crrobinson14]

+1 can't live without this. Oh wait. No, I can. Isn't that the litmus test?

[AdrianRossouw]

+1 for removal. They were attractive, but ultimately a mistake.

I think that the entire reason you would want them, is the entire reason they don't work.

The magic sauce of npm is that it allows more specific overrides downstream. Packages shouldn't be able to make assumptions about packages above them in the file hierarchy.

[joaquimserafim]

👍

[KoryNunn]

My impression of what peerDependencies are for is as follows:

Module A absolutely needs module B in order to work, it is a dependency.

BUT

It would be completely incorrect to install module B when installing module A, because module B is to be used as a top-level module, say, a framework or similar.

I've used this pattern a fair bit, and it works perfectly, does not lead to dependency hell, and is extremely easy to understand when reading the code.

It allows 'plugins' to share constructors, meaning the host module can simply do:

if(moduleA.thing instanceof SomeModuleBConstructor){
    // Good to go.
}

I feel that peerDependencies are currently abused, because there is very little documentation around them. The usual case, where peerDependencies are not require()'d, is very confusing, because it is hard to see where the dependency is.

TL;DR, a code example:

// Module A

// peerDependency on Module B

var Ctor = require('moduleB').Ctor;

function InheritedCtor(){}

module.exports = util.inherits(InheritedCtor, Ctor);


// Module B

function Ctor(){}

module.exports.Ctor = Ctor;

Here it is immediately obvious why module B shouldn't be a normal dependency of module A, but that A depends on B being there. This is where peerDependencies are very useful.

[Raynos]

I'm tempted more and more all the time to say that peerDependencies was just a mistake.

I just opened yet another issue of a really hard to debug peer dependencies edge case ( #5084 ).

Peer deps are really hard to implement correctly.

It introduces dependency hell,

That's the exact issue I ran into.

+1 on removing them

[DamonOehlman]

If it introduces dependency hell, or anything even close to that, then yes I think deprecation is probably the best solution.

[KoryNunn]

It probably doesn't help that there is no mention of peer dependencies anywhere in here

It would be unfortunate to remove a useful feature just because people don't know how to use it.