monorepo-management

Monorepo Management

Organize and build multi-package repositories efficiently.

When to Monorepo

Situation	Monorepo	Polyrepo
Shared libraries across packages	Yes	No
Tight coupling between packages	Yes	No
Independent release cycles needed	No	Yes
Different teams, different cadences	No	Yes
Atomic cross-package changes	Yes	No
< 20 packages	Yes	Either
> 100 packages	Depends	Often better

JavaScript/TypeScript Workspaces

pnpm Workspaces

# pnpm-workspace.yaml
packages:
  - "packages/*"
  - "apps/*"
  - "tools/*"

// package.json (root)
{
  "private": true,
  "scripts": {
    "build": "turbo build",
    "test": "turbo test",
    "lint": "turbo lint"
  }
}

Package Structure

monorepo/
├── pnpm-workspace.yaml
├── turbo.json
├── package.json
├── packages/
│   ├── ui/                # Shared UI components
│   │   ├── package.json
│   │   └── src/
│   ├── config/            # Shared config (ESLint, TS)
│   │   └── package.json
│   └── utils/             # Shared utilities
│       └── package.json
├── apps/
│   ├── web/               # Next.js app
│   │   └── package.json
│   └── api/               # Express API
│       └── package.json
└── tools/
    └── scripts/           # Build/deploy scripts

Internal Package References

// apps/web/package.json
{
  "dependencies": {
    "@myorg/ui": "workspace:*",
    "@myorg/utils": "workspace:*"
  }
}

Turborepo Configuration

// turbo.json
{
  "$schema": "https://turbo.build/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**"]
    },
    "test": {
      "dependsOn": ["build"],
      "outputs": []
    },
    "lint": {
      "outputs": []
    },
    "dev": {
      "persistent": true,
      "cache": false
    }
  }
}

Filtered Builds

# Build only packages affected by changes
turbo build --filter=...[HEAD~1]

# Build a specific package and its dependencies
turbo build --filter=@myorg/web

# Build everything that depends on a package
turbo build --filter=...@myorg/ui

Python Monorepo Patterns

Using a Shared Virtualenv

monorepo/
├── pyproject.toml          # Root with all optional deps
├── packages/
│   ├── core/
│   │   ├── pyproject.toml
│   │   └── src/core/
│   ├── api/
│   │   ├── pyproject.toml
│   │   └── src/api/
│   └── worker/
│       ├── pyproject.toml
│       └── src/worker/
└── tests/

# Root pyproject.toml
[project]
name = "monorepo"
dependencies = []

[project.optional-dependencies]
core = ["./packages/core"]
api = ["./packages/api"]
worker = ["./packages/worker"]
dev = ["pytest", "ruff", "mypy"]
all = ["monorepo[core,api,worker,dev]"]

pip install -e ".[all]"

Namespace Packages

packages/core/src/myorg/core/__init__.py
packages/api/src/myorg/api/__init__.py
# Both install into the `myorg` namespace

Dependency Management

Version Consistency

// .syncpackrc (syncpack)
{
  "versionGroups": [
    {
      "dependencies": ["react", "react-dom"],
      "packages": ["**"],
      "pinVersion": "^18.3.0"
    }
  ]
}

# Check version consistency
syncpack list-mismatches
# Fix mismatches
syncpack fix-mismatches

Dependency Graph

# Visualize internal dependencies
turbo ls --graph

# nx
nx graph

CI/CD for Monorepos

Change Detection

#!/usr/bin/env bash
set -euo pipefail

# Detect which packages changed
CHANGED=$(git diff --name-only HEAD~1 | grep '^packages/' | cut -d/ -f2 | sort -u)

for pkg in $CHANGED; do
    echo "Building packages/$pkg"
    cd "packages/$pkg" && npm run build && cd ../..
done

GitHub Actions Matrix

jobs:
  detect-changes:
    runs-on: ubuntu-latest
    outputs:
      packages: ${{ steps.changes.outputs.packages }}
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 2 }
      - id: changes
        run: |
          PKGS=$(git diff --name-only HEAD~1 | grep '^packages/' | cut -d/ -f2 | sort -u | jq -R -s -c 'split("\n") | map(select(. != ""))')
          echo "packages=$PKGS" >> $GITHUB_OUTPUT

  build:
    needs: detect-changes
    if: needs.detect-changes.outputs.packages != '[]'
    strategy:
      matrix:
        package: ${{ fromJson(needs.detect-changes.outputs.packages) }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: cd packages/${{ matrix.package }} && npm ci && npm run build

Anti-Patterns

• No task runner — Manual build ordering doesn't scale; use Turborepo or Nx
• Circular dependencies — Packages must form a DAG; validate in CI
• Everything in one package.json — Separate packages even in a monorepo
• No change detection in CI — Building everything on every commit wastes time
• Version drift — Enforce consistent dependency versions with syncpack or similar
• Implicit dependencies — Always declare package-level dependencies explicitly