agentleFS
nisarthnisarth/claude-skills-store/skills/engineering/monorepo-management/SKILL.md

monorepo-management

Skill1 starsChanged 7 months agoMITView on GitHub

Manage monorepo workflows: workspace configuration, dependency management, selective builds, code ownership, and tooling setup with Turborepo, Nx, pnpm workspaces, Yarn workspaces, or Lerna. Trigger with "set up monorepo", "monorepo workspace", "turborepo config", "nx setup", "shared packages", "workspace dependencies", or when the user needs help organizing, building, or maintaining a monorepo.

  • Reads credentials
  • Installs packages

7 other projects use a version of this.

Adopted by

Most recently taken up by

The file

Show its rules and text

We split this skill into the rules it gives an agent

17 rules. 0 are common, 8 are distinctive, and 9 are very specific to this project.

  • 0

    Common

    Most of the 7 edited versions we read keep these.

  • 8

    Distinctive

    This author's own choices. Worth a look.

  • 9

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Check for existing config: Look for turbo.json, nx.json, lerna.json, pnpm-workspace.yaml, root package.json with workspaces.

    line 35
  2. Very specific:

    Map dependencies: Check which packages depend on which using package.json files.

    line 37
  3. Very specific:

    Identify build tools: Check for tsconfig.json, vite.config.ts, webpack.config.js, esbuild usage.

    line 38
  4. Distinctive:

    Check CI/CD: Look for existing pipeline configs to understand current build process.

    line 39
  5. Distinctive:

    Package naming convention: Use a scope prefix for all packages:

    line 73
  6. Distinctive:

    Keep runtime dependencies in individual packages for clear dependency graphs.

    line 166
  7. Very specific:

    Use catalog: protocol (pnpm 9+) or syncpack to keep versions aligned.

    line 167
  8. Distinctive:

    Action: Create directory structure, configure pnpm workspaces, set up Turborepo, create shared config packages, configure TypeScript …

    line 319
  9. Very specific:

    Action: Create the package directory, initialize package.json with build/test scripts, configure tsup or equivalent for dual CJS/ESM …

    line 322
  10. Very specific:

    Action: Create a config-typescript package with base tsconfig, extend it in each package with "extends": …

    line 328
  11. Distinctive:

    Keep shared packages small and focused.

    line 332
  12. Very specific:

    Use workspace:* protocol for internal dependencies so they always resolve to the local version.

    line 333
  13. Distinctive:

    Use CODEOWNERS to enforce review requirements per package.

    line 336
  14. Very specific:

    Run turbo build --filter=...[main] in CI to only build packages affected by the PR, not the entire repo.

    line 338
  15. Distinctive:

    Create a template or generator script for adding new packages to ensure consistency.

    line 339
  16. Distinctive:

    Document the monorepo conventions in a root CONTRIBUTING guide so new developers know the patterns.

    line 340
  17. Very specific:

    Avoid circular dependencies between packages.

    line 341

“Common” is measured: kept by at least 6 in 10 of the 7 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Monorepo Management

Set up and maintain monorepo workflows. Covers workspace configuration, dependency management, selective builds, code ownership, and CI/CD integration for monorepos using Turborepo, Nx, pnpm workspaces, Yarn workspaces, or Lerna.

Workflow

Step 1: Assess the Current State

Understand the project structure and needs:

  • Check for existing config: Look for turbo.json, nx.json, lerna.json, pnpm-workspace.yaml, root package.json with workspaces.
  • Count packages: List all packages/apps in the repo with ls packages/ apps/ or equivalent.
  • Map dependencies: Check which packages depend on which using package.json files.
  • Identify build tools: Check for tsconfig.json, vite.config.ts, webpack.config.js, esbuild usage.
  • Check CI/CD: Look for existing pipeline configs to understand current build process.

Step 2: Workspace Structure

Recommend a standard directory layout:

monorepo/
  apps/                    # Deployable applications
    web/                   # Frontend app
      package.json
      src/
    api/                   # Backend API
      package.json
      src/
  packages/                # Shared libraries
    ui/                    # Shared UI components
      package.json
      src/
    utils/                 # Shared utilities
      package.json
      src/
    config-eslint/         # Shared ESLint config
      package.json
    config-typescript/     # Shared TSConfig
      package.json
      tsconfig.base.json
  package.json             # Root package.json
  turbo.json               # Turborepo config (or nx.json)
  pnpm-workspace.yaml      # Workspace definition
  .github/
    CODEOWNERS             # Code ownership

Package naming convention: Use a scope prefix for all packages:

  • @myorg/ui, @myorg/utils, @myorg/config-eslint
  • Apps use the scope too: @myorg/web, @myorg/api

Step 3: Workspace Configuration

pnpm workspaces (recommended for performance):

# pnpm-workspace.yaml
packages:
  - 'apps/*'
  - 'packages/*'

Root package.json:

{
  "name": "@myorg/monorepo",
  "private": true,
  "scripts": {
    "build": "turbo build",
    "dev": "turbo dev",
    "lint": "turbo lint",
    "test": "turbo test",
    "clean": "turbo clean"
  },
  "devDependencies": {
    "turbo": "^2.0.0"
  }
}

Turborepo configuration:

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

Nx configuration (alternative):

{
  "targetDefaults": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["{projectRoot}/dist"]
    },
    "test": {
      "dependsOn": ["build"]
    }
  },
  "defaultBase": "main"
}

Step 4: Dependency Management

Internal dependencies (packages referencing each other):

{
  "name": "@myorg/web",
  "dependencies": {
    "@myorg/ui": "workspace:*",
    "@myorg/utils": "workspace:*"
  }
}

Shared dependencies (hoisting strategy):

  • Hoist common devDependencies to root: TypeScript, ESLint, Prettier, testing frameworks.
  • Keep runtime dependencies in individual packages for clear dependency graphs.
  • Use catalog: protocol (pnpm 9+) or syncpack to keep versions aligned.

Version alignment:

# Check for mismatched versions across packages
npx syncpack list-mismatches

# Fix mismatches
npx syncpack fix-mismatches

Adding a dependency:

# Add to a specific package
pnpm add lodash --filter @myorg/utils

# Add dev dependency to root
pnpm add -D typescript -w

# Add to all packages matching a pattern
pnpm add -D vitest --filter './packages/*'

Step 5: Selective Builds and Caching

Build only affected packages:

# Turborepo: build only packages affected by changes since main
turbo build --filter=...[main]

# Nx: run only affected projects
npx nx affected --target=build --base=main

Remote caching (Turborepo):

# Link to remote cache (Vercel)
npx turbo login
npx turbo link

# Or self-hosted with turbo-remote-cache

CI/CD integration with selective builds:

# GitHub Actions with Turborepo
- name: Build affected packages
  run: npx turbo build --filter=...[HEAD^1]

# Or use change detection
- uses: dorny/paths-filter@v3
  id: changes
  with:
    filters: |
      web:
        - 'apps/web/**'
        - 'packages/ui/**'
      api:
        - 'apps/api/**'
        - 'packages/utils/**'

Step 6: Code Ownership

CODEOWNERS file:

# Default owner
* @org/engineering

# App-specific owners
/apps/web/ @org/frontend-team
/apps/api/ @org/backend-team

# Shared packages
/packages/ui/ @org/frontend-team @org/design-system
/packages/utils/ @org/platform-team

# Infrastructure
/packages/config-*/ @org/platform-team
/.github/ @org/platform-team
turbo.json @org/platform-team

Step 7: Adding a New Package

Standard procedure for adding a package to the monorepo:

# Create the package directory
mkdir -p packages/new-package/src

# Initialize package.json
cat > packages/new-package/package.json << 'EOF'
{
  "name": "@myorg/new-package",
  "version": "0.0.0",
  "private": true,
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "scripts": {
    "build": "tsup src/index.ts --format cjs,esm --dts",
    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
    "lint": "eslint src/",
    "test": "vitest run"
  }
}
EOF

# Create entry point
echo 'export {}' > packages/new-package/src/index.ts

# Install dependencies
pnpm install

Output Format

## Monorepo Configuration

### Structure
<directory tree>

### Workspace Config
<pnpm-workspace.yaml or package.json workspaces>

### Build Pipeline
<turbo.json or nx.json>
**Task graph**: <dependency visualization>

### Package Dependency Map
| Package | Depends On | Depended On By |
|---------|-----------|----------------|
| @myorg/ui | @myorg/utils | @myorg/web |

### CI/CD Integration
<selective build configuration>

### Code Ownership
<CODEOWNERS content>

### Commands Reference
| Command | Purpose |
|---------|---------|
| `pnpm build` | Build all packages |
| `pnpm dev` | Dev mode for all packages |
| `turbo build --filter=@myorg/web...` | Build web and its dependencies |

Examples

User: "Set up a monorepo for our React frontend and Node.js API with shared packages" Action: Create directory structure, configure pnpm workspaces, set up Turborepo, create shared config packages, configure TypeScript project references.

User: "Add a new shared UI component library to the monorepo" Action: Create the package directory, initialize package.json with build/test scripts, configure tsup or equivalent for dual CJS/ESM output, add to consuming packages.

User: "Our CI builds everything on every PR, it takes 15 minutes" Action: Analyze the build pipeline, add Turborepo's affected filter, configure remote caching, set up path-based job filtering in CI.

User: "How do I share TypeScript config across packages?" Action: Create a config-typescript package with base tsconfig, extend it in each package with "extends": "@myorg/config-typescript/base.json", configure project references for type-checking.

Best Practices

  • Keep shared packages small and focused. A package that does too many things forces unnecessary dependencies on consumers.
  • Use workspace:* protocol for internal dependencies so they always resolve to the local version.
  • Hoist common dev tools (TypeScript, ESLint, Prettier) to the root but keep runtime dependencies local.
  • Set up remote caching early. The time saved compounds quickly as the repo grows.
  • Use CODEOWNERS to enforce review requirements per package. This prevents unreviewed changes to shared infrastructure.
  • Pin the monorepo tool version in the root package.json to prevent inconsistencies across developer machines.
  • Run turbo build --filter=...[main] in CI to only build packages affected by the PR, not the entire repo.
  • Create a template or generator script for adding new packages to ensure consistency.
  • Document the monorepo conventions in a root CONTRIBUTING guide so new developers know the patterns.
  • Avoid circular dependencies between packages. Use turbo or nx graph visualization to detect them.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.