Lerna Versioning

Lerna versioning manages versions and releases for monorepo design systems. Lerna provides commands for version bumping, changelog generation, and publishing across multiple packages. It supports both fixed and independent versioning modes, adapting to different package relationship patterns.

What Is Lerna Versioning

Lerna is a monorepo management tool that handles versioning and publishing for JavaScript projects containing multiple packages. For design systems, Lerna coordinates version bumps, generates changelogs, and publishes packages to npm. It reduces the complexity of managing multiple related packages.

Lerna has evolved over its history and is now maintained by the Nx team. Modern Lerna integrates with Nx for additional capabilities. However, core versioning functionality remains consistent, making existing Lerna knowledge applicable.

How Lerna Versioning Works

Lerna versioning operates through its version and publish commands. Configuration determines versioning mode and behavior.

Fixed mode assigns the same version to all packages. The lerna.json file specifies a single version that applies everywhere. Running lerna version bumps all packages to the new version regardless of which packages changed. This ensures version alignment across the monorepo.

Independent mode allows per-package versions. Setting “version”: “independent” in lerna.json enables independent versioning. Lerna prompts for version bumps for each changed package. Packages unchanged since their last publish are not prompted.

Version determination uses conventional commits when configured. Lerna can analyze commits to determine appropriate version bumps automatically. This integrates with conventional commit workflows for automated semantic versioning.

Changelog generation creates per-package changelogs. Lerna generates CHANGELOG.md files in each package from commit messages. Conventional commit types map to changelog sections.

Key Considerations

• Choose fixed or independent mode based on package relationships
• Configure conventional commits for automated version determination
• Understand how Lerna detects changed packages
• Set up proper npm authentication for publishing
• Consider Nx integration for additional capabilities

Common Questions

How does Lerna detect which packages changed?

Lerna determines changed packages by comparing against the last version tag. Understanding this detection helps predict Lerna behavior.

Git tags mark previous releases. Lerna looks for tags following its naming convention (package@version or v1.2.3). Changes since the most recent tag are considered.

File changes within package directories flag packages as changed. If any file in a package’s directory changed since the tag, the package is considered changed.

Dependency changes can propagate. If package A changed and package B depends on A, Lerna can optionally consider B changed too. This ensures consumers of changed packages receive updates.

Manual inspection using lerna changed shows which packages Lerna considers modified. This preview helps verify expectations before versioning.

What are common Lerna versioning issues?

Several issues frequently affect Lerna versioning. Understanding these helps prevent or resolve them.

Tag mismatches cause Lerna to miscalculate changed packages. If git tags do not reflect actual published versions, detection fails. Ensuring tags and npm versions stay synchronized prevents issues.

Independent mode complexity increases with package count. Manually specifying version bumps for many packages is tedious. Conventional commits automation reduces this burden.

Publishing partial failures leave the monorepo in inconsistent states. If some packages publish but others fail, manual intervention is needed. Understanding recovery procedures helps address these situations.

Migration to Lerna requires setting up tags and configuration. Starting fresh is straightforward, but adopting Lerna for existing projects requires establishing the initial state that Lerna expects.

Summary

Lerna versioning manages version bumps, changelogs, and publishing for monorepo design systems. Fixed and independent modes accommodate different package relationship patterns. Configuration and conventional commit integration enable automated version determination and changelog generation.