Lerna logo

A tool for managing JavaScript projects with multiple packages.

Follow Lerna on Twitter

About

Splitting up large codebases into separate independently versioned packages is extremely useful for code sharing. However, making changes across many repositories is messy and difficult to track, and testing across repositories gets complicated really fast.

To solve these (and many other) problems, some projects will organize their codebases into multi-package repositories. Projects like Babel, React, Angular, Ember, Meteor, Jest, and many others develop all of their packages within a single repository.

Lerna is a tool that optimizes the workflow around managing multi-package repositories with git and npm.

Getting Started

Let's start by installing Lerna globally with npm:

Lerna 2.x is the recommended version to start with.

npm install --global lerna

Next we'll create a new git repository: 

git init lerna-repo && cd lerna-repo

And now let's turn it into a Lerna repo: 

lerna init

Your repository should now look like this: 

lerna-repo/
  packages/
  package.json
  lerna.json

Commands

Here is a brief introduction for each command. Please visit the README for more detailed informations.

lerna init

Create a new lerna repo or upgrade an existing repo to the current version of Lerna.

Options

--independent/-i – Use independent versioning mode.

lerna bootstrap

Bootstrap the packages in the current Lerna repo. Installing all their dependencies and linking any cross-dependencies.

This command is crucial, as it allows you to use your package names in require() as if the packages were already existing and available in your node_modules folder.

lerna import <pathToRepo>

Import the package in the local path <pathToRepo> into packages/<directory-name> with commit history.

lerna publish

Create a new release of the packages that have been updated. Prompts for a new version and updates all the packages on git and npm.

Options

--npm-tag [tagname] — Publish to npm with the given npm dist-tag (Defaults to latest).

--canary/-c – Create a canary release.

--skip-git – Don't run any git commands.

--force-publish [packages] — Force publish for the specified packages (comma-separated) or all packages using * (skips the git diff check for changed packages).

lerna changed

Check which packages have changed since the last release.

lerna diff [package?]

Diff all packages or a single package since the last release.

lerna run [script]

Run an npm script in each package that contains that script.

lerna ls

List all of the public packages in the current Lerna repo.

Who's using Lerna?