skip to content

With npm 7 or later, how does npm treat a component library's `peerDependencies`, and what changes when `peerDependenciesMeta` marks one peer optional?

level: middleimportance: must knowfreq 22%

answer

  1. a host the consumer provides
  2. one shared copy, not a private one
  3. npm 3 to 6 only warned
  4. installed by default since npm 7
  5. optional: true means not auto-installed

basics

~20 s

Since npm 7, a library's non-optional peerDependencies are installed automatically, so the app and the library share one copy of the host. A peer marked optional: true in peerDependenciesMeta is not installed; the app adds it when needed.

solid answer

~50 s

`peerDependencies` say "I plug into a host that you, the consumer, provide": `@fleetline/charts` declares its UI framework there so it runs against the app's copy instead of bundling a second one. In npm 3 to 6 peers were never installed, only warned about; since npm 7 npm installs non-optional peers by default and places them where the library and the app share one copy, so an app that already lists the framework at a compatible version simply satisfies the peer. `peerDependenciesMeta` with `"optional": true` tells npm not to install that peer automatically: the date adapter only matters if the app uses date axes, so the app installs it itself, and the library must cope when it is absent. That differs from `optionalDependencies`, which npm does try to install. If the app's version falls outside a peer range, the install can stop with an `ERESOLVE` conflict.

code

json · 13 lines
json
{
  "name": "@fleetline/charts",
  "version": "3.2.0",
  "peerDependencies": {
    "viewlib": "^4.0.0",
    "date-adapter": "^2.0.0"
  },
  "peerDependenciesMeta": {
    "date-adapter": {
      "optional": true
    }
  }
}

go deeper

for a junior

Recall that a peer is a host the app provides, and that npm 7+ installs non-optional peers automatically.

for a middle

Explain why a UI library peers on its framework, how one shared copy is placed, and how an optional peer differs from an optional dependency.

for a senior

Write peer ranges as broad as the library is tested for, and design optional integrations that degrade cleanly when the peer is absent.

for a principal

Decide which integrations a widely used library makes peers, optional peers or bundled code, weighing install size for consumers against conflict risk.

## What a peer dependency declares Most dependencies are private: a package lists them, npm installs them, and the package uses its own copy. A **peer dependency** is a different promise. It says the package is a plugin or extension for a **host** package, and that it must run against the copy of that host the consuming project uses. A component library is the textbook case. `@fleetline/charts` renders inside the dispatch dashboard's UI framework (call it `viewlib`). If the library listed `viewlib` under `dependencies`, its range could resolve to a separate copy, and two copies of a UI framework in one app break shared state, context and component identity. Declaring it as a peer makes the contract explicit: one `viewlib`, chosen by the app, compatible with the range the library declares. npm's docs give the guidance for writing that range: keep it as broad as the library honestly supports, because other plugins may peer on the same host, and a narrow range is what produces conflicts. ## What npm does with peers, by release | npm release | Non-optional peer missing from the tree | Peer marked optional | |---|---|---| | 3 to 6 | not installed; a warning if an invalid version was found | not installed | | 7 and later | **installed by default**, placed so the library and the app share it | not installed | Since npm 7 a fresh install of `@fleetline/charts` into a project with no `viewlib` installs `viewlib` too. If the dashboard already declares `viewlib` in its own `dependencies` at a version inside the library's peer range, that copy satisfies the peer and nothing extra appears. Most apps still list the host directly, so that the app, not a transitive peer range, decides which version it runs. Two flags change this behaviour, each covered with conflict handling: - `--omit=peer` keeps peers off disk while still planning the tree as if they were there. - `--legacy-peer-deps` makes npm ignore `peerDependencies` entirely, the npm 3 to 6 behaviour. ## Optional peers with `peerDependenciesMeta` The library also supports date axes through an adapter package, but most dashboards never draw one. Installing the adapter for every consumer would be waste, so the library declares it as a peer and marks it optional: - The adapter stays in `peerDependencies` with its supported range, so the compatibility statement is still written down. - `peerDependenciesMeta` adds `{ "date-adapter": { "optional": true } }`, and npm **will not install it automatically**. - An app that wants date axes adds `date-adapter` to its own `dependencies`, picking a version inside the declared range. - The library's code must handle the adapter being absent, for example by loading it lazily and degrading the feature when it is missing. - An app can read both declarations before installing anything with `npm view @fleetline/charts peerDependencies peerDependenciesMeta`, which prints the two fields one after another. The meta field gives npm more information about how a peer listed in `peerDependencies` is used; the range itself lives in `peerDependencies`. ## Peers versus `optionalDependencies` The two "optional" mechanisms are easy to confuse: 1. An **optional peer** is never installed by npm; it is used only if the consumer brought it. 2. An **`optionalDependencies`** entry is installed like a normal dependency, but if it cannot be found or fails to build, npm carries on; `--omit=optional` skips it. 3. A **`bundleDependencies`** entry is packed into the library's own tarball, so it arrives for everyone; peers cannot be bundled. For a library that integrates with a host only when the host is present, the optional peer is the right tool; `optionalDependencies` suits a package the library itself wants, such as a faster native implementation with a JavaScript fallback. ## Writing the entries `npm install viewlib --save-peer` saves the host into `peerDependencies`. The optional flag lives in `peerDependenciesMeta`, which you write in the manifest by hand or with `npm pkg set` plus `--json` for the boolean. A library usually keeps a copy of the host in its own development install too, so its tests run against a real version. When the app's chosen version falls outside a peer range, npm cannot satisfy both and the install can stop with an `ERESOLVE` error; diagnosing that conflict, and deciding between `--legacy-peer-deps`, `--force` and fixing the range, is its own topic.

  • Why not simply list the UI framework under the library's `dependencies`?
    Then the framework is the library's private dependency: whenever its range and the app's do not meet at one version, npm installs a second copy for the library. A UI framework loaded twice splits state and component identity. As a peer, the library promises to use the app's single copy and states the versions it supports.
  • The app never installs `date-adapter`, yet the date axis feature is called. What should happen?
    The library should detect that the optional peer is missing and degrade, for example by throwing a clear error that names the package to install or by hiding the feature. npm will not install an optional peer on its own, so the code path must not assume it is present.

  • npm never installs peer dependencies, it only warns
  • a peer is installed as a private copy under the library
  • optional peers are installed but allowed to fail
  • --omit=peer makes npm plan the tree as if peers did not exist
  • peer ranges should be pinned tightly to one patch version