Peer Dependency Versions

Peer dependency versions specify which versions of external packages a design system expects consumers to provide. Common peer dependencies include React, Vue, or Angular for framework-specific design systems. Managing peer dependency versions affects compatibility, consumer flexibility, and upgrade experiences.

What Are Peer Dependency Versions

Peer dependencies are packages that a library expects consumers to install rather than bundling itself. The version specification in peerDependencies defines which versions the library works with. Consumers must ensure their installed versions satisfy these requirements.

For design systems, peer dependencies commonly include UI frameworks, build tools, or other foundational libraries. A React design system might peer depend on React 17 or 18. The peer dependency version range determines which React versions consumers can use with the design system.

How Peer Dependency Versions Work

Peer dependency management involves specifying appropriate ranges, communicating requirements, and coordinating updates. Each aspect affects consumer experience.

Range specification defines which versions are supported. Broad ranges like >=17.0.0 support many versions but may not work with all. Narrow ranges like ^18.2.0 ensure compatibility but limit consumer flexibility. The range should reflect actual tested compatibility.

Installation behavior varies by package manager. npm 7+ auto-installs peer dependencies, creating potential conflicts. Earlier npm and yarn warn but do not auto-install. Understanding this behavior helps predict consumer experiences.

Conflict resolution handles cases where multiple packages require different peer dependency versions. If two design system packages require different React versions, consumers face conflicts. Avoiding conflicts through compatible ranges benefits consumers.

Key Considerations

• Test against all versions in the supported range
• Document supported versions clearly
• Consider major version support timelines
• Coordinate peer dependency changes with major releases
• Communicate changes prominently in release notes

Common Questions

How broad should peer dependency ranges be?

Range breadth balances compatibility with reliability. Broader ranges support more consumers; narrower ranges ensure tested compatibility.

Supporting multiple major versions maximizes consumer flexibility. A React peer dependency of ^17.0.0 || ^18.0.0 supports both React 17 and 18. This range requires testing against both and maintaining compatibility, but consumers on either version can use the design system.

Limiting to current versions reduces maintenance burden. Supporting only ^18.0.0 means focusing testing and development on React 18. Consumers on React 17 must upgrade or use older design system versions.

The decision depends on consumer characteristics. If many consumers are on older framework versions, broader support helps adoption. If most consumers stay current, focused support on recent versions is reasonable.

Regular range review ensures ranges reflect reality. As older framework versions become rare, removing them from peer dependency ranges simplifies maintenance. Communicate these changes in major releases.

How should peer dependency changes be communicated?

Peer dependency changes affect consumers significantly and require clear communication. Several practices help consumers adapt.

Major version releases are the appropriate time for peer dependency changes. Changing supported framework versions is a breaking change. Consumers may need to upgrade their framework before upgrading the design system.

Release notes should highlight peer dependency changes prominently. Burying this information among other changes risks consumers missing it. Clear statements like “This release requires React 18 or higher” prevent surprise.

Migration guides help consumers adapt. If dropping React 17 support, explain what consumers on React 17 should do. Options might include upgrading React, staying on the previous design system version, or following a specific migration path.

Deprecation warnings before removal give advance notice. Announcing in version 4.x that version 5.x will drop React 17 support helps consumers plan ahead.

Summary

Peer dependency versions define which external package versions design systems support. Range specification balances consumer flexibility with tested compatibility. Clear communication of peer dependency requirements and changes helps consumers manage their dependencies effectively.