Skip to main content

Frequently asked questions

This document is a work in progress.

How do I add a third party dependency to my Lerna repository?

Lerna is not responsible for adding or linking your dependencies, that is what your package manager of choice (npm/yarn/pnpm) is best at. By using the workspaces feature of your package manager, all the linking of local packages will happen automatically based on the relationships you set up in your package.json files.

You can check out the workspaces documentation for your package manager here:

NOTE: Because lerna itself predates the workspaces feature in package managers, there was historically a few commands (add, bootstrap and link) that attempted to fill that gap. Fortunately these commands are no longer needed and lerna can focus on what it does best and let the package managers does the same.

New packages within the lerna repo

You can use the lerna create command to create new packages within your lerna repo.

lerna create <packageName>

See the create docs for more options.

If you don't want to use lerna create, then you can still manually create a package by running npm init within a subdirectory of the packages folder and Lerna will automatically detect it.

Existing packages

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 publish fails?

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.

How does Lerna detect packages?

By default, for npm and yarn, lerna uses the configured workspaces property in package.json to know what packages to operate on. For details on this property, see the npm documentation or the yarn documentation.

If you are using pnpm, you might have set npmClient to pnpm in lerna.json. In this case, Lerna will use the packages property in pnpm-workspace.yaml to know what packages to operate on. For details on this property, see the pnpm documentation.

If you want lerna to focus on a particular subset of packages in your repo, you can leverage the packages property in lerna.json to search for packages.