[BUG] Scoped npm ci --workspace installs an out-of-scope workspace's optional peer dependency, then reports it as extraneous

[davidsundelius]

Is there an existing issue for this?

• I have searched the existing issues

This issue exists in the latest npm version

• I am using the latest npm

This is not just a request to bump a dependency for a CVE

• This is not solely a request to bump a dependency for a CVE

Current Behavior

Running these commands in the provided repo gives:

npm ci --workspace=pkg-b --include-workspace-root installs sass-embedded, even though:

• pkg-b - is the only workspace in scope and declares no dependencies at all
• sass-embedded is declared only by pkg-a, which is not in scope
• vite (in scope, from the root) declares sass-embedded as an optional peer: peerDependenciesMeta: { "sass-embedded": { "optional": true } }

npm explain then describes the package npm has just installed as extraneous:

$ npm explain sass-embedded
sass-embedded@1.100.0 extraneous
node_modules/sass-embedded
  peerOptional sass-embedded@"^1.70.0" from vite@8.2.1
  node_modules/vite

So the resolver installs it while the explainer reports that nothing requires it.

The optional peer edge alone is not sufficient to cause this. vite also declares less, stylus and terser as optional peers, and none of those are installed, because no workspace declares them. It is the combination of "declared by some workspace anywhere in the monorepo" plus "an in-scope package has an optional peer edge to it" that makes a package survive scoping.

Prior issues I checked

I could not find an existing issue covering this case. The closest are all different:

• [BUG] npm install in workspace root installs optional peer dependencies of workspace package dependencies #2628 - unscoped root install, duplicate versions of a package (no --workspace, and no duplication here)
• [BUG] npm workspace incorrectly flags dependency as optional peer #8489 - the inverse: a package not installed when it should be, workspace-order dependent
• [BUG] installing in a scoped workspace with --omit=dev still installs devDependencies if they are workspace packages #6670 - --omit=dev failing for devDependencies that are themselves workspace packages (not peers; the package here is external)
• Automatic installation of optional peer dependencies looks weird feedback#225 - general objection to auto-installing optional peers, not scoping-specific

Happy to close as a duplicate if I've missed one.

Why this matters

In a monorepo where each CI pipeline builds a single app, a scoped install is expected to fetch only that app's dependency closure. Packages pulled in this way tend to be large native toolchains. sass-embedded here is roughly 40 MB plus a platform-specific binary, so every pipeline pays to download and cache a compiler its app never invokes. There is no flag that removes it without also removing genuinely needed optional dependencies such as esbuild, rollup, or lint binaries.

Expected Behavior

--workspace=pkg-b should not install a package that is reachable only from an out-of-scope workspace. Either it should be pruned like any other out-of-scope dependency (which I would prefer), or — if installing it is intentional — npm explain should not then report it as extraneous.

Steps To Reproduce

Repro repo: https://github.com/davidsundelius/npm-workspace-optional-peer-repro

Three files:

package.json

{
  "name": "npm-workspace-optional-peer-repro",
  "version": "1.0.0",
  "private": true,
  "workspaces": ["pkg-a", "pkg-b"],
  "devDependencies": { "vite": "^8.0.0" }
}

pkg-a/package.json

{ "name": "pkg-a", "version": "1.0.0", "devDependencies": { "sass-embedded": "^1.97.3" } }

pkg-b/package.json

{ "name": "pkg-b", "version": "1.0.0" }

Then:

1. npm install --package-lock-only
2. npm ci --workspace=pkg-b --include-workspace-root
3. ls node_modules/sass-embedded → present
4. npm explain sass-embedded → extraneous

Control, which isolates the cause

Change pkg-a to declare lodash (no peer edge from any installed package) instead of sass-embedded, and repeat. lodash is correctly pruned.

This rules out the simpler explanation that devDependencies of out-of-scope workspaces are never pruned — they are. Only the ones with an optional peer edge from an in-scope package survive.

Environment

Reproduced on every version tested, so this does not appear to be a recent regression:

npm	result
10.9.2	sass-embedded installed
11.4.2	sass-embedded installed
11.6.0	sass-embedded installed
11.12.1	sass-embedded installed
12.0.2 (latest)	sass-embedded installed

• npm: 12.0.2
• Node.js: v25.9.0
• OS Name: macOS 26.6
• System Model Name: Apple Silicon (arm64)

Note: npm 12.0.2 warns that it does not support Node v25.9.0. The behaviour is identical on the earlier npm releases listed above, which do support the Node version used.