Monorepo (Lerna) Setup for Web Project

Monorepo Setup (Lerna) for Web Project

Lerna—one of first JavaScript monorepo tools. Long de-facto standard, lost popularity, then revived v6+ under Nrwl (Nx creators) with Nx integration. Today Lerna—good choice for projects needing package versioning and npm publishing, but not complex Nx infrastructure.

When Lerna, Not Turborepo or Nx

Lerna makes sense when:

• Project—library or package set published to npm
• Need automatic versioning (semver) and CHANGELOG
• Small team, complex infrastructure overkill

For closed product without npm publishing—better Turborepo or Nx.

Initialization

# New monorepo
npx lerna init --packages="packages/*" --independent
cd my-monorepo

# Or add to existing
npm install lerna --save-dev
npx lerna init

--independent—each package versioned separately. Alternative—fixed mode, all packages one version.

Configuration lerna.json

{
  "$schema": "node_modules/lerna/schemas/lerna-schema.json",
  "version": "independent",
  "npmClient": "pnpm",
  "command": {
    "publish": {
      "conventionalCommits": true,
      "createRelease": "github",
      "registry": "https://registry.npmjs.org"
    },
    "version": {
      "conventionalCommits": true,
      "gitTagVersion": true,
      "push": true
    }
  },
  "useWorkspaces": true,
  "useNx": true
}

conventionalCommits: true—Lerna determines versioning by commit format: fix: → patch, feat: → minor, BREAKING CHANGE → major.

Structure for Component Library

my-ui-library/
├── packages/
│   ├── button/
│   │   ├── src/
│   │   ├── package.json
│   ├── input/
│   ├── modal/
├── apps/
│   └── docs/
├── lerna.json
└── pnpm-workspace.yaml

// packages/button/package.json
{
  "name": "@acme/button",
  "version": "1.2.0",
  "main": "./dist/index.js",
  "module": "./dist/index.mjs",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/index.mjs",
      "require": "./dist/index.js",
      "types": "./dist/index.d.ts"
    }
  },
  "scripts": {
    "build": "tsup src/index.ts --format cjs,esm --dts",
    "dev": "tsup src/index.ts --watch",
    "test": "vitest run"
  },
  "peerDependencies": {
    "react": ">=17.0.0"
  },
  "devDependencies": {
    "@acme/theme": "workspace:*"
  }
}

Version Management

# Determine changes (dry run)
npx lerna changed

# Update versions interactively
npx lerna version

# Automatically by conventional commits
npx lerna version --conventional-commits --yes

# Prerelease version (beta)
npx lerna version --conventional-commits --conventional-prerelease --preid=beta

lerna version process:

1. Finds changed packages
2. Proposes new versions by semver rules
3. Updates package.json and interdependencies
4. Generates CHANGELOG.md
5. Creates git commit and tags

Publishing

# Publish all unpublished packages
npx lerna publish from-package

# Publish changed (after lerna version)
npx lerna publish from-git

# To private registry
npx lerna publish from-git --registry=https://npm.pkg.github.com

# .github/workflows/release.yml
jobs:
  release:
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - run: pnpm install --frozen-lockfile
      - run: npx lerna run build
      - run: npx lerna version --conventional-commits --yes --no-push
      - run: npx lerna publish from-git --yes
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

Run Tasks with Nx Under the Hood

Lerna 6+ uses Nx for smart task execution:

# Build all packages parallel with cache
npx lerna run build

# Only changed packages
npx lerna run test --since=main

# Package and dependents
npx lerna run build --scope=@acme/modal --include-dependents

// nx.json (auto-created with --useNx)
{
  "extends": "nx/presets/npm.json",
  "targetDefaults": {
    "build": {
      "dependsOn": ["^build"],
      "cache": true
    }
  }
}

Dependency Management Between Packages

# Add dependency to specific package
pnpm add react --filter @acme/button

# Add local package as dependency
pnpm add @acme/theme --filter @acme/button --workspace

# Add devDependency to all packages
pnpm add -D typescript --recursive

If package A depends on B and B changed—lerna run build --scope=A --include-dependencies rebuilds B first.

Common Issues

Dependency version not updating on lerna version—check dependency without ^ or ~, else Lerna won't hardcode update. Use --force-publish to force all.

CHANGELOG duplicates—Lerna includes only commits touching files. Use --changelog-include-commits-root-path for root commits.

Publishing fails on CI due npm publish --dry-run in .npmrc—ensure dry-run=false in CI.

Timeline

Setup Lerna for npm package set from scratch—2–3 days: configuration, conventional commits (commitlint + husky), CI/CD for auto publishing, document release process for team.