Lerna Monorepo
A practical primer on managing multiple packages in a single repository with Lerna — the tool that keeps your JavaScript ecosystem fast, consistent, and publishable.
What is Lerna?
Lerna is a build system for managing JavaScript/TypeScript projects that contain multiple packages. Instead of juggling separate repos, you keep everything in one place. Lerna handles cross-package linking, versioning, changelogs, and publishing so your team ships faster with fewer footguns.
Why use it?
- Single source of truth — one
lerna.jsondrives the entire repo. - Atomic releases — version interdependent packages together, never ship a broken graph.
- Local linking —
lerna bootstrapsymlinks packages so you develop against live code, not stale npm tarballs. - Parallel execution — scripts, tests, and builds run concurrently across packages.
Core commands
| Command | Purpose |
|---|---|
| lerna init | Scaffold a new monorepo |
| lerna bootstrap | Install deps and cross-link packages |
| lerna run build | Execute the build script in every package |
| lerna publish | Bump versions, tag, and push to npm |
Fixed vs Independent mode
In fixed mode (default), all packages share a single version number — great for tightly coupled libraries. In independent mode, each package versions on its own cadence. Choose based on how tightly your packages depend on one another.
Nx integration
Modern Lerna delegates task orchestration to Nx. You get computation caching, distributed task execution, and a dependency graph out of the box. Pass --use-nx during init or set "useNx": true in lerna.json.
Pro tip: Combine Lerna with conventional commits and let lerna version auto-generate changelogs. Your release notes write themselves.