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:
  json

  {
    "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