Lerna - Automates the Annoying Parts of Publishing Multiple npm Packages

You update a utility package, forget to bump the version in the three apps that depend on it, and suddenly everyone's CI is broken with Cannot resolve module '@company/utils@1.2.3'. You spend 2 hours figuring out which packages need version bumps and which order to publish them without breaking npm installs.

Lerna solves the specific pain of coordinating releases. It tracks which packages changed, bumps versions automatically, and publishes in dependency order so Package A doesn't go live before Package B when A depends on B. The React team uses it because managing dozens of packages manually is impossible.

The Publishing Pain Points That Will Bite You

Version Hell: Miss one dependency bump and you get angry GitHub issues about broken installs. I've seen teams publish something like @company/ui@2.1.0 that depends on @company/utils@1.3.0, but @company/utils is still sitting at 1.2.8 or whatever. Users install the new UI and get Module not found errors. Lerna tracks these relationships so it doesn't happen.

Publishing Order Will Fuck You: Publish Package A before Package B updates its dependency on A, and npm users get 30 seconds of broken installs. Enough time for your Slack to blow up with "build is broken" messages. Lerna calculates the dependency graph and publishes in order.

Git Tag Nightmare: Manual tagging means someone uses v1.2.3, someone else uses 1.2.3, and your changelog generation breaks. Lerna creates conventional commit-based tags consistently.

The Nx Integration Reality Check (It's Complicated)

When Nrwl took over Lerna in 2022, they integrated Nx caching. Now your builds are fast when the cache works, but when it doesn't, you'll spend hours debugging why Package A rebuilt when nothing changed. Miss one environment variable in your cache inputs and you get stale builds that pass locally but fail in CI.

The caching hashes file contents and dependencies to store build outputs. Change one file, Nx rebuilds that package plus everything depending on it. The problem is figuring out what counts as an "input" - your source files, yes, but also .env files, global configs, and whatever random shit your build script reads. Get it wrong and cache keys become useless.

Lerna gets regular updates - version 8.2.4 is current as of 2025 with Node.js 22 support and bug fixes. The documentation is solid, and you can usually get help on Stack Overflow when things break.

Works with conventional commits if your team can be trusted to write commit messages correctly (good luck). Plays nice with GitHub Actions for CI/CD, though you'll spend time debugging why the auth token works locally but fails in CI. Most teams end up adding TypeScript project references, ESLint configs, and Prettier because apparently we love making simple things complicated.

Setup usually takes a while - maybe 20 minutes if everything goes right, could be most of your afternoon if it doesn't. The Nx integration works great until it doesn't, then you're googling "nx cache miss" at 2am trying to figure out why your build takes 10 minutes again.

The Publishing Workflow That Works

Lerna's main strength is coordinating npm package releases. When you run lerna publish, it:

1. Detects which packages have changes since the last release
2. Figures out version bumps based on conventional commits (if you use them)
3. Updates package.json files and inter-package dependencies
4. Creates git tags and publishes to npm in dependency order

This actually works most of the time. When it doesn't, you get cryptic errors like npm ERR! 404 Not Found - PUT https://registry.npmjs.org/@company%2futils and have to figure out whether it's auth, network, or package name issues. But it beats manually coordinating releases where someone always publishes the wrong version.

Two versioning modes:

• Independent: Each package has its own version (good for libraries)
• Fixed: All packages share one version (simpler for apps)

Most teams I've worked with prefer independent versioning because different packages evolve at different rates.

Caching Reality Check

Since Lerna 6, builds go through Nx's caching system. This is genuinely useful for large monorepos but adds complexity:

When caching helps:

• Your builds are slow (>30 seconds)
• You have >10 packages with complex build steps
• Multiple developers work on the same monorepo

When caching becomes a nightmare:

• Simple projects where caching overhead exceeds build time
• Teams who spend more time debugging cache misses than building features
• CI environments where random environment differences invalidate cache keys
• Docker builds where filesystem timestamps fuck up cache inputs

The cache stores build outputs based on file hashes. Sounds simple until you realize your build reads .env.local, some random config file, and the phase of the moon. Miss one input and you get stale builds that work locally but fail in prod. Debugging requires understanding Nx internals, which defeats the "it just works" promise.

Setup Pain Points

Basic setup is npx lerna init, but you'll hit these gotchas:

{
  "version": "independent",
  "useNx": true,
  "npmClient": "npm"
}

useNx: true is the default, but the docs don't tell you when to turn the damn thing off. Hint: if you just want to publish packages without learning another build system, set it to false and save yourself hours of cache debugging.

Shit that will break:

• Build task configuration requires understanding Nx project.json format
• Error messages like Cannot find project 'my-package' when your workspace detection fails
• Windows PATH length limits break deep node_modules (yes, still a thing in 2025)
• The migration guide assumes your old config was simple

Migrating from Lerna 5 takes way longer than the docs claim. Plan on spending a weekend, maybe more, debugging configuration edge cases that the changelog doesn't mention.

Teams that make Lerna work have at least one person who gets both the publishing workflow and Nx's caching bullshit. If you just need to coordinate 3-4 package releases, pnpm workspaces is probably less painful.

When shit breaks, check the GitHub issues first. Someone else probably hit the same problem.