skip to content

In a component library built on a UI framework, why is that framework declared as a peer dependency rather than bundled as a regular dependency?

level: juniorimportance: should knowfreq 45%

answer

  1. one framework instance per app
  2. who supplies the copy
  3. duplicate instances break shared state
  4. range matches what is tested
  5. the host decides the version

basics

~20 s

An app must run a single copy of its UI framework; declaring it a peer makes the app supply that copy, avoiding duplicate instances that break shared state and double the download, while the range states which versions work.

solid answer

~40 s

A UI framework keeps internal state - its rendering scheduler, its component bookkeeping, values shared down the tree - that works only when every component on the screen uses the same instance. If the library listed the framework as a regular dependency, an app could end up with two copies: its own and the library's. That doubles the download and can break things subtly, from shared values never reaching library components to outright runtime errors. A **peer dependency** says 'I need this, but the host provides it', so the app installs one copy and the library uses it. The peer range should list exactly the framework majors the library is tested against, and the library's own development setup installs the framework separately so its tests still run.

go deeper

for a junior

Recall that a peer dependency is supplied by the host app, and that the UI framework must exist once per app so every component shares its state.

for a middle

Explain what breaks with two framework instances and why the peer range should match the majors the library actually tests.

for a senior

Show you can diagnose a duplicate-framework symptom in a consuming app and decide which other packages, such as tokens, deserve peer status.

for a principal

Weigh supporting several framework majors at once against the testing cost, and set a policy for when the library drops an old major.

## Regular versus peer dependencies A **regular dependency** is something a package needs and brings along: installing the package installs it too, possibly as a private copy. A **peer dependency** is something a package needs but expects its *host* to provide: installing the package does not add a separate copy, and the package manager checks that the host's version falls inside the declared range. For a **component library** - the coded components of a design system, consumed by many apps - the UI framework the components render with is the textbook peer. ## Why two copies of a framework hurt - **Shared state splits.** A framework tracks rendering work, component identity and values provided down the component tree inside one instance. Components from a second instance live in a parallel world, so a theme or locale the app provides may never reach them. - **Runtime errors.** Some frameworks detect components from another instance and fail loudly; others misbehave quietly. - **Double download.** A telecom self-service app would ship the framework twice, often the largest single dependency it has. - **Version drift.** The library's private copy upgrades on the library's schedule, not the app's, so two versions of the framework can run side by side. ## Choosing the peer range The range is a promise: 'these framework versions work with this library'. Making it honest: 1. **Test every major in the range.** If the library's CI runs against two framework majors, the peer range covers those two and no more. 2. **Widen deliberately.** When a new framework major is tested and passes, widening the range is backward-compatible for consumers. 3. **Narrowing is breaking.** Dropping support for an older framework major forces some consumers to upgrade before they can take the release. 4. **Avoid version promiscuity.** The semantic versioning spec calls assuming compatibility with more future versions than is reasonable 'version promiscuity'; an open-ended peer range does exactly that. ## What belongs as a peer | Dependency | Peer or regular | Why | |---|---|---| | The UI framework itself | Peer | Must be one shared instance chosen by the app | | The framework's rendering package for the platform | Peer | Tied to the framework instance and version | | The design system's token package | Usually peer | The app may theme it and must not load two versions | | A small internal helper | Regular | No shared state; consumers should not have to install it | ## Recognising a duplicate framework in an app When a library gets this wrong, the symptoms rarely point at packaging: - A theme, locale or other value the app provides reaches the app's own components but not the library's. - The framework reports an error about invalid usage or mismatched instances that appears only when library components render. - A bundle report shows the framework's code twice, sometimes at two different versions. - The installed dependency tree lists the framework both at the top level and nested under the library. The fix is to declare the framework as a peer, let the app's single copy satisfy it, and align versions so the package manager has one copy to install. ## The development-time catch A peer is not installed for the library itself, so the library's own repository installs the framework as a development-only dependency. Without that, its tests and workshop would have no framework to run against. ## The native mobile parallel Native component libraries meet the same idea as a platform constraint: the app decides the operating-system SDK and minimum version, and the library declares the minimum it supports rather than bringing its own. The shape is identical - the host owns the shared runtime, and the library states which versions of it are compatible. The interview point is the reason, not the syntax: the host must own anything that has to exist exactly once, and the library's job is to state honestly which versions of it are supported.

  • How wide should the peer range on the UI framework be?
    Exactly as wide as the library's CI tests. If the suite runs against two framework majors, the range covers those two; widening it to an untested major invites breakage consumers will blame on the library. Adding a newly tested major is backward-compatible, while dropping one forces some consumers to upgrade, so it is a breaking change.
  • What happens when an app's framework version falls outside the library's peer range?
    Depending on the package manager, the install warns or fails. Forcing past it means running an untested combination: it may work, or fail in ways neither team's tests cover. The fix is upgrading one side, or the library testing and widening its range.
  • Should small utility dependencies also be peers?
    Usually not. A peer is for something that must be a single shared instance or that the host must choose - the UI framework, its rendering package, often the token package. Ordinary helpers stay regular dependencies so the library works out of the box; making everything a peer pushes installation chores onto every consumer.

saying these in an interview costs you the question

  • Bundling the framework inside the library makes it safer and self-contained.
  • The peer range should be as wide as possible to avoid install warnings.
  • Two copies of the framework only cost bandwidth, nothing else.
  • Dropping support for an old framework major is a minor change.
  • Every dependency of a component library should be a peer.