Lerna – Monorepo Management Tool for JavaScript/TypeScript

Overview

Lerna is an open-source command-line interface (CLI) tool designed to manage multi-package repositories, often referred to as monorepos, primarily within the JavaScript and TypeScript ecosystems. Since its inception in 2015, Lerna has aimed to streamline the development processes associated with maintaining multiple interdependent packages within a single Git repository. Its core utility lies in abstracting away much of the complexity involved in managing cross-package dependencies, running scripts across various packages, and orchestrating the publishing of updated packages to registries like npmjs.com.

Developers use Lerna to consolidate related projects into one repository, which can offer benefits such as simplified dependency management, easier code sharing, and atomic changes across packages. For example, if a team maintains a UI component library, a core utility library, and several applications that consume these libraries, a Lerna monorepo can enable a single pull request to update a component, its consuming application, and the associated tests simultaneously. This approach can reduce overhead compared to managing several individual repositories.

Lerna provides commands for bootstrapping a monorepo, which involves installing root and package-specific dependencies and symlinking local packages to each other, allowing them to be consumed as if they were installed from a registry. It also offers mechanisms for executing scripts in parallel or sequentially across all packages, or a subset of them, based on changes detected since the last release. The publishing workflow is another key feature, automating the versioning and publication of updated packages to public or private npm registries, with options for independent or fixed versioning strategies.

While Lerna historically filled a critical gap in JavaScript monorepo management, the landscape has evolved with the emergence of integrated build systems like Nx and Turborepo. Lerna itself became part of the Nx ecosystem when it was acquired by Nrwl, the creators of Nx. This acquisition has led to renewed development activity and a strategic alignment, with Lerna continuing to focus on its core strengths while leveraging insights from the broader monorepo tooling space. It is particularly well-suited for teams looking for a dedicated solution for publishing and dependency management in JavaScript/TypeScript monorepos without requiring the full suite of build optimization features offered by more comprehensive build systems.

Key features

• Multi-package repository management: Organizes multiple distinct packages within a single Git repository, enabling shared dependencies and simplified development workflows.
• Dependency bootstrapping: Automatically installs all dependencies for every package in the monorepo and symlinks local packages, making them available for development without manual configuration.
• Package linking: Establishes symbolic links between interdependent local packages, allowing them to reference each other as if they were installed from a package registry like npm.
• Version management: Supports both fixed (synchronized) and independent versioning strategies for packages, allowing teams to choose how package versions are incremented and released.
• Automated publishing: Streamlines the process of publishing updated packages to npm or other registries, including version bumping, Git tagging, and changelog generation.
• Command execution across packages: Provides commands to run arbitrary shell scripts or npm scripts across all packages, or only those that have been modified, with options for parallel execution.
• Change detection: Identifies which packages have been modified since the last release, enabling targeted command execution and publishing, which can speed up CI/CD pipelines.

Pricing

Lerna is an open-source project distributed under the MIT License. It is fully free to use for all purposes, including commercial projects.

Common integrations

• npm: Lerna integrates directly with npm for dependency installation, linking, and package publishing.
• Yarn: Compatible with Yarn Workspaces, allowing Lerna to leverage Yarn's efficient dependency management for monorepos.
• Git: Uses Git for change detection, version control, and tagging releases during the publishing process.
• GitHub/GitLab: Often used in conjunction with CI/CD pipelines on platforms like GitHub Actions or GitLab CI for automated testing and deployment of monorepos.
• TypeScript: Fully supports TypeScript projects, enabling efficient management of typed multi-package repositories.

Alternatives

• Nx: A powerful build system and monorepo tool from Nrwl, offering advanced caching, task orchestration, and code generation beyond Lerna's core features.
• Turborepo: A high-performance build system for JavaScript and TypeScript monorepos, focused on optimizing build times through caching and parallel execution.
• Yarn Workspaces: A feature of the Yarn package manager that provides basic monorepo capabilities, primarily focused on dependency management and linking.
• pnpm Workspaces: Similar to Yarn Workspaces, pnpm's workspace feature offers efficient monorepo support with a focus on disk space efficiency and strict dependency resolution.
• Rush: A scalable monorepo manager from Microsoft, designed for very large repositories and providing features like custom command execution and build cache.

Getting started

To initialize a new Lerna monorepo, you first need to set up a new project directory and initialize it as a Git repository and an npm project. Then, install Lerna and use the lerna init command to set up the basic monorepo structure. This example demonstrates how to create two simple packages, package-a and package-b, within the monorepo.

# 1. Create a new project directory and navigate into it
mkdir my-lerna-repo
cd my-lerna-repo

# 2. Initialize it as a Git repository
git init

# 3. Initialize it as an npm project
npm init -y

# 4. Install Lerna locally
npm install lerna --save-dev

# 5. Initialize Lerna in the current repository (creates lerna.json and 'packages' directory)
npx lerna init

# The 'packages' directory will be created. Let's create two example packages.
mkdir packages/package-a
mkdir packages/package-b

# Create a simple index.js and package.json for package-a
echo 'module.exports = "Hello from package A!";' > packages/package-a/index.js
json_a='{"name": "package-a", "version": "1.0.0", "main": "index.js"}'
echo $json_a > packages/package-a/package.json

# Create a simple index.js and package.json for package-b
echo 'const packageA = require("package-a");\nconsole.log("Hello from package B!" + " " + packageA);' > packages/package-b/index.js
json_b='{"name": "package-b", "version": "1.0.0", "main": "index.js", "dependencies": {"package-a": "^1.0.0"}}'
echo $json_b > packages/package-b/package.json

# 6. Bootstrap the monorepo to link packages and install dependencies
npx lerna bootstrap

# 7. Run package-b to see the cross-package dependency in action
npm run --prefix packages/package-b start # Add "start": "node index.js" to package-b's package.json scripts

# Expected output for package-b start: "Hello from package B! Hello from package A!"

This setup demonstrates the fundamental steps to get started with Lerna, including initializing the repository, creating individual packages, defining dependencies between them, and using lerna bootstrap to establish the necessary links for local development. Further configuration in lerna.json allows for fine-tuning versioning strategies, command execution, and publishing behavior.