{"id":13431,"library":"lerna","title":"Lerna","description":"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.","status":"active","version":"9.0.7","language":"javascript","source_language":"en","source_url":"https://github.com/lerna/lerna","tags":["javascript","lerna","monorepo","multi-package"],"install":[{"cmd":"npm install lerna","lang":"bash","label":"npm"},{"cmd":"yarn add lerna","lang":"bash","label":"yarn"},{"cmd":"pnpm add lerna","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const { detectProjects } = require('lerna/utils');","symbol":"detectProjects","correct":"import { detectProjects } from 'lerna/utils';"},{"note":"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.","wrong":"const Project = require('@lerna/project');","symbol":"Project","correct":"import { Project } from '@lerna/project';"},{"note":"Base class for Lerna commands. Primarily used when extending Lerna with custom commands. Direct imports from `lerna/commands` are not the public API.","wrong":"import { Command } from 'lerna/commands';","symbol":"Command","correct":"import { Command } from '@lerna/core';"}],"quickstart":{"code":"{\n  \"name\": \"my-lerna-monorepo\",\n  \"private\": true,\n  \"workspaces\": [\n    \"packages/*\"\n  ],\n  \"scripts\": {\n    \"build\": \"lerna run build\",\n    \"test\": \"lerna run test\",\n    \"clean\": \"lerna run clean\",\n    \"start\": \"lerna run start --parallel\"\n  },\n  \"devDependencies\": {\n    \"lerna\": \"^9.0.0\"\n  }\n}\n// In your terminal:\n// 1. Initialize Lerna in an empty directory (or with an existing repo)\n//    npx lerna init\n// 2. Create a new package within the 'packages' directory\n//    npx lerna create my-package-a\n//    npx lerna create my-package-b\n// 3. Add a 'build' script to packages/my-package-a/package.json and packages/my-package-b/package.json\n//    // packages/my-package-a/package.json\n//    {\n//      \"name\": \"my-package-a\",\n//      \"version\": \"1.0.0\",\n//      \"scripts\": {\n//        \"build\": \"echo Building my-package-a\"\n//      }\n//    }\n//    // packages/my-package-b/package.json\n//    {\n//      \"name\": \"my-package-b\",\n//      \"version\": \"1.0.0\",\n//      \"scripts\": {\n//        \"build\": \"echo Building my-package-b\"\n//      }\n//    }\n// 4. Run the build script across all packages\n//    npm run build\n// 5. Publish packages (after configuring registry, tokens, etc.)\n//    npm install -g lerna # if not using npx for publish\n//    lerna publish","lang":"typescript","description":"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."},"warnings":[{"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.","message":"Lerna 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`.","severity":"breaking","affected_versions":">=9.0.0"},{"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.","message":"Lerna v9 formally removed the `bootstrap`, `add`, and `link` commands after two years of deprecation. These commands are no longer available in the Lerna CLI.","severity":"breaking","affected_versions":">=9.0.0"},{"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.","message":"The `@lerna/legacy-package-management` package was formally removed in Lerna v9. Any explicit dependencies or usage of this polyfill will no longer work.","severity":"breaking","affected_versions":">=9.0.0"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":">=8.2.2"},{"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.","message":"Lerna 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).","severity":"gotcha","affected_versions":">=8.2.2"},{"fix":"Use the format `npx lerna run --scope=\"package-*\" test` instead of `npx lerna run --scope=package-* test`.","message":"When 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.","severity":"gotcha","affected_versions":">=3.0.0"},{"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.","message":"Installing 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.","severity":"gotcha","affected_versions":">=9.0.7"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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>`.","cause":"Lerna is not installed in the current project or globally, or `npx` is not being used to invoke the local installation.","error":"Error: Cannot find module 'lerna'"},{"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.","cause":"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.","error":"lerna success run No packages found with the lifecycle script 'build' (or similar command messages like 'No packages found.')"},{"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.","cause":"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`.","error":"Error: Cannot find module '@scope/package-name' or its corresponding type declarations."},{"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.","cause":"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.","error":"lerna add: No packages found where <package> can be added."},{"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.","cause":"This specific error was a known bug in `lerna@6.5.0` where the `js-yaml` dependency was missing from the published package.","error":"Cannot find module 'js-yaml' Require stack: - .../node_modules/lerna/dist/cli.js"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"lerna","cli_version":null}