monorepo-tooling

What this skill does

# Monorepo Tooling Skill

## Overview

This skill provides comprehensive guidance on monorepo build systems, task
runners, package managers, and development tools that enable efficient
development, building, and testing across multiple packages in a monorepo.

## Build Systems

### Turborepo

High-performance build system with intelligent caching and task orchestration.

#### Pipeline Configuration

```json
{
  "$schema": "https://turbo.build/schema.json",
  "globalDependencies": [
    ".env",
    "tsconfig.json"
  ],
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [
        "dist/**",
        ".next/**",
        "build/**"
      ],
      "cache": true
    },
    "test": {
      "dependsOn": ["build"],
      "outputs": ["coverage/**"],
      "cache": true
    },
    "lint": {
      "outputs": [],
      "cache": true
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "deploy": {
      "dependsOn": ["build", "test", "lint"],
      "cache": false
    }
  },
  "globalEnv": [
    "NODE_ENV",
    "CI"
  ]
}
```

#### Remote Cache Configuration

```json
{
  "remoteCache": {
    "enabled": true
  }
}
```

With Vercel:

```bash
# Link to Vercel for remote caching
turbo login
turbo link
```

With custom cache:

```json
{
  "remoteCache": {
    "enabled": true,
    "signature": true,
    "preflight": true
  }
}
```

#### Key Features

- **Incremental builds**: Only rebuild changed packages
- **Remote caching**: Share cache across team and CI
- **Parallel execution**: Run tasks in parallel when safe
- **Pipeline dependencies**: Automatic task ordering
- **Pruning**: Extract subset of monorepo
- **Filtering**: Run tasks on specific packages

**Usage**:

```bash
# Run build across all packages
turbo run build

# Run with filter
turbo run build --filter=@myorg/web

# Run with dependencies
turbo run build --filter=@myorg/web...

# Force rebuild (skip cache)
turbo run build --force

# Dry run
turbo run build --dry-run

# Prune for deployment
turbo prune --scope=@myorg/web
```

### Nx

Extensible build system with powerful code generation and analysis.

#### Workspace Configuration

```json
{
  "extends": "nx/presets/npm.json",
  "tasksRunnerOptions": {
    "default": {
      "runner": "nx/tasks-runners/default",
      "options": {
        "cacheableOperations": [
          "build",
          "test",
          "lint"
        ],
        "parallel": 3,
        "cacheDirectory": "node_modules/.cache/nx"
      }
    }
  },
  "targetDefaults": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["{projectRoot}/dist"],
      "cache": true
    },
    "test": {
      "inputs": [
        "default",
        "^production"
      ],
      "cache": true
    }
  },
  "namedInputs": {
    "default": [
      "{projectRoot}/**/*"
    ],
    "production": [
      "default",
      "!{projectRoot}/**/*.spec.ts"
    ]
  }
}
```

#### Project Configuration

```json
{
  "name": "web",
  "targets": {
    "build": {
      "executor": "@nx/webpack:webpack",
      "outputs": ["{options.outputPath}"],
      "options": {
        "outputPath": "dist/apps/web",
        "main": "apps/web/src/main.ts",
        "tsConfig": "apps/web/tsconfig.app.json"
      }
    },
    "serve": {
      "executor": "@nx/webpack:dev-server",
      "options": {
        "buildTarget": "web:build"
      }
    },
    "test": {
      "executor": "@nx/jest:jest",
      "outputs": ["{workspaceRoot}/coverage/apps/web"],
      "options": {
        "jestConfig": "apps/web/jest.config.ts"
      }
    }
  }
}
```

#### Nx Cloud Configuration

```json
{
  "nxCloudAccessToken": "YOUR_ACCESS_TOKEN",
  "tasksRunnerOptions": {
    "default": {
      "runner": "nx-cloud",
      "options": {
        "cacheableOperations": ["build", "test", "lint"],
        "accessToken": "YOUR_ACCESS_TOKEN"
      }
    }
  }
}
```

#### Nx Key Features

- **Computation caching**: Local and remote cache
- **Affected commands**: Run tasks on changed projects only
- **Code generators**: Scaffolding for new projects
- **Dependency graph**: Visualize project relationships
- **Module boundaries**: Enforce architectural rules
- **Distributed execution**: Parallel task execution

**Usage**:

```bash
# Run target on all projects
nx run-many --target=build --all

# Run on affected projects only
nx affected --target=test --base=main

# View dependency graph
nx graph

# Generate new library
nx generate @nx/js:library my-lib

# Run task on specific project
nx build web

# Clear cache
nx reset
```

### Bazel

Google's scalable build system for very large monorepos.

#### WORKSPACE File

```python
workspace(name = "my_workspace")

load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")

# Load Node.js rules
http_archive(
    name = "build_bazel_rules_nodejs",
    sha256 = "...",
    urls = ["https://github.com/bazelbuild/rules_nodejs/..."],
)

load("@build_bazel_rules_nodejs//:index.bzl", "node_repositories")

node_repositories(
    node_version = "18.16.0",
    package_manager = "pnpm",
)
```

#### BUILD File

```python
# packages/ui/BUILD.bazel
load("@build_bazel_rules_nodejs//:index.bzl", "pkg_npm")
load("@npm//@bazel/typescript:index.bzl", "ts_library")

ts_library(
    name = "ui",
    srcs = glob(["src/**/*.ts", "src/**/*.tsx"]),
    deps = [
        "@npm//react",
        "@npm//react-dom",
        "@npm//@types/react",
    ],
    visibility = ["//visibility:public"],
)

pkg_npm(
    name = "ui_pkg",
    deps = [":ui"],
    package_name = "@myorg/ui",
    substitutions = {
        "0.0.0-PLACEHOLDER": "{STABLE_VERSION}",
    },
)
```

#### Bazel Key Features

- **Hermetic builds**: Reproducible builds
- **Remote execution**: Distribute builds across machines
- **Fine-grained caching**: Cache at file level
- **Language agnostic**: Support many languages
- **Scalability**: Handle massive codebases
- **Build correctness**: Reliable dependency tracking

**Usage**:

```bash
# Build target
bazel build //packages/ui:ui

# Build all targets in package
bazel build //packages/ui/...

# Test target
bazel test //packages/ui:ui_test

# Run target
bazel run //apps/web:serve

# Clean builds
bazel clean

# Query dependency graph
bazel query 'deps(//packages/ui:ui)'
```

### Lerna

Multi-package repository management and publishing tool.

#### Lerna Configuration

```json
{
  "version": "independent",
  "npmClient": "pnpm",
  "useWorkspaces": true,
  "packages": [
    "packages/*",
    "apps/*"
  ],
  "command": {
    "publish": {
      "conventionalCommits": true,
      "message": "chore(release): publish",
      "ignoreChanges": [
        "**/__tests__/**",
        "**/*.md"
      ]
    },
    "version": {
      "allowBranch": ["main", "next"],
      "message": "chore(release): version packages"
    },
    "bootstrap": {
      "npmClientArgs": ["--no-package-lock"]
    }
  }
}
```

#### Lerna Key Features

- **Version management**: Fixed or independent versioning
- **Publishing**: Automated package publishing
- **Bootstrap**: Link local packages
- **Changed detection**: Identify modified packages
- **Conventional commits**: Automated changelogs
- **Workspace integration**: Works with NPM/Yarn/PNPM

**Usage**:

```bash
# Bootstrap packages
lerna bootstrap

# Run command in all packages
lerna run build

# Run command in changed packages
lerna run test --since origin/main

# Publish packages
lerna publish

# Publish from git tags
lerna publish from-git

# Version packages
lerna version

# List packages
lerna list
```

### Rush

Scalable monorepo manager with strict dependency management.

#### Rush Configuration

```json
{
  "rushVersion": "5.108.0",
  "pnpmVersion": "8.10.0",
  "nodeSupportedVersionRange": ">=18.0.0",
  "projectFolderMinDepth": 1,
  "projectFolderMaxDepth": 2,
  "projects": [
    {
      "packageName": "@myorg/web",
      "projectFolder": "apps/web",
      "reviewCategory": "production"
    },
    {
      "packageName": "@myorg/ui",
      "projectFolder": "packages/ui",
      "