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.
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:
Your repository should now look like this:
lerna-repo/ packages/ package.json lerna.json
Here is a brief introduction for each command. Please visit the README for more detailed informations.
Create a new lerna repo or upgrade an existing repo to the current version of Lerna.
-i – Use independent
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
require() as if the packages were already existing
and available in your
lerna import <pathToRepo>
Import the package in the local path <pathToRepo> into packages/<directory-name> with commit history.
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.
--npm-tag [tagname] — Publish to npm with the given
npm dist-tag (Defaults to latest).
-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).
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.
List all of the public packages in the current Lerna repo.
Who's using Lerna?