Lerna

Information

Lerna is a tool for managing JavaScript/TypeScript monorepos. It optimizes workflow around managing multi-package repositories with git and npm (or yarn/pnpm), handling versioning, changelog generation, and publishing of multiple packages from a single repository.

Lerna works on top of Node.js and npm workspaces. It is most commonly used with even-numbered LTS Node.js versions for production monorepos. See node.md for the Node.js LTS versioning policy.

Lerna currently ships as two modes:

Since Lerna v5, it is maintained by Nx and integrates with the Nx task runner optionally.

Installation

Global (legacy usage)

npm install --global lerna
lerna --version

Install Lerna as a dev dependency in the monorepo root:

npm install --save-dev lerna
npx lerna --version

Preparations

Initialize a New Monorepo

mkdir my-monorepo
cd my-monorepo
git init
npx lerna init

This creates a lerna.json and a root package.json. The default structure places packages under packages/.

lerna.json

Minimal lerna.json for independent versioning:

{
    "$schema": "node_modules/lerna/schemas/lerna-schema.json",
    "version": "independent",
    "npmClient": "npm"
}

For fixed versioning, replace "independent" with a version string such as "0.1.0".

Root package.json with Workspaces

{
    "name": "my-monorepo",
    "private": true,
    "workspaces": [
        "packages/*"
    ],
    "scripts": {
        "build": "lerna run build",
        "test": "lerna run test",
        "lint": "lerna run lint"
    },
    "devDependencies": {
        "lerna": "^8.0.0"
    }
}

Add a Package

cd packages
mkdir my-package
cd my-package
npm init -y

Or using the Lerna create command:

npx lerna create my-package packages

Angular Workspace inside Lerna (legacy)

cd packages
ng new has-web-app-new-ng

Usage, tips and tricks

Run a Script in All Packages

# Run "build" in every package that defines it
npx lerna run build
# Run "serve" with streaming output
npx lerna run serve --stream
# Run in a specific package
npx lerna run test --scope=my-package

Versioning and Publishing

# Bump versions interactively (independent mode)
npx lerna version
# Publish packages that changed since last release
npx lerna publish from-git
# Publish with conventional commits changelog
npx lerna version --conventional-commits

Bootstrap (Lerna v4 and below)

In older Lerna versions (before npm workspaces were the default), lerna bootstrap was used to link local packages:

npx lerna bootstrap

In modern Lerna (v5+) with npm/yarn workspaces enabled, npm install from the root is sufficient.

Check Changed Packages

npx lerna changed
npx lerna diff

See also