Automatic installation of optional peer dependencies looks weird

[stof]

As of npm 7, peer dependencies are automatically installed without requiring the parent package to depend on them, including for optional peer dependencies. This looks weird to me. Common use cases for optional peer dependencies are:

• providing additional integration with a package if the project uses that package
• giving a choice between multiple alternatives. For instance, the webpack sass-loader packages supports using either sass or node-sass as the sass implementation, and uses optional peer dependencies for that (not defining any peer dependency and relying on package hoisting rules to be able to access the parent package would sometimes work with npm, but would fail with pnpm and yarn 2, and would also sometimes fail with npm depending on how packages were hoisted). this can even lead to surprising results because we end up in the case where the package chooses the implementation based on its rule for the case where multiple peer dependencies are satisfied, even if the project made an explicit choice by installing one of them and not the other.

I think it would make sense for optional peer dependencies to not be installed automatically but only validated.

[ljharb]

When you say “optional”, do you mean, specified as such in peerDependenciesMeta? All peer deps are and always have been required by default.

[ljharb]

npm/rfcs#221 (comment) and npm/arborist@e13ba3b seem like optional peer deps are already not auto installed?

[stof]

Well, npm 7.5.4 is auto-installing them. So maybe something changed again after that commit

[MylesBorins]

@stof could you open a bug report on the npm/cli repo if you think there is a bug

[stof]

@MylesBorins should it be on the cli repo or the aborist one (as previous work on that topic happened in arborist) ?

[MylesBorins]

Seems like you know more than me 😇. I'd say open in the one you find most appropriate and I'm sure the team will route appropriately

[cawa-93]

I do not agree with you. In my opinion, the automatic installation that we were offered brings a few useful things:

• No noise in your dependency list. A very common case is when you need to use 'packageA', which requires peer packageAP. You are forced to install both, although in fact you do not use the packageAP. Now looking at your list of dependencies, you see only what your program REALLY depends on.

• It also saves you problems with support. Suppose you have installed packageA and packageAP. After some time, due to refactoring or other reasons, the team refused to use packageA and removed this dependency. The 'packageAP' now remains in your list of dependencies. It is not used in any way, nobody needs it, but it is not always obvious. If someone is engaged in refactoring the list of dependencies, the following questions may arise::

  • Is the packageAP used somewhere?
  • Can I safely delete it?
  • Is it someone's peer dependency?
  • Why is it here at all?

• It also saves you noise when updating outdated dependencies.

[stof]

@cawa-93 the use case solved by optional peer dependencies is packages that can use several alternate implementations, where the project is expected to choose which one is used. The automatic installation means that all implementations get installed (which can lead to installing tons of packages, for instance when node-sass gets installed in parallel of sass).
For mandatory peer dependencies, I'm fine with the automatic installation.

[nfantone]

Came here to add my two cents on this.

I can see where @cawa-93 is coming from and the benefits of installing peers by default — however, I also see scenarios where this leads to unexpected behaviours or broken installations; something that a package manager should avoid like the plague. In addition to the sass-loader example already provided by @stof, here's another one: canvas via jsdom.

We recently upgraded some library to latest jest, which now pulls canvas required by jest-environment-jsdom — marked as peerDependenciesMeta.optional.

❯ npm why canvas
canvas@2.9.3 dev peer
node_modules/canvas
  peer canvas@"^2.5.0" from jsdom@19.0.0
  node_modules/jsdom
    jsdom@"^19.0.0" from jest-environment-jsdom@28.1.3
    node_modules/jest-environment-jsdom
      dev jest-environment-jsdom@"^28.1.3" from the root project

Turns out, canvas started requiring some native deps recently to be installed in your system to be able to be built and users started complaining about broken installations. And now, consequently, contributors to our own library are facing the exact same issue where they can't even run npm install the way they used to.

This whole ordeal is particularly bizarre because we don't even have a need for node-canvas in our own project. A use case which the jsdom developers anticipated by declaring canvas as optional to begin with. Regrettably, npm breaks this implicit contract.

Lastly: semantics. I believe they matter. At some point in your argument, you have to acknowledge that introducing something like an optional: true flag only for the package to be installed anyway, comes at the cost of users either misunderstanding or misusing your tool.

[thoughtspile]

Running into this with vitest -> jsdom -> canvas on M1.

To be fair, on a clean project optional peer dependencies are not installed, but on a larger ones they are, and I have no idea what's causing it

[ggascoigne]

Right there with you, what is the point of optional if it's going to be installed anyway. Surely if I want to use an optional feature I should be responsible for adding the optional package to my own set of dependencies.

And yes, I was bitten by the same jsdom -> canvas issue on an M1 mac, and that same problem is rippling through our team. A brew install cairo fixed it for me, but that's a really heavyweight solution to something that shouldn't be a problem in the first place.

[ingvaldlorentzen]

A very similar thing is happening to us with the new version of react-query as it defines react-native as a optional peer dependency.

This causes all our webprojects that use react-query to install react-native which is not only unneccessary, but also easily causes build issues as react-native has very different requirements from a simple webproject.

It is also limiting as react-native doesn't seem to support React v18.2.0, forcing us to downgrade to v18.0.0 all because of an optional peer dependency that we do not use or need.

[deanohyeah]

For anyone experiencing optional peers being installed, my case was due to using artifactory.
They have an open ticket.
https://www.jfrog.com/jira/browse/RTFACT-27265

[DevRCRun]

We've recently run into this as well. It seems that an optional peer dependency of a top level dep will be marked in the package-lock.json as devOptional if it is also a dependency of a dev dep. This leads to the weird situation where it then gets installed in a production build (--omit=dev) unless you also --omit=optional

[IanVS]

I am a bit confused as to the current state. Does the latest npm still automatically install optional peers? I see a few links to issues that seem to indicate it was fixed, but then others are saying it's still a problem. Is there an issue tracking it? I couldn't find one so far.

[robkorv]

I'm using npm@9.4.2 and I now have the problem that optional dependencies are not installed. I can't find any info on which npm command or flag to use to install any of the optional dependencies.

See https://github.com/getsentry/sentry-capacitor/blob/8463cee3ce4980ea2dfdc0229bfd20a577c720c6/package.json#L39-L55.
How do I make sure the optional peer dependency "@sentry/vue" gets installed when running npm install --save @sentry/capacitor@latest? This should also be registered in the "package.json" and/or "package-lock.json" so that someone else uses the same project will also get the peer dependency.

For now I will install the option peer dependency manually with npm install --save @sentry/vue or is this always the way to go for optional peer dependencies from now on?

[mrgrain]

I'm encountering the same issue. As of npm@9.7.1 there is no way to install optional peer dependencies.

[stof]

@robkorv that's exactly how optional peer dependencies are meant to be installed. A peer dependency is a dependency that is expected to be installed as a peer of the package to reuse the dependency of the parent package. npm has a shortcut where it automatically install mandatory peer dependencies even if the parent package does not depend on them (implicitly adding some dependencies in the parent). It does not do that for optional ones as there are legitimate reasons not to install them (otherwise, it would not be marked as optional)

[mrgrain]

@stof I agree that this shouldn't be the default. What's confusing is that optional dependencies can be installed and the whole behavior around optional peer deps isn't documented.

My use case is automation. It's not the end of the world for me since I can parse the package.json file myself, but it would be nice to have a way to install all (really all) things a package might depend on.

Maybe supporting a flag like --include=optional-peers would be a good compromise.

[glitch-txs]

am I missing something, I'm using npm v10.4.0 and optional peer deps are being installed, biggest concern is I'm use Vite for bundling and it's bundling these opt peers