Lerna — Monorepo Management for JavaScript Projects

Introduction

Lerna is a build system and package management tool designed for JavaScript and TypeScript monorepos. It optimizes task execution across multiple packages in a single repository, handling dependency resolution, versioning, and publishing to npm registries. Originally created by Sebastian McKenzie, Lerna is now maintained by the Nx team at Nrwl.

What Lerna Does

• Runs scripts across all packages in topological order with automatic dependency detection
• Manages versioning for multiple packages using fixed or independent version strategies
• Publishes changed packages to npm with automatic changelog generation
• Caches task outputs locally and remotely via Nx integration for faster builds
• Detects affected packages from git changes so you only rebuild what changed

Architecture Overview

Lerna operates on a monorepo containing multiple packages under a configurable directory (typically packages/). It reads lerna.json for configuration and each package's package.json for dependency relationships. Under the hood, Lerna delegates to Nx for task scheduling, which builds a project graph to determine build order and parallelism. Version management uses git tags and conventional commits to calculate semantic version bumps.

Self-Hosting & Configuration

• Install globally via npm install -g lerna or use npx lerna for zero-install usage
• Initialize a monorepo with lerna init which creates lerna.json and a packages directory
• Configure lerna.json to set version mode (fixed or independent) and package directories
• Enable remote caching by connecting to Nx Cloud for shared build caches across CI
• Set useWorkspaces: true to delegate dependency hoisting to npm, yarn, or pnpm workspaces

Key Features

• Task pipeline orchestration runs builds in correct dependency order across packages
• Conventional Commits integration automates version bumps and CHANGELOG.md generation
• Affected command filters tasks to only packages changed since a given git ref
• Independent versioning allows each package to maintain its own semver version
• First-class support for npm, yarn, and pnpm workspace protocols

Comparison with Similar Tools

• Nx — Full-featured monorepo build system; Lerna now uses Nx under the hood but provides a simpler publishing-focused CLI
• Turborepo — Focuses on task caching and parallel execution; Lerna adds versioning and npm publishing workflows
• Rush — Microsoft's monorepo manager with strict dependency isolation; more complex setup than Lerna
• Changesets — Handles versioning and changelogs for monorepos; lighter weight but lacks Lerna's task running
• npm Workspaces — Built-in workspace support in npm 7+; lacks Lerna's versioning, publishing, and caching features

FAQ

Q: Is Lerna still maintained? A: Yes. After a period of reduced activity, the Nx team at Nrwl took over stewardship in 2022 and actively maintains and develops Lerna.

Q: What is the difference between fixed and independent versioning? A: Fixed mode keeps all packages on the same version number. Independent mode lets each package version independently based on its own changes.

Q: Can Lerna work with pnpm? A: Yes. Lerna supports npm, yarn (classic and berry), and pnpm as package managers with native workspace integration.

Q: Do I need Nx Cloud to use Lerna? A: No. Lerna works fully offline with local caching. Nx Cloud is optional and adds remote caching for CI environments.

Sources

• https://github.com/lerna/lerna
• https://lerna.js.org