What Is Lerna and How Does It Manage JavaScript Monorepos?
Lerna is a build system for managing and publishing multiple JavaScript or TypeScript packages from a single repository. It fits teams that keep several interdependent packages together and need coordinated versioning, publishing, and task running. If you only have one package, or your packages never share code or releases, Lerna adds overhead without much benefit.
The core problem Lerna solves
A monorepo puts many packages in one repository. That makes sharing code easy, but it creates coordination work:
- Which packages changed since the last release?
- What version should each changed package get?
- In what order should packages be published so dependencies exist first?
- How do you run a build or test across all packages without doing it manually?
Lerna addresses these by understanding the dependency graph between your packages and acting on it.
How Lerna manages a monorepo
Versioning
Lerna tracks which packages changed and updates their versions together or independently. It supports two common modes:
- Fixed mode: all packages share one version number and are released together.
- Independent mode: each package gets its own version, so you can release only what changed.
The choice matters. Fixed mode is simpler and suits tightly coupled packages. Independent mode gives finer control but requires more discipline.
Publishing
When you publish, Lerna determines the correct order based on inter-package dependencies, so a package that depends on another is published after its dependency. It can also create git tags and update changelogs as part of the release.
Running tasks across packages
Lerna can run a command (build, test, lint) across multiple packages, and it can scope that to only the packages affected by recent changes. This is the part that saves the most time in large repos, because you avoid rebuilding everything on every change.
Lerna and Nx
Lerna is now part of the Nx ecosystem. The relationship matters when you choose tooling:
- Lerna handles the monorepo versioning and publishing workflow.
- Nx provides the broader task running, caching, and project graph capabilities.
In practice, Lerna can use Nx under the hood for task execution and caching. If you already use Nx, Lerna fits as the release layer. If you only need publishing and versioning, Lerna can stand alone.
Lerna vs. plain npm/yarn workspaces
| Concern | npm/yarn workspaces | Lerna |
|---|---|---|
| Linking local packages | Yes | Yes (builds on workspaces) |
| Coordinated versioning | No | Yes |
| Ordered publishing | No | Yes |
| Changelog generation | No | Yes |
| Running tasks across packages | Limited | Yes, with affected-package scoping |
Workspaces solve dependency linking. Lerna solves the release and task-orchestration layer on top. Many projects use both: workspaces for installation, Lerna for versioning and publishing.
When Lerna is the right choice
Consider Lerna when:
- You maintain multiple packages that depend on each other.
- You need repeatable, ordered releases rather than manual
npm publishper package. - You want to run builds or tests only for packages affected by a change.
- You are already in or moving toward the Nx ecosystem.
Look elsewhere when:
- You have a single package.
- Your packages are released independently by different teams with no shared release process.
- You only need local linking and never publish.
Where to start
Begin with the Lerna documentation at lerna.js.org. The typical first steps are initializing Lerna in an existing repository, defining your package locations, and choosing fixed or independent versioning before your first release. Getting the versioning mode right early avoids a painful migration later.