peerDependencies cause a conflict on install

[jamesmortensen]

Hello,

You should consider not making jsdoc a peerDependency and should instead make it a dependency. I had trouble installing and don't want to mess around with my jsdoc installation since I have it working the way I want it to. Hope this helps!

880 silly resolved []
2881 error peerinvalid The package jsdoc does not satisfy its siblings' peerDependencies requirements!
2881 error peerinvalid Peer jsdoc-githubify@0.1.3 wants jsdoc@3.3.0-alpha2
2882 error System Darwin 13.1.0
2883 error command "node" "/usr/local/bin/npm" "install" "jsdoc-githubify"
2884 error cwd /Users/jem/Dev/myproj/app
2885 error node -v v0.10.26
2886 error npm -v 1.4.3
2887 error code EPEERINVALID
2888 verbose exit [ 1, true ]

[thlorenz]

Not sure why you are running into this, the version required by jsdoc-githubify is exactly the version it works with, so I have to pin it. However it doesn't use it so it's not a dependency.

How are you using this with docme? Cause you shouldn't have to change your global install.

[q2s2t]

Hello,

I had the same issue, solved by this

npm uninstall -g jsdoc
cd myProject
rm -rf node_modules/
npm install

Also you may want to update npm itself.

[jamesmortensen]

Not sure why you are running into this, the version required by jsdoc-githubify is exactly the version it works with, so I have to pin it. However it doesn't use it so it's not a dependency.

I think what you might be missing is that peerDependency isn't just a placeholder for you to pin things. It actually tells npm to install jsdoc alongside the module instead of within the module. So if there's another script that uses a different version of jsdoc, such as in my case, that version of jsdoc must first be uninstalled so that your peerDependencies can be satisfied.

If jsdoc-githbufy isn't using jsdoc, or even if it is, please consider either putting it in the dependencies section or perhaps just specify the version in the README. I spent a lot of time writing scripts that work with the latest version of jsdoc. I want to install jsdoc-githubify so I can play with it during my downtime to see if it's a better replacement for what we're doing now. However, I can't continue to generate documentation if your module decides that I have to uninstall my local copy of jsdoc. Therefore, if I want to try your module out to see what it can do, while still working on the product and meeting goals, I can't use my scripts anymore.

If it helps, this is all I'm doing, today, to output JSDocs for my project:

node_modules/jsdoc/jsdoc.js scripts/**/* ../Readme.md -d doc -t node_modules/ink-docstrap/template/ -c jsdoc.conf.json 

That version of jsdoc is 3.3.0-alpha5, whereas your module, whether you intend it or not, requires that I uninstall this version to satisfy your jsdoc 3.3.0-alpha2 peerDependency requirement. I hope it's clear that peerDependencies aren't simple placeholders, and when you lock them down to specific patch versions, it creates problems for people who need to use other versions for different things. See this section of the Node.js blog post on peerDependencies:

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. It would be really annoying if one Chai plugin peer-depended on Chai 1.4.1, while another depended on Chai 1.5.0, simply because the authors ... didn't spend the time figuring out the actual minimum version of Chai they are compatible with.

I don't know the exact details of this module, so take what you will from this, but I hope this helps clarify and makes your module more accessible to others!

[thlorenz]

tl;dr; (your entire thing), but here is a short answer.

I do know how peer deps work and jsdoc needs to be one since it's not directly used by jsdoc-githubify, but only specific versions of both of these modules work together nicely. Therefore I use peer deps to indicate to npm to warn the user in case they are trying to use jsdoc-githubify with an incompatible jsdoc version.

Things work perfectly for me (I have installed docme and wicked multiple times on different machines with different OSes without any problems).

As @quentinrossetti points out simply uninstalling jsdoc in order to allow npm to use the correct version instead fixes the issue. That is exactly what the peer dep warning is trying to guide you to do.

Closing since not a jsdoc issue.

[jamesmortensen]

The tl;dr is basically this: Your stuff causes my stuff to break and not work. Hence, I cannot use your stuff. Even following quentin's suggestion to uninstall jsdoc means I now can't use ink-docstrap, because npm won't let me install my jsdoc dependency while your module is installed on my system.

If you can't fix it, fine. You know your project better than I do. I'll move on. Thank you for your explanation.

[thlorenz]

Just install jsdoc and jsdoc-githubify, docme, etc. local to the package where you want to use it. Then add an npm script to your package, i.e.

{
  "scripts": {
     "docme": "docme README.md"
  }
}

That way you can avoid your global conflict.

If you can't fix it, fine. You know your project better than I do

No one can fix your global conflict (the peerDep just makes you aware of it) which is why I discourage installing your build dependencies (even command line tools) globally. Otherwise you end up in something similar to "DLL hell" which is what npm's local strategy is trying to avoid.

[jamesmortensen]

No one can fix your global conflict (the peerDep just makes you aware of it) which is why I discourage installing your build dependencies (even command line tools) globally.

I think we're talking past each other. Maybe our definitions of global (/usr/local/lib/node_modules/) and local (~/Dev/jem/myproj/app/node_modules) aren't the same, because all of my dependencies are installed inside my project's node_modules folder.

With that said, I found a workaround, so the conflict between your module and the other module in my project is solved. I'm also thinking I should write my build tools as their own modules so they aren't affected by other modules' dependencies on locally shared resources. Thank you for your help!