Frequently asked questions
This document is a work in progress.
How do I add a package to my Lerna repository?
For any packages that you add to your Lerna repository, instead of running
npm install you should run
lerna bootstrap. This will take into
account the existing projects in the
packages folder as well as
Create a directory for your package in the
packages folder, and run
as normal to create the
package.json for your new package.
You can use
lerna import <package> to transfer an existing package
into your Lerna repository; this command will preserve the commit history.
lerna import <package> takes a local path rather than a URL. In this
case you will need to have the repo you wish to link to on your file system.
How do I retry publishing if
lerna publish does not work. Your network may have had a hiccup, you may have not been logged on to npm, etc.
lerna.json has not yet been updated, simply try
lerna publish again.
If it has been updated, you can force re-publish.
lerna publish --force-publish $(ls packages/)
Recovering from a network error
In the case that some packages were successfully published and others were not,
lerna publish may have left the repository in an inconsistent state with some changed files. To recover from this, reset any extraneous local changes from the failed run to get back to a clean working tree. Then, retry the same
lerna publish command. Lerna will attempt to publish all of the packages again, but will recognize those that have already been published and skip over them with a warning.
If you used the
lerna publish command without positional arguments to select a new version for the packages, then you can run
lerna publish from-git to retry publishing that same already-tagged version instead of having to bump the version again while retrying.
The bootstrap process is really slow, what can I do?
Projects having many packages inside them could take a very long time to bootstrap.
You can significantly reduce the time spent in
lerna bootstrap if you turn
on hoisting, see the hoisting docs for more information.
In combination with that you may increase the bootstrap performance even more by
using yarn as an npm client instead of
package.json, at the very least, is how you install
lerna locally during a CI build.
You should also put your testing, linting and similar tasks there to run them from root
as running them separately from each package is slower. The root can also hold all the "hoisted" packages,
which speeds up bootstrapping when using the
As mentioned above root
package.json is responsible for installing
lerna locally. You need to automate
This can be achieved by putting it as npm script to use it during CI phases.
"bootstrap": "lerna bootstrap --hoist",
"pretest": "eslint packages",
Example CircleCI's configuration file (
- npm run bootstrap
How does Lerna detect packages?
By default, Lerna uses the
workspaces property in
package.json to search for packages. For details on this property, see the npm documentation or the Yarn documentation.
If you are using
pnpm, you might have set
lerna.json. In this case, Lerna will use the
packages property in
pnpm-workspace.yaml to search for packages. For details on this property, see the pnpm documentation.
If you are using an older version of Lerna or have explicitly opted out of using workspaces, then Lerna will use the
packages property in
lerna.json to search for packages.