Glossary / Peer dependencies
Peer dependencies
A peer dependency declares that a package expects to integrate with a host package supplied at a compatible version, rather than privately bundling an independent copy. It is common for plugins, adapters, framework components, and packages that depend on shared runtime identity or singleton context.
Resolution and compatibility
For example, a React component library may declare react as a peer so the application and library use a compatible host instance. npm 7 and later attempt to install peer dependencies automatically, while older npm versions generally warned and left installation to the user. Conflicting peer ranges across the tree can make resolution impossible or require a deliberate compatibility decision. Package managers differ in how strictly they report or resolve conflicts.
peerDependenciesMeta can mark a peer optional. This means the host integration may be absent, so the package must guard imports/behavior and document the feature. Optional peer does not imply that all package managers install it automatically.
Choosing ranges and diagnosing conflicts
A peer range is a public support claim. Use the widest range that is genuinely tested and compatible; do not pin to one patch release without a reason. Include supported prereleases only intentionally. Duplicate framework copies can break hooks, context, identity comparisons, or plugin registries even when APIs look compatible.
Diagnose with package-manager explain/tree commands, inspect every peer edge and workspace resolution, and test representative host versions. Avoid --legacy-peer-deps as a permanent fix because it suppresses the contract rather than reconciling it. If ranges cannot coexist, update packages or isolate integrations explicitly.
Interview questions
- Why peer instead of dependency? The consumer should provide a shared compatible host instance.
- What changed with npm 7? npm began installing peers by default, while conflicts can now affect resolution.
- What does optional peer metadata imply? The integration may be absent and code must handle that condition.
- Why not pin a peer to one patch? It unnecessarily excludes compatible hosts and creates conflicts.
- What failures can duplicate React copies cause? Invalid hook calls, disconnected contexts, or identity mismatch.