What are peerOptional dependencies?

[everett1992]

🏷️ Discussion Type

Question

Body

I'm strugging to understand how peerOptional dependencies should behave, and what might be a bug.

peerOptional are edges declared in peerDependencies and peerDepsMeta[name].optional

{
  "name": "lib"
  "peerDependencies": { "shared": "^1.0.0" },
  "peerDepsMeta": { "shared": { "optional": true } }
}

shared^1.0.0 is a peerOptional dependency of lib.

npm's package.json docs say this about peerDependenciesMeta

Npm will not automatically install optional peer dependencies

This is different from optionalDependencies, which npm says

npm [will] proceed if it cannot be found or fails to install

But what does npm actually do with peerOptionals? What's the difference between not declaring a dependency at all?
My guess would be that npm will warn, error, or build a different node_modules to prevent the peerOptional dependency from being resolved to a package that doesn't satisfy the dependency.

node_modules/shared@2.0.0 // npm should not allow  this, because it conflicts with peerOptional ^1.0.0
node_modules/lib

There's a test that checks this, 'properly fail on conflicted peerOptionals'
That covers a case where it's impossible to satisfy both requirements because they must both go to node_modules/shared.
There's another case that covers detect conflicts in transitive peerOptional deps.
In this test the conflict can be avoided by nesting the non-peer.

But npm nests the required dependency by fetching the peerOptional edge

  root/                                                                                                  
    nm/has-peer          → peer(peer@1)                                                                  
    nm/meta-peer         → dep(has-peer)                                                                 
    nm/meta-peer-optional/                                                                               
      nm/has-peer-optional  → peerOptional(peer@2)                                                       
      nm/peer@2             ← FETCHED and nested here                                                    
    nm/peer@1              ← at root, satisfies has-peer

That feels like it doesn't match the docs, npm did automatically fetch peer@2 to satisfy a peerOptional, but only because it would have conflicted otherwise. I'm not sure how else npm could solve the conflict tho. I think ideally has-peer-optional would be placed so it can't resolve peer (it's optional anyway). But that's not possible due to has-peer.

Question is related to this issue, which I'm trying to fix.
In this case nm/jest-util@28 is placed by @types/jest@28, Then jest@29 has to nest nm/jest-a/nm/jest-util@29, nm/jest-b/nm/jest-util@29, ect (21 copies of jest-util@29). When ts-jest is placed it conflicts with nm/jest-util@28, pushing it into nm/@types/jest/nm/jest-util. **But instead of de duplicating and hoisting the 21 copies of jest-util@29 that satisfy the peer-dependency it fetches a version that only satisfies the peerOptional edge (jest-util@30).

In subsequent npm install's the jest-util@30 edge is marked extraneous and removed, so the second install produces different results.

The observed behavior technically matches the 'detect conflicts in transitive peerOptional deps' test, and it feels valid, but bad.

• Optional does not mean "never install" so it's fair that npm would fetch jest-util@30 as a way to de-conflict.
• But creating a tree that cannot be reproduced on subsequent installs in wrong.
• And installing a 3rd version, when npm could have hoisted jest-util@29 is suboptimal
• Leaving a whole in the graph (like subsequent installs, with extraneous removed) seems correct as well.

https://github.com/npm/cli/tree/latest/workspaces/arborist

[cookesan]

peerOptional still creates a peer dependency edge with a version constraint. The optional part means npm will not install that peer only because this package names it.

It does not mean "ignore the constraint if the peer is present." If some other dependency causes shared to be placed where lib will resolve it, npm still has to consider lib's peer range. If the placed version conflicts with the optional peer range and the tree cannot be arranged to satisfy both, an ERESOLVE is expected.

The difference from not declaring the dependency is the compatibility contract:

not declared        npm has no peer relationship to enforce
peer optional       absent is allowed, but present must be compatible
regular peer        npm may install it and present must be compatible
optionalDependency  npm tries to install it, but install/build failure is allowed

So your guess is basically right: npm should not install or leave an incompatible peer at the resolution point just because the peer was marked optional.

[Pratikchetry]

The Contract — Precisely Stated
peerOptional deps are listed in peerDependencies and also have an entry in peerDependenciesMeta containing {"optional": true}. These are not installed by default, but if installed, must be resolved to a version that satisfies the optional peer dependency relationship. Thus, if foo had a peerOptional dependency on bar@1, you could not install both foo and bar@2 at the top level.

Why Arborist Nested peer@2 — It's Correct Behavior
Your specific tree:
nm/has-peer → peer(peer@1)
nm/meta-peer → dep(has-peer)
nm/meta-peer-optional/
nm/has-peer-optional → peerOptional(peer@2)
nm/peer@2 ← fetched here
nm/peer@1 ← satisfies has-peer

This is the correct resolution, not a bug. Here's what Arborist is reasoning through:

peer@1 is placed at root to satisfy has-peer's regular peer dep.
has-peer-optional declares peerOptional(peer@2) — conflicting with peer@1 at root.
Because foo has a peer dep on bar, and foo is installed at .../node_modules/foo, npm may not install bar at .../node_modules/foo/node_modules/bar. It must be placed at foo's level or higher. GitHub
But since meta-peer-optional itself is nested, Arborist CAN place both has-peer-optional and peer@2 inside nm/meta-peer-optional/node_modules/, avoiding the conflict entirely. This is the tree solver doing its job — it found a valid arrangement.

The key insight: Arborist doesn't "fetch peer@2 to satisfy a peerOptional." It fetches peer@2 because a conflict was detected and a valid nesting resolution existed. If no valid nesting were possible, it would correctly ERESOLVE.

When Does Arborist Correctly ERESOLVE?
The solution Arborist uses is to include peerOptional edges when building the peerSet (so conflicts are detected), but still omit missing peerOptional deps when looking for invalid edges needing further resolution.

Historical Context: This Was a Real Bug Area
Early versions of Arborist did not add peerOptional edges to the peerSet at all. This meant a peerOptional(k@2) dep would not be seen as conflicting with an existing k@1, so the package would get placed at root, and then ERESOLVE would fire later when the invalid edge was discovered — the wrong error at the wrong time. GitHub The fix was to include peerOptional in peerSet construction while still not requiring them to be fetched when absent.

Bottom Line
Your intuition that "npm shouldn't allow node_modules/shared@2.0.0 when lib has peerOptional shared@^1.0.0" is exactly correct and is the enforced behavior. What you observed with peer@2 being nested is not npm violating this rule — it's npm finding the one valid tree arrangement that satisfies all constraints simultaneously. If that arrangement didn't exist, you'd get ERESOLVE.

[alblez]

Hey @everett1992, great question — this one confuses a lot of people, and the npm docs don't do a great job explaining it, so let me try to break it down in a way that actually sticks.

Think of dependencies in npm as different levels of "how much do I need this thing":

A regular dependency means "I need this, install it." An optionalDependency means "try to install it, but if it fails (maybe it needs a native build and the platform doesn't support it), just move on, it's fine." A peerDependency means "I don't install this myself, but whoever uses me needs to have it, and it better be a compatible version." Now peerOptional is the interesting one it means
"If the person using me happens to have this package installed, then it must be a compatible version. But if they don't have it at all, that's perfectly fine too."

The key thing people get wrong: the "optional" part only refers to whether the package needs to be present. It does NOT mean the version constraint is relaxed. If someone has it installed but it's the wrong version, npm treats that as a real conflict — the same as a regular peer dependency.

A real-world example: imagine you write a logging library that can optionally format output nicely if the user has "chalk" installed. You don't need to force everyone to install chalk, but if they do, you'll need v5 because that's the API you coded against. That's a peerOptional — chalk isn't required, but if it is, please use v5.

The package.json looks like this:

     "peerDependencies": { "chalk": "^5.0.0" },
     "peerDependenciesMeta": { "chalk": { "optional": true } }

Under the hood, npm's tree solver (Arborist) handles conflicts by nesting incompatible versions within node_modules subdirectories. If it can't find any arrangement that works, you get the dreaded ERESOLVE error. This happens with peerOptional too — optional doesn't mean "ignore conflicts."

One gotcha worth knowing: in complex dependency trees (like projects using jest + ts-jest), npm sometimes behaves inconsistently with peerOptional — it might fetch a version on first install and then mark it as extraneous on the next one. If you ever see packages appearing and disappearing between installs, this is likely why. It's a known edge case.

Hope that clears things up — it's one of those npm concepts that makes total sense once someone explains it plainly, but is nearly impossible to figure out just from the docs.

[BuildWithNil]

peerOptional dependencies can definitely feel confusing because their behavior sits between peerDependencies and optionalDependencies.

Here’s the practical way to think about them:

---

What is a peerOptional dependency?

It’s a dependency that:

• Must behave like a peer dependency if present

• But is not required to be installed

Defined as:

"peerDependencies": {
  "shared": "^1.0.0"
},
"peerDependenciesMeta": {
  "shared": { "optional": true }
}

---

How npm actually treats it

1. npm does NOT install it by default
If shared is not present anywhere in the tree:

• No install

• No error

• Usually no warning (unlike strict peer deps)

---

2. If it IS present, it must satisfy the version
If some version of shared exists:

• npm tries to ensure it satisfies ^1.0.0

• If not, it may:

  • warn

  • or restructure the tree

---

3. npm may still install it indirectly (important)
Even though it's “optional,” npm can fetch it when:

• Resolving dependency conflicts

• Avoiding invalid peer graphs

This is what you’re observing:

npm fetching jest-util@30 to resolve a conflict

This is not because peerOptional is “auto-installed,” but because:
👉 npm is trying to produce a valid dependency tree

---

Key difference vs other dependency types

Type | Installed automatically? | Required? | Version enforced? -- | -- | -- | -- dependency | ✅ Yes | ✅ Yes | ✅ Yes optionalDependencies | ✅ Yes (but can fail) | ❌ No | ❌ Not strict peerDependencies | ❌ No | ✅ Yes (must exist) | ✅ Strict peerOptional | ❌ No | ❌ No | ✅ Only if present

---

Answer to your core question

What’s the difference from not declaring it at all?

Declaring peerOptional tells npm:

👉 “If this dependency exists, it MUST be compatible.”

Without it:

• npm ignores compatibility entirely

• You risk runtime issues

---

About your observed behavior (important)

What you described:

• npm installing an extra version (jest-util@30)

• Then removing it as extraneous later

• Producing inconsistent trees

This suggests:

👉 npm is making a conflict-resolution decision that isn’t stable across installs

That’s likely:

• A limitation or edge case in Arborist’s resolution algorithm

• Possibly a bug (especially due to non-deterministic installs)

---

What would be ideal behavior?

As you noted, better options could be:

• Prefer existing compatible versions (29) over fetching new ones

• Allow “holes” in optional peer resolution

• Avoid introducing non-reproducible trees

---

TL;DR

• peerOptional = “optional, but must be compatible if present”

• npm doesn’t install it by default

• But may install it during conflict resolution

• Your case likely exposes a non-deterministic resolution issue / edge case

---

If you’re working on fixing this in npm/Arborist, your intuition about preferring deduplication over fetching a new version is spot on.

[everett1992]

These answers didn't really help me. One aspect I'm trying to understand is when peer Optional should be satisfied.

I think a strict package manager like would only satisfy the peerOptional dependency if the direct consumer declared a compatible edge, otherwise it would leave it missing. Npm's hoist optimization already exposes packages to undeclared deps, so it makes sense that hoisting can also satisfy peerOptionals. They are not like 'feature dependencies' where the package can sue their presence to assume the feature was requested - they could just as well be accidentally hoisted.

I ended up implementing a minor fix in this PR, peerOptionals will prefer a node that already exists in the sub-tree instead of resolving a new edge.

npm/cli#9283