DOCSEARCHbyAlgolia
Submit Docs

Lerna Documentation

website·Indexed 30 days ago

https://lerna.js.org

Lerna is a build system for managing and publishing multiple JavaScript/TypeScript packages from a single monorepo. It provides features for versioning, publishing to NPM, task caching, and distributed task execution. Now stewarded by Nx, Lerna integrates with Nx for advanced caching and task pipelines, and supports package managers including pnpm and Bun.

Tokens
11.2K
Snippets
66
Records
101
Agent score
74%

What's inside Lerna

  1. Overview of Lerna monorepo tool capabilities

    Lerna is a monorepo tool for JavaScript and TypeScript designed to solve two primary challenges in large-scale projects: efficient task execution across multiple projects and the management of the NPM publishing process (including versioning). Since v6, Lerna integrates the Nx task runner to provide advanced features such as computation caching and distributed task execution.

  2. Understand Lerna's computation hashing and caching

    Lerna uses a computation hash to determine if a task needs to be executed or can be replayed from cache. The hash is computed based on source files, global configuration, external dependency versions, runtime values (like Node version), and CLI flags passed to the script. If a matching hash is found locally or in a configured remote cache, Lerna restores the generated files and replays the terminal output (stdout/stderr) instead of running the task.

  3. Leverage Lerna monorepos for AI agent efficiency

    AI agents perform better in Lerna monorepos because they have access to a single working tree and a project dependency graph. While agents can trace imports and dependencies, they struggle to understand the broader relationship between projects. Lerna provides this context via the underlying Nx graph, allowing agents to identify which projects are affected by changes and which projects are relevant to a specific task.

  4. Use Lerna Workspace Watching to automate tasks on file changes

    Available as of Lerna 6.4.0, lerna watch monitors file changes within packages and automatically executes a specified command from the repository root. This eliminates the need to set up individual watchers for every package in a monorepo.

  5. Nx Console Key Features

    Nx Console enhances the development workflow with the following capabilities:

    • AI Enhancements: Informs AI assistants about workspace architecture.
    • Visual UI for Generators: Provides an interactive interface with form validation for running Nx generators.
    • Project Details View: Visual exploration of projects and their associated tasks.
    • Task Execution: One-click task execution from within the editor.
    • Workspace Visualization: Visual exploration of the project dependency graph.
    • Nx Cloud Integration: Tracking for distributed task execution and CI pipeline runs.
    • Inferred Tasks: Discovery and execution of all available tasks, including those that are inferred.

  6. Understand how Lerna integrates with Nx

    Lerna uses Nx as its underlying engine to detect packages within a workspace and manage dependencies between them. By deferring to the Nx task runner, Lerna enables developers to run scripts in parallel, cache execution results, and distribute tasks across multiple machines while maintaining correct dependency order.

  7. Visualize the Lerna project dependency graph

    Lerna (and Nx) creates a dependency graph of all projects in a repository to ensure tasks run quickly and correctly. You can launch an interactive browser-based visualization of this graph to understand code architecture or debug Lerna's behavior. Within the visualization, you can:

    • Focus on specific projects using proximity and 'group by folder' controls.
    • Search for projects by name.
    • Manually toggle project visibility via the sidebar.
    • Click individual dependency links to identify the specific files that created the dependency.
    nx graph

  8. Run multiple npm scripts concurrently

    You can trigger multiple targets simultaneously by providing a comma-delimited list of npm script names. If dependencies exist between these tasks, Lerna will coordinate the execution order provided a Task Pipeline Configuration is defined.
    npx lerna run test,build,lint

  9. Initialize a new Lerna monorepo

    Lerna is a build system used to manage and publish multiple JavaScript or TypeScript packages within a single repository (monorepo). To initialize a new Lerna project in an existing or new directory, use the lerna init command via npx.
    npx lerna init

  10. Debug Jest tests in Lerna packages using VS Code

    To debug Jest tests for a specific package within a Lerna monorepo using VS Code, add a launch configuration to .vscode/launch.json. This setup uses lerna exec to target the specific package and runs Jest with --runInBand (to avoid parallelization) and --no-cache.
    {
    "name": "Jest my-package",
    "type": "node",
    "request": "launch",
    "address": "localhost",
    "protocol": "inspector",
    "runtimeExecutable": "${workspaceRoot}/node_modules/.bin/lerna",
    "runtimeArgs": [
        "exec",
        "--scope",
        "my-package",
        "--",
        "node"
    ],
    "args": [
        "${workspaceRoot}/node_modules/jest/bin/jest.js",
        "--runInBand",
        "--no-cache",
        "packages/my-package"
    ]
}

  11. Replay and restore cached task outputs

    When Lerna determines that task inputs have not changed, it restores the cached results instead of re-running the task. This includes both the terminal output and the files created in the task's defined output directories. If you delete a build artifact folder (e.g., dist) and run the command again, Lerna will instantly recreate those files from the cache.
    # Example: running a cached build for a specific package
lerna run build --scope=header

  12. Manage AI agents across multiple repositories using meta-harnesses

    In multi-repo setups, AI agents typically lack knowledge of related repositories, access to those repositories, and the ability to coordinate changes across them. To bridge this gap, 'meta-harnesses' (such as Polygraph) can be used to wrap underlying AI tools (like Claude Code or Codex). These tools provide a unified cross-repo graph, durable sessions to maintain context across repository boundaries, and shared memory to coordinate changes across separate repos.