lerna/lerna
github.com/lerna/lerna ↗ · 1479 files · 3.7 MB
Important note: this project changed stewardship to Nx!
Overview
Lerna is a Node.js CLI for teams managing and publishing multiple JavaScript or TypeScript packages in one repository. It combines Nx project discovery and task execution with package-aware change detection, coordinated versioning, npm publishing, and GitHub/GitLab releases. This pinned revision publishes an ESM package while preserving selected CommonJS entrypoint contracts; its React website is a separate Docusaurus documentation surface.
System map
The product runtime is a Node CLI assembled from command libraries and shared core utilities. Nx supplies project graphs and the default task runner, while Lerna owns package metadata and release coordination. Persistent state consists primarily of workspace files, Git state, and registry artifacts. The npm package and documentation website have separate build and deployment paths.
- The published lerna package is ESM, exposes dist/cli.js as its binary, and exports the main API, command modules, selected helpers, migrations, and utilities.
- cli.ts first delegates through importLocal; otherwise it requires index.js and passes process.argv.slice(2) to main.
- main explicitly registers 15 command modules; shared CLI setup uses strict yargs parsing, requires a command, and maps failures to nonzero exit codes.
- Most command implementations resolve through @lerna aliases into libs/commands; published run wrappers re-export that implementation rather than duplicate it.
- Command orchestrates Project initialization, environment/options/properties setup, validation, graph detection, preparations, and subclass execution; composed publish/version calls can reuse graph data.
- Project owns root configuration and Package owns mutable manifests; serialization writes lerna configuration and package.json files rather than a database.
- Nx/esbuild compiles the published package for Node as split ESM with explicit additional entrypoints; root scripts route tests, lint, and integration through Nx.
- The website uses Docusaurus and React, deploys to the lerna/website repository, and has a PR build check; npm releases use a separately dispatched workflow with an npm-production environment.
Feature catalog
The registered CLI covers workspace setup, package inspection, task execution, cleanup, importing history, and releases. Shared filtering supports package scopes, exclusions, changed-package selection, and dependency expansion where commands expose those options. Versioning and publishing have distinct modes and side effects. Legacy package-management names remain registered only to explain their removal.
- init generates lerna.json, adds Lerna as a development dependency, supplies workspace configuration for a new repository, and supports dry-run previews; create scaffolds package files and optional CLI files.
- list filters and formats packages; changed collects release candidates and returns exit code 1 when none exist; diff invokes Git for a named package or package parent directories; info reports environment details.
- run accepts comma-separated targets and forwards arguments after --; Nx is the default runner, while useNx=false selects parallel, topological, or lexical legacy execution and rejects multiple targets.
- exec runs shell commands in selected package directories with LERNA_PACKAGE_NAME and LERNA_ROOT_PATH; watch delegates change-triggered execution to Nx with LERNA_PACKAGE_NAME and LERNA_FILE_CHANGES.
- clean removes selected packages' node_modules directories after confirmation or --yes; import reads an external repository and sequentially applies rewritten commit patches with git am.
- version supports fixed and independent versions, explicit semver or increment keywords, interactive selection, conventional-commit recommendations, changelogs, Git tags, pushes, and optional hosted releases.
- publish selects from-git, from-package, canary, or composed versioning; it supports custom publish directories/assets, private-package inclusion, temporary dist-tags, throttling, and a JSON summary.
- add-caching collects script dependency/cache/output answers and writes nx.json; repair passes registered Lerna migrations to Nx; add, bootstrap, and link terminate with removal guidance.
Data flow
Inputs enter through yargs, workspace configuration, package manifests, Git history, and registry responses. Project and Command establish effective options before Nx graph nodes acquire Package objects and dependency metadata. Task flows produce process output and exit codes; release flows mutate workspace files and transmit packed artifacts. Authentication state is passed through in-memory publish options and configuration.
- Run's argument builder converts comma-separated script input into an array and preserves -- arguments; Command merges CLI values before command-specific config, global lerna config, and environment defaults.
- Project searches lerna.json/package.json, applies extends, and derives its root from the resolved configuration; package globs come from explicit config, pnpm-workspace.yaml, or root workspaces.
- detectProjects obtains the Nx graph and file map, then createProjectGraphWithPackages matches configured roots, reads manifests, attaches Package instances, and sorts nodes by root.
- Graph enrichment resolves manifest dependency specs, records collection and resolution metadata, and includes local dependencies only when workspace protocol, directory location, or version requirements match.
- filterProjects applies private/scope/ignore selection, optionally intersects Git-derived updates, then expands dependents and dependencies; update detection uses git diff paths and ignoreChanges predicates.
- Run maps selected project names and targets into runOne/runMany, forwarding output style, concurrency, cache/bail/cycle options, argument overrides, and loadDotEnvFiles, which defaults to true.
- Version refreshes manifests after preversion hooks, mutates versions/dependencies, serializes packages and lockfiles, and writes fixed-mode lerna.json; writePackage sorts dependency keys and preserves detected indentation.
- Packing converts Arborist/npm-packlist output into a temporary tarball; npmPublish reads that archive and prepared manifest, merges publishConfig, attempts OIDC authentication, and submits through libnpmpublish with OTP handling.
Behavior traces
Source inspection followed startup, task execution, and version persistence through their concrete functions and branches. Publishing was also traced from selection through archive upload and cleanup. These are execution-order descriptions inferred directly from source, not observed runtime traces. Early returns and configuration switches materially change the work performed.
- Startup: cli.ts → importLocal or main(argv) → lernaCLI() → explicit command registration → cli.parse(argv, context); strict parser failures reach cli.exit with a positive error code or 1.
- Shared command startup: constructor → new Project → configureEnvironment → configureOptions → configureProperties → logger → conditional runValidations → detectProjects or reuse preinitialized graph data → runPreparations → runCommand; initialize=false prevents execute.
- lerna run: handler → factory → RunCommand.initialize → filterProjects → target-presence filtering → execute; missing scripts raise ENOSCRIPT, while zero matching targets return false with a success message.
- Default task execution: execute → runScriptsUsingNx → configureNxOutput → prepNxOptions → runOne for one project/one target, otherwise runMany; custom Nx configuration changes dependency and parallel/sort behavior.
- Version selection: initialize validates Git state when required, collects updates, filters private/unversioned packages, checks the working tree when enabled, then calls getVersionsForUpdates → setUpdatesForVersions → confirmVersions.
- Version persistence: updatePackageVersions runs root preversion unless rooted-leaf, then per-package preversion → refresh → version/dependency writes → version hook → optional changelog; afterward it updates fixed-mode configuration and root lockfiles.
- Version completion: execute awaits updatePackageVersions, optional commitAndTagUpdates, optional gitPushToRemote, then optional createRelease; commitAndTagUpdates chooses fixed/independent tags and runs postversion hooks.
- Publishing: initialize selects tagged/unpublished/canary updates or invokes version; execute prepares registry/licenses/private state → rewrites dependency links → serializes → packUpdated → publishPacked → restores private flags → serializes → optional resetChanges/dist-tag promotion.
Testing signals
Tests and CI were inspected, not executed; no passing result or coverage percentage is established. Vitest supplies shared Node-environment configuration for unit, integration, and e2e projects. Inspected suites mix mocked command boundaries with actual CLI and local-registry scenarios. The inventory is bounded, and mock coverage does not establish live service correctness.
- Shared Vitest configuration enables globals, a Node environment, single-run mode, spec/test discovery, Jest-compatible snapshot formatting, cleared mocks, and V8 coverage output.
- Run unit tests mock npm script execution and assert script validation, filtering, streaming/prefix behavior, no-match success, alternate clients, and bail/non-bail exit propagation.
- Version unit tests mock push and upstream checks while checking working-tree validation, version prompts, updated manifests, commit snapshots, and push arguments.
- Publish unit tests mock packing, publishing, authentication helpers, and checkout; they assert rejected CLI options and package publication order, so those assertions do not exercise a live npm service.
- Integration tests invoke the CLI on fixtures and check exec filtering, shell environment expansion, streaming, and failure codes; inspected non-bail cases are conditional on non-Windows platforms.
- E2e defaults serialize spec files and retry failures up to three times; an inspected publish scenario uses localhost:4873 to verify recovery when one version already exists, and task-runner assertions check environment loading.
- The inspected OIDC suite has two mocked cases: CircleCI token exchange and skipping unsupported CI. The ESM compatibility suite checks built output, ESM imports, synchronous require contracts, and CLI version output.
- CI defines a Node 22.22.2 package-entrypoint job, distributed Linux checks, Windows unit/integration jobs, and isolated task-runner e2e; core config excludes three config-chain suites on Windows.
Risk map
These are source observations and explicitly labeled hypotheses, not confirmed vulnerabilities. Lerna intentionally executes workspace-controlled commands and writes release artifacts, so trust boundaries include configuration, scripts, Git, and registries. Release operations span several independent systems and are not presented as one atomic transaction. Inspection also found narrow authentication tests and strong coupling to Nx internals.
- exec joins command and arguments into shell-interpreted text, uses shell=true, and copies the parent environment into package processes; callers must treat supplied command text as executable input.
- Configuration can execute code: applyExtends requires resolved modules, changelog presets use require/import and callable builders, and lifecycle scripts run through @npmcli/run-script unless ignored.
- Publishing deliberately writes archives beneath the system temporary directory, and configured contents/assets influence filesystem destinations; the inspected contents setter uses string-prefix selection and path joining rather than a containment check.
- Publish restoration defaults to enabled, but granularPathspec=false makes gitCheckout target '.'; import failure recovery invokes git am --abort and git reset --hard to the saved HEAD.
- Hypothesis: a later failure can leave earlier release side effects in place because ordinary publish awaits composed versioning before registry upload, and version executes writes, tags, pushes, and hosted releases sequentially. (inferred)
- Run and repair import nx/src internal APIs, while publish/version share preinitialized graph data; dependency upgrades therefore affect execution contracts beyond the public @nx/devkit interface.
- OIDC exchanges identity tokens against the effective registry and suppresses exchange failures before normal publish authentication continues; GitHub acquisition and provenance branches are not exercised by the two cases in the inspected OIDC suite.
- Release workflow protections include nonpersisted checkout credentials, a pinned npm registry, disabled remote build cache, serialized releases, environment-scoped Git credentials, and validation of free-text version input; their live environment configuration was not verified.
Extension points
Extension mechanisms are explicit command registration, shared command hooks, configuration, Nx task definitions, and migration metadata. Publishing accepts configurable artifact directories and assets, while conventional-commit processing loads presets. Hosted release providers share an adapter-shaped API. Public package entrypoints and build lists must stay aligned with implementation changes.
- A CLI command plugs into main's .command chain using a yargs CommandModule with builder and handler; run demonstrates handler-to-factory construction.
- Command subclasses implement initialize/execute and can override requiresGit, otherCommandConfigs, or project detection; initialize=false supplies a standard early-return contract.
- Lerna config extends supports locally resolvable modules with circular-reference detection; effective command options can inherit another command's namespace, as changed does for version and publish.
- Nx targetDefaults and package.json nx configuration define task dependencies; add-caching writes cache/dependsOn/output settings, replacing array-form entries with object form for per-script answers.
- Publishing configuration accepts root/package directory and asset definitions with projectRoot, projectName, and workspaceRoot interpolation; assets support strings or from/to objects.
- getChangelogConfig accepts named or object presets, loads CommonJS/ESM exports, invokes builder or legacy callback functions, and normalizes legacy preset fields for modern consumers.
- createReleaseClient selects GitHub or GitLab; GitLab adapts createRelease to the repos.createRelease interface, while provider environment variables configure credentials and alternate API endpoints.
- Migration generators are registered with versions/descriptions/implementation paths in migrations.json; repair forwards that registry to Nx, and generators mutate an Nx Tree and format it.
Contributor handoff
Tests and CI were inspected, not executed, and this brief provides bounded onboarding evidence rather than exhaustive coverage. Begin with contributor guidance, but resolve drift against manifests and executable source. Keep implementation, argument builders, public wrappers, and build entrypoints consistent. Release and e2e commands have material filesystem, process, Git, and registry side effects.
- Read AGENTS.md, CLAUDE.md, and CONTRIBUTING.md first, then verify against root package.json: this commit pins Node 26.10.0 and npm 12.1.0, despite older versions appearing in CLAUDE.md.
- Start a command change in its libs implementation and command.ts builder, inspect the published wrapper, and preserve exports/additional entrypoints when changing the public module surface.
- Read shared Command, Project, and graph enrichment before changing discovery: explicit lerna package globs select packages from the Nx graph and do not redefine the underlying workspace graph.
- Preserve ESM/CommonJS compatibility contracts: main exports a module.exports alias, selected command factories attach their classes, and package tests explicitly check synchronous require and ESM import behavior.
- For an authorized change, begin with the affected Nx test project; contributor guidance requires format, lint, unit, and integration checks and gates e2e behind other tests and build. None of these checks was executed in this investigation.
- Use the correct e2e target names from CONTRIBUTING.md and project configuration; modern task-runner e2e first prepares the local package, then runs a bash capture harness, while shared e2e defaults include retries.
- The build script must run at the workspace root and performs removal, Nx builds, npm install, and package copying; local registry configuration can affect later lockfile resolutions, so these are not source-inspection commands.
- Follow Oxlint module-boundary configuration and Oxfmt's 110-column style, use Conventional Commit scopes, and keep real releases in the gated GitHub workflow rather than invoking production publish locally.
Languages
| Language | Files | Share of source |
|---|---|---|
| JSON | 652 | docs/config |
| TypeScript | 591 | 92% |
| Markdown | 73 | docs/config |
| JavaScript | 32 | 5% |
| YAML | 16 | docs/config |
| Shell | 15 | 2% |
| CSS | 12 | docs/config |
| TOML | 1 | 0% |
Start reading here
Probable source entrypoint: packages/ — inferred from the directory tree and manifest, not the upstream docs.
Source roots
packages/ (87 files)
Repository structure
| Top-level path | Files |
|---|---|
libs/ | 868 |
e2e/ | 164 |
__fixtures__/ | 164 |
packages/ | 87 |
integration/ | 74 |
website/ | 70 |
.github/ | 16 |
tools/ | 10 |
Docs found: AGENTS.mdCLAUDE.mdCONTRIBUTING.mdREADME.md
Package
package.json — lerna-monorepo, 36 declared dependencies.
@nx/devkit@nx/esbuild@nx/js@nx/oxlint@nx/plugin@nx/vite@nx/vitest@nx/web@types/columnify@types/envinfo@types/fs-extra@types/libnpmpublish
CI & config entrypoints
README.md— Repository readmeAGENTS.md— Agent instructionsCLAUDE.md— Claude instructions.github/workflows/release.yml— GitHub Actions workflow.github/workflows/pkg-pr-new.yml— GitHub Actions workflow.github/workflows/nx-migrate.yml— GitHub Actions workflow.github/workflows/update-formatting-for-renovate.yml— GitHub Actions workflow.github/workflows/other-node-versions.yml— GitHub Actions workflow.github/workflows/website-deploy.yml— GitHub Actions workflow.github/workflows/ci.yml— GitHub Actions workflow
Structural health signals
Average score 8.5/10 across 96 analyzed source files; 4 hotspots surfaced.
libs/e2e-utils/src/lib/fixture.ts— 606 lines, score 5.2 (Large file, Deep nesting)libs/commands/publish/src/index.ts— 1261 lines, score 5.7 (Large file, Deep nesting)libs/commands/version/src/index.ts— 962 lines, score 6.2 (Large file, Deep nesting)
These are deterministic review leads — size, churn, and structural signals — not proof of a bug in this project.
Recent history
ce3e38f2889b2026-10-02 — chore: update dependency oxfmt to v0.70.0 (#4538)93682300054d2026-10-02 — chore: update vitest monorepo to v5 (#4508)5cf576627cc12026-10-02 — chore: switch lint and format to oxlint and oxfmt (#4537)87da4c1977c42026-10-02 — fix: update dependency @octokit/rest to v22 (#4517)430e67618ff32026-10-02 — feat: upgrade the npm publishing dependency stack (#4536)