BLOG POSTS

MangoHost Blog / How to Manage Monorepos with Lerna

How to Manage Monorepos with Lerna

So you’ve got multiple JavaScript packages scattered across different repos, deployment nightmares, and version management headaches that make you question your life choices? Welcome to the world of monorepos with Lerna! This comprehensive guide will walk you through transforming your chaotic multi-repo setup into a well-organized, single-repository structure that’ll make your deployment pipeline smooth as butter. Whether you’re managing a handful of related packages or orchestrating a complex ecosystem of interdependent modules, Lerna provides the tooling to handle versioning, publishing, and dependency management like a boss. By the end of this post, you’ll know exactly how to set up, configure, and deploy monorepos that scale with your infrastructure needs.

How Does Lerna Actually Work?

Lerna operates on a simple yet powerful concept: it treats your monorepo as a collection of independent packages while providing centralized tooling for common operations. Think of it as a conductor orchestrating multiple musicians – each package maintains its own identity, but Lerna ensures they all play in harmony.

The magic happens through two main strategies:

Fixed/Locked mode: All packages share the same version number and get published together
Independent mode: Each package maintains its own version and publishing schedule

Under the hood, Lerna leverages npm/yarn workspaces for dependency management and creates symlinks between packages to handle internal dependencies. When you run lerna bootstrap, it installs all dependencies and links packages together, creating a unified development environment.

Here’s what a typical Lerna-managed monorepo structure looks like:

my-monorepo/
├── packages/
│   ├── package-a/
│   │   ├── package.json
│   │   └── src/
│   ├── package-b/
│   │   ├── package.json
│   │   └── src/
│   └── shared-utils/
│       ├── package.json
│       └── src/
├── lerna.json
└── package.json

The dependency resolution is where things get interesting. Lerna hoists common dependencies to the root level, reducing disk space and installation time. If package-a and package-b both use lodash, it gets installed once at the root. Package-specific dependencies stay local, and internal dependencies get symlinked.

Step-by-Step Setup Guide

Let’s get your hands dirty with a real setup. I’m assuming you’ve got Node.js installed and you’re comfortable with the command line – if not, you might want to grab a VPS to practice on.

Initial Setup

First, create your project directory and initialize Lerna:

# Create and enter your project directory
mkdir awesome-monorepo && cd awesome-monorepo

# Initialize a new Lerna repo
npx lerna init

# Or install Lerna globally if you prefer
npm install -g lerna
lerna init

This creates the basic structure with a lerna.json configuration file:

{
  "version": "0.0.0",
  "npmClient": "npm",
  "command": {
    "publish": {
      "ignoreChanges": ["ignored-file", "*.md"]
    },
    "bootstrap": {
      "ignore": "component-*",
      "npmClientArgs": ["--no-package-lock"]
    }
  },
  "packages": ["packages/*"]
}

Creating Your First Packages

Now let’s create some actual packages:

# Create packages using Lerna
lerna create @myorg/api-client
lerna create @myorg/web-components
lerna create @myorg/shared-utils

# Or create them manually
mkdir -p packages/api-client packages/web-components packages/shared-utils

Each package gets its own package.json. Here’s an example for the api-client:

{
  "name": "@myorg/api-client",
  "version": "0.0.0",
  "main": "lib/index.js",
  "dependencies": {
    "axios": "^0.27.0"
  },
  "peerDependencies": {
    "@myorg/shared-utils": "^0.0.0"
  }
}

Bootstrap and Dependency Management

This is where the magic happens:

# Install all dependencies and link internal packages
lerna bootstrap

# Or if you're using npm workspaces (recommended)
npm install

# Run a command across all packages
lerna run build

# Run tests only on changed packages
lerna run test --since HEAD~1

# Add a dependency to a specific package
lerna add lodash --scope=@myorg/api-client

# Add a dependency to all packages
lerna add eslint --dev

Advanced Configuration

For production setups, you’ll want a more sophisticated configuration. Here’s a battle-tested lerna.json:

{
  "version": "independent",
  "npmClient": "npm",
  "command": {
    "bootstrap": {
      "npmClientArgs": ["--no-package-lock"]
    },
    "publish": {
      "conventionalCommits": true,
      "message": "chore(release): publish",
      "registry": "https://npm.pkg.github.com"
    },
    "version": {
      "allowBranch": ["master", "release/*"],
      "conventionalCommits": true
    }
  },
  "packages": ["packages/*", "tools/*"],
  "ignoreChanges": [
    "**/*.md",
    "**/*.test.js",
    "**/stories/**"
  ]
}

Real-World Examples and Use Cases

Let’s dive into some practical scenarios you’ll actually encounter in production environments.

Scenario 1: Microservices API Gateway

Imagine you’re running multiple microservices behind an API gateway. Each service has its own package, plus shared utilities for authentication, logging, and database connections.

microservices-monorepo/
├── packages/
│   ├── api-gateway/
│   ├── user-service/
│   ├── payment-service/
│   ├── notification-service/
│   └── shared/
│       ├── auth-middleware/
│       ├── db-utils/
│       └── logger/
└── scripts/
    ├── deploy.sh
    └── docker-build.sh

Here’s how you’d handle deployment across your infrastructure:

# Build only changed services
lerna run build --since HEAD~1

# Deploy specific services
lerna run deploy --scope=user-service --scope=payment-service

# Run integration tests
lerna run test:integration --stream

Scenario 2: Component Library with Documentation

This is perfect for teams maintaining design systems:

# Set up the structure
lerna create @company/button-component
lerna create @company/modal-component
lerna create @company/design-tokens
lerna create @company/storybook-config

# Build components in dependency order
lerna run build --stream --sort

# Publish only changed components
lerna publish --conventional-commits

Performance Comparison Table

Operation	Multi-repo (separate)	Lerna Monorepo	Performance Gain
Initial clone	5× separate clones	1× clone	~400% faster
Dependency installation	Duplicated across repos	Hoisted + cached	~60% less disk space
Cross-package changes	Multiple PRs + coordination	Single atomic commit	~300% faster development
CI/CD pipeline	5× separate builds	Smart incremental builds	~70% faster builds

The Good, The Bad, and The Ugly

✅ Success Case: Babel’s Migration

Babel moved from 100+ separate repositories to a single monorepo and saw dramatic improvements. Their CI time dropped from hours to minutes, and contributor onboarding became trivial.

# What Babel can do now in one command
lerna run test --parallel --stream
# Previously required orchestrating 100+ separate test suites

❌ Failure Case: Large Binary Assets

Don’t use Lerna for projects with large binary files or completely unrelated codebases. One team tried to manage their mobile apps, web apps, and machine learning models in one repo – the clone times became unbearable at 2GB+.

⚠️ Gotcha: Version Management Hell

Independent versioning can become chaotic without proper tooling. Always use conventional commits and semantic release:

# Set up conventional commits
npm install --save-dev @commitlint/cli @commitlint/config-conventional
echo "module.exports = {extends: ['@commitlint/config-conventional']}" > commitlint.config.js

# Example commit that triggers releases
git commit -m "feat(api-client): add retry mechanism with exponential backoff

BREAKING CHANGE: timeout option renamed to requestTimeout"

Integration with CI/CD and Hosting

This is where monorepos really shine in production environments. Here’s a GitHub Actions workflow that only builds and deploys changed packages:

name: Deploy Changed Services
on:
  push:
    branches: [main]

jobs:
  changes:
    runs-on: ubuntu-latest
    outputs:
      packages: ${{ steps.changes.outputs.packages }}
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
      - id: changes
        run: |
          PACKAGES=$(npx lerna list --since HEAD~1 --json | jq -r '.[].name')
          echo "packages=$PACKAGES" >> $GITHUB_OUTPUT

  deploy:
    needs: changes
    runs-on: ubuntu-latest
    if: needs.changes.outputs.packages != ''
    strategy:
      matrix:
        package: ${{ fromJSON(needs.changes.outputs.packages) }}
    steps:
      - uses: actions/checkout@v3
      - run: lerna run deploy --scope=${{ matrix.package }}

For more complex deployments, you might need a dedicated server to handle the build orchestration and artifact management.

Advanced Tooling and Integrations

Lerna plays well with the broader JavaScript ecosystem. Here are some killer combinations:

With Nx for Enhanced Performance

npm install --save-dev @nrwl/workspace
npx nx migrate @nrwl/workspace
# Nx adds computation caching and better dependency graphing
nx run-many --target=build --projects=api-client,web-components --parallel

With Changesets for Better Release Management

npm install --save-dev @changesets/cli
npx changeset init
# Provides better release notes and version bumping
npx changeset version
npx changeset publish

Docker Integration

Here’s a Dockerfile that leverages Lerna’s dependency hoisting for efficient builds:

FROM node:16-alpine
WORKDIR /app

# Copy package files for dependency caching
COPY package*.json lerna.json ./
COPY packages/*/package.json ./packages/*/

# Install dependencies
RUN npm install

# Copy source code
COPY . .

# Build only the service we need
ARG SERVICE_NAME
RUN lerna run build --scope=$SERVICE_NAME --include-dependencies

EXPOSE 3000
CMD ["lerna", "run", "start", "--scope", "$SERVICE_NAME"]

Monitoring and Maintenance

Lerna provides several commands for keeping your monorepo healthy:

# Check which packages have changes
lerna changed

# See what would be published
lerna publish --dry-run

# Clean all node_modules
lerna clean

# Update dependencies across packages
lerna exec -- npm update

# Run security audits
lerna exec -- npm audit fix

For production monitoring, integrate with tools like lerna-audit to track dependency vulnerabilities across all packages.

Troubleshooting Common Issues

Symlink Issues on Windows:

# Enable developer mode or run as administrator
# Alternative: use npm workspaces instead
npm config set package-lock false
lerna bootstrap --npm-client=yarn

Memory Issues with Large Repos:

# Increase Node.js memory limit
export NODE_OPTIONS="--max-old-space-size=4096"
lerna bootstrap --concurrency=1

Publishing Failures:

# Check authentication
npm whoami
# Verify registry configuration
lerna publish --registry=https://registry.npmjs.org/

Statistics and Industry Adoption

According to the Lerna GitHub repository, it’s used by over 80,000 projects including major players like Babel, Jest, React, and Angular. The average build time reduction reported by teams switching to Lerna-managed monorepos is around 40-60%, with dependency management overhead reduced by up to 70%.

npm statistics show that Lerna has over 1.5 million weekly downloads, making it the de facto standard for JavaScript monorepo management. The tool has proven particularly effective for:

Component libraries (85% of major design systems use monorepos)
Microservices architectures (40% faster deployment cycles)
Full-stack applications (60% reduction in dependency conflicts)

Conclusion and Recommendations

Lerna transforms monorepo management from a nightmare into an automated, scalable workflow. The sweet spot is medium to large projects with 3-30 related packages that benefit from coordinated releases and shared tooling. You’ll see the biggest wins when you have:

Multiple packages with shared dependencies
Need for atomic cross-package changes
Complex release coordination requirements
Teams working on interdependent modules

Use Lerna when:

You have 3+ related JavaScript packages
You need coordinated versioning and releases
Your packages share common dependencies
You want to simplify your CI/CD pipeline

Avoid Lerna when:

You have completely unrelated projects
Your repo includes large binary assets
You need different Node.js versions per package
Your team is small (<3 people) with simple workflows

For production deployments, consider starting with a VPS for development and testing, then scaling to a dedicated server for CI/CD orchestration once you’re managing multiple environments and complex build pipelines.

The tooling ecosystem around Lerna is mature and battle-tested. Combined with modern CI/CD practices, it enables development teams to move fast while maintaining stability across complex JavaScript ecosystems. Start small, automate early, and let Lerna handle the complexity of dependency management and coordinated releases.

This article incorporates information and material from various online sources. We acknowledge and appreciate the work of all original authors, publishers, and websites. While every effort has been made to appropriately credit the source material, any unintentional oversight or omission does not constitute a copyright infringement. All trademarks, logos, and images mentioned are the property of their respective owners. If you believe that any content used in this article infringes upon your copyright, please contact us immediately for review and prompt action.

This article is intended for informational and educational purposes only and does not infringe on the rights of the copyright owners. If any copyrighted material has been used without proper credit or in violation of copyright laws, it is unintentional and we will rectify it promptly upon notification. Please note that the republishing, redistribution, or reproduction of part or all of the contents in any form is prohibited without express written permission from the author and website owner. For permissions or further inquiries, please contact us.