lerna

SKILL.md

Lerna Monorepo Development

You are an expert in Lerna, the fast, modern build system for managing and publishing multiple JavaScript/TypeScript packages.

Project Structure

Organize packages following Lerna conventions:

packages/ - All package directories (default)

Can customize with multiple directories in lerna.json

Each package should be self-contained with its own:

package.json

Source code

Tests

Build configuration

Lerna Configuration

Configure lerna.json at the root:
{
  "$schema": "https://json.schemastore.org/lerna.json",
  "version": "independent",
  "npmClient": "npm",
  "packages": ["packages/*"],
  "useWorkspaces": true
}

Choose versioning mode:

"version": "independent" - Each package versioned separately

"version": "1.0.0" - Fixed/locked mode, all packages same version

Enable workspaces integration with useWorkspaces: true

Workspaces Integration

Configure npm/yarn/pnpm workspaces in root package.json:

{
  "workspaces": ["packages/*"],
  "private": true
}

Let the package manager handle hoisting and linking

Use Lerna for versioning, publishing, and running scripts

Task Execution

Run scripts across packages:

lerna run build - Run build in all packages

lerna run test --scope=@org/package - Run in specific package

lerna run lint --since main - Run only in changed packages

Use --stream for real-time output

Use --parallel for concurrent execution

Versioning Workflow

Update versions with lerna version:

lerna version patch - Bump patch version

lerna version minor - Bump minor version

lerna version major - Bump major version

lerna version - Interactive version selection

Lerna automatically:

Updates package.json versions

Updates internal dependency versions

Creates git tags

Pushes to remote

Publishing Packages

Publish with lerna publish:

lerna publish - Publish packages changed since last release

lerna publish from-git - Publish packages tagged in git

lerna publish from-package - Publish packages with unpublished versions

Configure npm registry in .npmrc or lerna.json

Use --dist-tag for pre-release versions

Change Detection

Use --since flag for changed packages:

lerna run test --since main

lerna changed - List packages changed since last tag

lerna diff - Show diff since last release

Leverage affected commands in CI for efficiency

Conventional Commits

Enable conventional commits for automated versioning:

{
  "command": {
    "version": {
      "conventionalCommits": true,
      "message": "chore(release): publish"
    }
  }
}

Commits determine version bumps:

fix: - Patch version

feat: - Minor version

BREAKING CHANGE: - Major version

Automatic changelog generation

Dependency Management

Use internal package references:
{
  "dependencies": {
    "@org/shared-utils": "^1.0.0"
  }
}

Lerna keeps internal dependencies in sync during versioning

Hoist common dependencies to root with workspaces

CI/CD Integration

Install dependencies once at root level

Use lerna run with --since for efficient CI

Publish from CI with proper npm authentication

Use --yes flag for non-interactive publishing

Best Practices

Keep packages focused and single-purpose

Use consistent package naming: @org/package-name

Maintain clear dependency boundaries between packages

Document package APIs and usage

Use TypeScript with project references for type checking

Implement proper testing at package and integration levels

Consider Nx integration for advanced caching and task execution