Claude Code Lerna Independent Versioning Workflow Tutorial

Managing multiple npm packages in a monorepo presents unique versioning challenges. When each package has its own release cycle, dependencies, and consumer base, synchronized versioning becomes a bottleneck. Lerna’s independent versioning mode solves this by allowing each package to maintain its own semantic version. Combined with Claude Code’s automation capabilities, you can build a powerful workflow that streamlines multi-package releases.

This tutorial walks you through setting up Lerna with independent versioning and integrating Claude Code for intelligent version management and automated releases.

Understanding Lerna’s Versioning Modes

Lerna offers two versioning strategies: fixed and independent. In fixed mode, all packages share a single version number that increments together. While simple, this approach forces coordinated releases even when only one package changed.

Independent mode grants each package complete version autonomy. You bump only what changed, when it changed. This aligns with microservices architecture principles where each component evolves at its own pace.

To initialize Lerna in independent mode:

# Create a new Lerna repo with independent versioning
npx lerna init --independent

# Or convert existing fixed-mode repo
lerna bootstrap
# Then update lerna.json to set "version": "independent"

Your lerna.json should include:

{
  "packages": ["packages/*"],
  "version": "independent",
  "npmClient": "yarn",
  "useWorkspaces": true
}

Setting Up Your Monorepo Structure

Organize your monorepo with a clear packages directory:

my-monorepo/
├── packages/
│   ├── core/           # Core utilities
│   ├── ui-components/  # Reusable UI components
│   ├── api-client/     # HTTP client library
│   └── utils/          # Helper functions
├── lerna.json
├── package.json
└── yarn.lock

Each package needs its own package.json with proper name and version:

{
  "name": "@myorg/ui-components",
  "version": "1.2.0",
  "main": "dist/index.js",
  "dependencies": {
    "@myorg/core": "^1.0.0"
  }
}

Notice the caret (^) in dependencies—this allows each package to specify version ranges rather than exact matches, supporting independent evolution.

Integrating Claude Code for Version Management

Claude Code can assist with intelligent version bumping, changelog generation, and release automation. Create a skill that understands your monorepo structure and applies consistent versioning policies.

Here’s a practical workflow:

1. Analyze What Changed

Before bumping versions, Claude Code analyzes git commits since the last release:

# Get commits since last tag
git log $(git describe --tags --abbrev=0)..HEAD --oneline

Based on commit messages following conventional commits, Claude determines version impact:

feat: → minor version bump
fix: → patch version bump
BREAKING CHANGE: → major version bump

2. Bump Versions Selectively

Run version bumps only for changed packages:

# Lerna handles version bumping for changed packages
lerna version --conventional-commits --yes

# This updates only packages with new commits
# and creates git tags like: @myorg/ui-components@1.3.0

3. Generate Changelogs Automatically

Lerna’s conventional commits integration generates changelogs:

lerna version --conventional-commits \
  --changelog-release-prefix=" Changes" \
  --yes

This creates detailed changelogs showing exactly what changed in each package.

Practical Workflow Example

Here’s a complete workflow for managing independent versions with Claude Code:

Step 1: Initialize the Monorepo

mkdir my-org && cd my-org
npx lerna init --independent
npm install -D lerna conventional-changelog-conventionalcommits

Step 2: Configure Conventional Commits

In lerna.json:

{
  "packages": ["packages/*"],
  "version": "independent",
  "command": {
    "version": {
      "conventionalCommits": true,
      "changelogPreset": "conventional-changelog-conventionalcommits"
    }
  }
}

Step 3: Create a Release Script

Add to your root package.json:

{
  "scripts": {
    "release": "lerna version --conventional-commits --yes",
    "publish": "lerna publish from-git --yes"
  }
}

Step 4: Execute the Release

# Analyze changes, bump versions, generate changelogs
npm run release

# Publish to npm
npm run publish

Handling Dependencies Between Packages

Independent versioning requires careful dependency management. When package A depends on package B, you need strategies to prevent breakage:

Strategy 1: Flexible Version Ranges

Use caret (^) or tilde (~) ranges in dependencies:

"dependencies": {
  "@myorg/core": "^1.0.0"
}

This allows patch and minor updates without breaking changes.

Strategy 2: Lerna’s Dependency Graph

Lerna automatically links local packages during development:

# Links local packages before running scripts
lerna bootstrap --scope=@myorg/ui-components

Strategy 3: CI Validation

Add continuous integration checks to catch version mismatches:

# Check for outdated dependencies
npm run audit:deps

# Verify peer dependency compatibility
lerna exec -- npm ls peerDependencies

Best Practices for Independent Versioning

Adopt Conventional Commits: Structure commit messages consistently so Lerna can determine version impact automatically.
Use Lockfiles: Always commit yarn.lock or package-lock.json to ensure reproducible installs.
Test Each Package: Run tests for affected packages only:
```
lerna run test --scope=@myorg/ui-components
```

Automate Publishing: Set up CI pipelines that publish only on tagged commits:

# GitHub Actions example
on:
  push:
    tags:
      - 'v*'
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
      - run: npm ci
      - run: npm run publish

Document Breaking Changes: Maintain a CHANGELOG.md in each package root, or rely on Lerna’s automatic generation.

Common Pitfalls to Avoid

Overly Strict Ranges: Avoid exact versions (1.0.0) in internal dependencies—they defeat independent versioning’s purpose.
Forgetting to Bootstrap: After pulling changes, always run lerna bootstrap to ensure symlinks are created.
Skipping Tests: Independent versioning means changes in one package can affect consumers. Run comprehensive tests before publishing.
Manual Version Bumps: Let Lerna’s conventional commits handle versioning—manual bumps introduce human error.

Conclusion

Lerna’s independent versioning mode, combined with Claude Code’s automation capabilities, provides a robust foundation for monorepo package management. Each package evolves at its own pace while maintaining dependency compatibility through flexible version ranges.

Start with the workflow outlined here: initialize in independent mode, adopt conventional commits, and automate releases through CI/CD. Your monorepo will scale cleanly as you add more packages, each with its own release cadence managed efficiently.

The key is consistency—standardized commit messages, automated version detection, and thorough testing. With these practices in place, independent versioning becomes not just possible, but the natural way to manage complex monorepos.

Built by theluckystrike — More at zovo.one