Monorepo Versioning

Monorepo versioning manages versions for multiple design system packages housed in a single repository. When design systems split functionality across multiple packages (components, tokens, utilities), coordinating their versions becomes important. Monorepo versioning strategies determine whether packages share versions or evolve independently.

What Is Monorepo Versioning

Monorepo versioning addresses the challenge of managing multiple packages within one repository. Unlike single-package repositories where versioning is straightforward, monorepos must decide how package versions relate to each other. The choice affects consumer experience and maintenance complexity.

Two primary strategies exist: fixed versioning (all packages share the same version) and independent versioning (each package has its own version). Hybrid approaches combine elements of both. The right choice depends on how packages relate and how consumers use them.

How Monorepo Versioning Works

Monorepo versioning requires tooling to manage version numbers, changelogs, and publishing across packages. Several tools support this workflow.

Fixed versioning assigns the same version to all packages. When any package changes, all packages receive version bumps. This ensures all packages at version 5.0.0 are compatible. Tools like Lerna in fixed mode support this approach.

Independent versioning allows each package to evolve separately. Changes to one package do not affect others’ versions. This prevents unnecessary version inflation but requires tracking compatibility between packages. Lerna in independent mode and Changesets support this approach.

Version coordination ensures related packages work together. In independent versioning, peer dependency ranges must be maintained carefully. Compatibility matrices help consumers understand which versions work together.

Release coordination publishes multiple packages atomically. Even with independent versions, releasing related changes together prevents intermediate incompatible states. Tooling handles the complexity of coordinated multi-package releases.

Key Considerations

• Choose strategy based on package relationships and consumer needs
• Use tooling designed for monorepo versioning
• Document version compatibility clearly
• Coordinate releases of related changes
• Consider consumer experience when packages have interdependencies

Common Questions

When should design systems use fixed versus independent versioning?

The choice depends on package coupling and consumer usage patterns. Each approach has tradeoffs that fit different situations.

Fixed versioning suits tightly coupled packages. If most consumers use multiple packages together and packages frequently change in tandem, fixed versioning simplifies the mental model. Consumers know version 5.0.0 of all packages are compatible.

Independent versioning suits loosely coupled packages. If packages evolve at different rates and consumers often use subsets, independent versioning prevents unnecessary updates. A change to an obscure utility package does not bump the components package version.

Hybrid approaches apply different strategies to different package groups. Core packages might use fixed versioning while peripheral packages version independently. This complexity requires clear documentation but can optimize for actual package relationships.

How do tools like Changesets handle monorepo versioning?

Changesets provides a developer-friendly approach to monorepo versioning. Understanding its workflow helps teams adopt it effectively.

Developers create changeset files describing their changes. These markdown files specify which packages changed and the change type (major, minor, patch). Change descriptions become changelog entries.

Versioning happens at release time. A version command aggregates changesets, determines appropriate version bumps for each package, updates package.json files, and generates changelogs. This batch processing avoids versioning during development.

Publishing releases updated packages to npm. The publish command identifies packages with new versions and publishes them. Coordination ensures all packages in a release are published together.

The changeset approach works for both fixed and independent versioning through configuration. Teams can adopt the workflow regardless of versioning strategy choice.

Summary

Monorepo versioning manages versions across multiple packages in a single repository. Fixed versioning shares versions across packages while independent versioning allows separate evolution. Tooling like Lerna and Changesets supports monorepo versioning workflows regardless of strategy choice.