Lerna

Overview

Lerna is a command-line interface (CLI) tool designed to manage JavaScript and TypeScript projects that adopt a monorepo strategy. A monorepo, short for monolithic repository, is a single repository containing multiple distinct projects or packages. Lerna streamlines the development workflow within such an environment by providing features for linking local packages, distributing commands across multiple packages, and automating the versioning and publishing processes to package registries like npm.

Initially launched in 2015, Lerna became one of the foundational tools for monorepo management in the JavaScript ecosystem. It enables developers to maintain a consistent development setup across related projects, share code more effectively, and simplify dependency management when internal packages depend on each other. For example, a single Lerna command can install dependencies for all packages, run tests across the entire repository, or publish updated versions of multiple packages in a coordinated manner. The tool is particularly well-suited for organizations and teams that develop component libraries, shared utility packages, or multi-application systems that benefit from co-location and atomic changes.

Lerna supports two primary modes for version management: Fixed mode (also known as "synchronized" mode) and Independent mode. In Fixed mode, all packages in the monorepo share a single version number, which is updated together. This is often preferred for component libraries where all parts are released in unison. Independent mode allows each package to have its own version number and be incremented independently, offering more flexibility for projects with distinct release cycles. This approach supports a micro-frontend or microservice architecture within a single repository, where individual services evolve and deploy at their own pace.

While Lerna provides core monorepo functionalities, its capabilities for advanced task orchestration and caching have been extended through its integration with Nx. Since being acquired by Nrwl, the company behind Nx, Lerna has increasingly leveraged Nx's underlying technology to offer enhanced build performance and more sophisticated dependency graphing for tasks like incremental builds and affected commands. This evolution means that while Lerna remains a dedicated monorepo manager, its users can benefit from the performance optimizations of a dedicated build system like Nx, which can significantly reduce build times in large monorepos by executing tasks efficiently and selectively rebuilding only what has changed.

Lerna is primarily utilized by front-end and full-stack development teams working with Node.js and web technologies. It helps maintain code quality and consistency across various packages by enforcing shared linting rules, build configurations, and testing strategies. Its CLI commands are designed to be intuitive for developers familiar with package managers like npm or Yarn, making it accessible for managing complex project structures without excessive configuration overhead. The tool's open-source nature ensures community contributions and continuous development, making it a sustainable choice for long-term monorepo strategies.

Key features

• Package Hoisting: Lerna can hoist common dependencies to the monorepo root node_modules folder, reducing disk space usage and speeding up dependency installation by avoiding redundant package installations within individual package directories.
• Inter-package Linking: It automatically links local packages together using symlinks, allowing developers to work on changes across dependent packages simultaneously without publishing intermediate versions.
• Distributed Command Execution: Lerna enables running arbitrary npm scripts or shell commands across all or a subset of packages within the monorepo, facilitating tasks like testing, linting, or building all projects with a single command.
• Version Management: Supports both fixed (synchronized) and independent versioning strategies, allowing teams to choose how packages are versioned and released based on their project's needs. Lerna automates the process of bumping versions and creating Git tags.
• Automated Publishing: Streamlines the process of publishing updated packages to npm or other registries, handling version bumps, Git commits, and tag creation automatically after a successful release.
• Change Detection: When integrated with Nx, Lerna can leverage Nx's powerful change detection to identify which packages have been affected by recent code changes, enabling more efficient builds and tests by only processing relevant projects.
• Caching Capabilities: Through its integration with Nx, Lerna benefits from advanced computation caching, which stores the outputs of tasks and reuses them if inputs haven't changed, significantly speeding up subsequent build and test runs.
• Filtering: Provides robust filtering options to execute commands on specific packages, packages that depend on others, or packages affected by recent changes, offering fine-grained control over monorepo operations.

Pricing

Lerna is a fully open-source tool, distributed under the MIT License. There are no direct costs associated with its use, installation, or deployment.

While Lerna itself is free, organizations might incur costs related to hosting repositories, continuous integration/delivery (CI/CD) infrastructure, or professional support/consulting from third parties for complex monorepo setups. For more detailed information on Lerna's open-source status, refer to the Lerna project homepage.

Common integrations

• Nx: Lerna integrates with Nx for enhanced caching, task orchestration, and change detection capabilities, improving build performance and developer experience in monorepos. Learn more about Nx integrated monorepos.
• npm/Yarn/pnpm: Lerna works seamlessly with popular JavaScript package managers to install dependencies, link packages, and publish to registries. See Lerna's package manager documentation.
• Git: Lerna relies on Git for version control, handling tags and commits during the release process.
• CI/CD Pipelines: Often integrated into CI/CD workflows (e.g., GitHub Actions, GitLab CI, Jenkins) to automate testing, building, and publishing of monorepo packages.

Alternatives

• Nx: A comprehensive monorepo toolkit that offers advanced caching, task orchestration, and code generation beyond Lerna's core features, often used alongside or as an alternative to Lerna.
• Turborepo: A high-performance build system for JavaScript and TypeScript monorepos, focused on optimizing build times through incremental builds and remote caching.
• Rush Stack: A set of tools from Microsoft for managing large-scale monorepos, emphasizing strict governance, code quality, and performance for enterprise environments.
• Yarn Workspaces: A feature built into Yarn that provides basic monorepo capabilities for dependency management and linking local packages without Lerna's advanced versioning or publishing features. Read more about Yarn Workspaces on the official documentation.
• pnpm Workspaces: Similar to Yarn Workspaces, pnpm offers its own workspace feature for efficient dependency management in monorepos, known for its disk space efficiency. The pnpm Workspaces documentation provides further details.

Getting started

To begin using Lerna in a new or existing monorepo, you typically start by initializing Lerna in your repository. This example demonstrates how to set up a new Lerna monorepo and add a package.

# 1. Initialize a new Git repository
mkdir my-lerna-repo
cd my-lerna-repo
git init

# 2. Install Lerna globally (optional, or use npx)
npm install -g lerna

# 3. Initialize Lerna in your repository
lerna init

# This creates lerna.json and a packages directory
# and adds lerna as a devDependency in your root package.json

# 4. Create a new package within the monorepo
mkdir packages/my-ui-button
cd packages/my-ui-button
npm init -y
# Add some content to my-ui-button/index.js
echo "module.exports = () => 'Hello from my-ui-button!';" > index.js
cd ../..

# 5. Add another package
mkdir packages/my-app
cd packages/my-app
npm init -y
# Add some content to my-app/index.js
echo "const button = require('my-ui-button');\nconsole.log(button());" > index.js
cd ../..

# 6. Install dependencies for all packages and link them
lerna bootstrap

# 7. Run a script in a specific package (e.g., in my-app)
lerna run start --scope=my-app
# Expected output: Hello from my-ui-button!

# 8. Clean up node_modules and build artifacts across all packages
lerna clean

This sequence initializes Lerna, creates two sample packages, demonstrates how to link dependencies using lerna bootstrap, and runs a script within a specific package. The lerna bootstrap command installs all root and package-level dependencies and symlinks any internal Lerna packages that depend on each other, allowing for local development across interdependent projects.