lerna

library2.0.4jsnpmunverified

Lerna is a fast, modern build system and monorepo management tool for JavaScript and TypeScript projects. It allows developers to manage and publish multiple packages from a single repository, streamlining development workflows for complex applications and libraries. The current stable version is 9.0.7, with frequent patch releases addressing bug fixes and minor improvements, and major versions typically released every 1.5 to 2 years. Key differentiators include its integration with Nx for advanced caching and optimized task execution, efficient package publishing (supporting both fixed and independent versioning), and a focus on performance by avoiding redundant builds. Lerna helps teams maintain a unified development experience across many packages while leveraging the benefits of a monorepo structure, such as shared code and simplified CI processes.

devops workflow

npm install lerna

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · LERNA

lerna

devopsjavascriptv2.0.4

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

detectProjects

✓ import { detectProjects } from 'lerna/utils';

✗ const { detectProjects } = require('lerna/utils');

For programmatic access to the monorepo's project graph. Primarily used in advanced scripting or custom tooling within a Lerna workspace. Lerna v9+ is primarily ESM, though `require` might still work in some contexts depending on project configuration.

Project

✓ import { Project } from '@lerna/project';

✗ const Project = require('@lerna/project');

Used for programmatic interaction with individual Lerna projects. This is a lower-level package within the Lerna ecosystem, intended for advanced use cases like custom commands or tooling.

Command

✓ import { Command } from '@lerna/core';

✗ import { Command } from 'lerna/commands';

Base class for Lerna commands. Primarily used when extending Lerna with custom commands. Direct imports from `lerna/commands` are not the public API.

This quickstart demonstrates how to set up a Lerna monorepo, create packages, and execute scripts across them using the Lerna CLI. It covers initialization, package creation, running a shared build script, and preparing for package publishing.

{ "name": "my-lerna-monorepo", "private": true, "workspaces": [ "packages/*" ], "scripts": { "build": "lerna run build", "test": "lerna run test", "clean": "lerna run clean", "start": "lerna run start --parallel" }, "devDependencies": { "lerna": "^9.0.0" } } // In your terminal: // 1. Initialize Lerna in an empty directory (or with an existing repo) // npx lerna init // 2. Create a new package within the 'packages' directory // npx lerna create my-package-a // npx lerna create my-package-b // 3. Add a 'build' script to packages/my-package-a/package.json and packages/my-package-b/package.json // // packages/my-package-a/package.json // { // "name": "my-package-a", // "version": "1.0.0", // "scripts": { // "build": "echo Building my-package-a" // } // } // // packages/my-package-b/package.json // { // "name": "my-package-b", // "version": "1.0.0", // "scripts": { // "build": "echo Building my-package-b" // } // } // 4. Run the build script across all packages // npm run build // 5. Publish packages (after configuring registry, tokens, etc.) // npm install -g lerna # if not using npx for publish // lerna publish

lerna --version

Debug

Known issues

breakingLerna v9 dropped support for Node.js v18 as it reached End-of-Life. Projects must use Node.js versions `^20.19.0 || ^22.12.0 || >=24.0.0`.

fix

Upgrade Node.js to a supported version (20.x, 22.x, or 24.x+). It is recommended to run `npx lerna repair` after upgrading Lerna to ensure `lerna.json` is up to date.

affects: >=9.0.0

breakingLerna v9 formally removed the `bootstrap`, `add`, and `link` commands after two years of deprecation. These commands are no longer available in the Lerna CLI.

fix

Migrate to using your package manager's native workspaces feature (npm, Yarn, pnpm) for package management concerns like installing and linking dependencies. Consult the Lerna documentation on 'Legacy Package Management' for migration guides.

affects: >=9.0.0

breakingThe `@lerna/legacy-package-management` package was formally removed in Lerna v9. Any explicit dependencies or usage of this polyfill will no longer work.

fix

This removal is tied to the deprecation of `bootstrap`, `add`, and `link` commands. Migrate to using native package manager workspaces as the primary method for managing package dependencies.

affects: >=9.0.0

gotchaWhen Lerna v8.2.2 upgraded to `cosmiconfig` v9.0.0, it changed configuration lookup behavior. If your Lerna configuration (e.g., `lerna.json`) is not in the root and you encounter issues, it might be due to this change.

fix

Ensure your `lerna.json` is at the root of your project or configure `searchStrategy: 'global'` if using advanced `cosmiconfig` setups. Running `lerna repair` may help.

affects: >=8.2.2

gotchaLerna v8.2.2 changed the default behavior for peer dependencies, disabling 'legacy peer deps' by default. This might affect how peer dependencies are resolved during `lerna install` or `lerna bootstrap` (if you were on an older version and still using these commands).

fix

Ensure your `package.json` files correctly define peer dependencies and their versions. If specific legacy behavior is required, consult Lerna or package manager documentation for explicit configuration options, though this is generally not recommended.

affects: >=8.2.2

gotchaWhen executing Lerna commands via `npx` (e.g., `npx lerna run`), glob arguments must be explicitly enclosed with an equals sign (`=`) to prevent `npx` from expanding them prematurely, which can lead to unexpected behavior or incorrect targeting of packages.

fix

Use the format `npx lerna run --scope="package-*" test` instead of `npx lerna run --scope=package-* test`.

affects: >=3.0.0

gotchaInstalling Lerna v9.0.7 may produce `npm warn deprecated` messages for transitive dependencies like `git-semver-tags@5.0.1`, `git-raw-commits@3.0.0`, and `glob@11.1.0`. These indicate underlying packages are no longer maintained or have known security vulnerabilities.

fix

While Lerna is actively working on updating these dependencies, the warnings are typically informational and don't block functionality. Future Lerna versions are expected to address these. In the meantime, ensure your project's overall dependencies are regularly audited.

affects: >=9.0.7

Errors

Common errors & fixes

Error: Cannot find module 'lerna'

Lerna is not installed in the current project or globally, or `npx` is not being used to invoke the local installation.

fix

Install Lerna locally (`npm install --save-dev lerna`) and run commands with `npx lerna <command>`, or install globally (`npm install -g lerna`) and run `lerna <command>`.

lerna success run No packages found with the lifecycle script 'build' (or similar command messages like 'No packages found.')

Lerna cannot detect packages in the monorepo, or the specified script does not exist in any of the detected packages. This can be caused by incorrect `workspaces` configuration in `package.json` or `lerna.json`, or if packages are accidentally excluded by `.gitignore` rules in a parent directory.

fix

Verify the `workspaces` array in your root `package.json` or `lerna.json` matches your project structure (e.g., `"packages/*"`). Ensure that packages actually contain the specified npm script in their `package.json`. Check for `.gitignore` files that might be excluding package directories. Run `npx lerna list` to confirm Lerna detects your packages.

Error: Cannot find module '@scope/package-name' or its corresponding type declarations.

This error often occurs in TypeScript monorepos when one package cannot find another internal package. Common causes include the dependent package not being built, incorrect `tsconfig.json` paths, or missing `main`, `types`, or `exports` fields in the internal package's `package.json`.

fix

Ensure all internal packages are built before being consumed. Verify `tsconfig.json` in consuming packages include correct `paths` mapping. Make sure internal packages' `package.json` specify `main`, `types` (for declaration files), and potentially `exports` fields. Set `compilerOptions.declaration: true` in `tsconfig.json` for packages that are consumed by others.

lerna add: No packages found where <package> can be added.

This specific error often occurred with older versions of `lerna add` when attempting to add multiple packages in a single command, or if the target package was not found. Note that the `lerna add` command itself is deprecated in Lerna v9.

fix

For older Lerna versions (pre-v9), add packages individually: `lerna add <dependency> --scope=<target-package>`. For Lerna v9+, use your package manager's native commands (e.g., `npm install <dependency> -w <target-package>`) as `lerna add` has been removed.

Cannot find module 'js-yaml' Require stack: - .../node_modules/lerna/dist/cli.js

This specific error was a known bug in `lerna@6.5.0` where the `js-yaml` dependency was missing from the published package.

fix

Upgrade Lerna to a version greater than `6.5.0` (e.g., `npm install lerna@latest`). This issue was resolved in subsequent patch releases of Lerna v6.

Upgrade

Version history

2.0.4latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

21 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/lerna/lerna ↗

packagehttps://www.npmjs.com/package/lerna ↗

homepagehttps://lerna.js.org ↗