How to resolve dependency hell in NPM with peerDependencies

Question

Setup:

Given the following points

• my_library makes extensive runtime use of jquery.
• in my_library the jquery required via npm is ^3.3.1 by default (because of security fixes in it). However it is compatible also with jquery >=2.2.0 (but is not specified in package.json, yet)
• the my_library is used in a custom_project via npm.
• the custom_project requires also outer_library, that is using different & conflicting jquery versions (e.g. let's say jquery 1.7.3).
• the custom_project_2 instead just requires my_library in dependencies.

Problems:

• installing custom_project will provoke duplicate dependencies, messing up jquery for one of the two libraries.
• the jquery version in my_library dependencies specifies a suggested version (in order to avoid critical vulnerabilities) but doesn't say anything about which jquery minimum version is compatible with my_library

Eventual solution:

To avoid jquery dependency duplication (1.7.3 for outer_library and 3.3.1 for my_library) I could move my jquery ^3.3.1 from dependencies to devDependencies, so I'll get the 3.3.1 on development while it won't be installed on production (npm install --only=prod) and just jquery 1.7.3 will be installed.

But this:

• doesn't guarantees that my_library will get a compatible jquery version, so my_library could easily break.
• • adding jquery@>=2.2.0 inside my_library peerDependencies will at least raise a WARN asking to resolve the conflict manually installing a specific version in custom_project (even though probably it can't be solved).

• feels wrong to me since jquery is a runtime dependency and shouldn't go into devDependencies (with unit-testing tools, etc.). In fact jquery won't be installed in the custom_project_2, when installing on production (so my_library will break)

Questions

1. How can I manage to satisfy both use cases of dependency by my_library?

2. (A) In case the outer_library would require a jquery compatible with my peerDependencies definition (>=2.0.0), would I STILL need to install jquery manually? Or npm will resolve a common version?

3. (B) Are there cases where peerDependencies doesn't complain and doesn't require to install anything manually? (as long as semvers are honoured?)

4. (A) Does it make sense to put a dependency like jquery (high probability of conflicts) either inside peerDependencies (with an as loose as possible semver) and inside dependencies with the recommended version?

5. (B) Would that work correctly in every setup and with NPM version <3 (peerDependencies automatically installed) and >=3 (manual installation needed)?

Appreciated if you can answer even to a part of the questions

Answer 1

Is it safe to assume the dependency of my_library on jquery is a peer dependency? And that you are on the development team of my_library?

If so, the best solution might be to change my_library's peer dependency on jquery into a regular dependency. If I understand this article correctly, only peer dependencies can generate conflicts between packages, regular packages get installed into subdirectories so my_library get's it's own version of jquery installed, seperate from outer_library.

It might just be impossible to convert a peer dependency into a regular dependency however. https://medium.com/@jacob.h.page/common-npm-mistakes-51bf8989079f

Is your module a plugin for some library or framework? Then that library/framework is a peer dependency. The consuming application is responsible for selecting and integrating a set of mutually-compatible plugins; the plugins themselves should not introduce said framework directly, but should instead specify a maximally-inclusive version range to make the job of integration as easy as possible.

Your other option would be to wait for outer_library to release a new version that IS compatible with the latest jquery.