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