Monorepo Manager

Overview

Analyze, maintain, and optimize monorepo dependency graphs. Detect version mismatches across packages, sync shared dependencies, configure build pipelines, and resolve workspace conflicts that slow teams down.

Instructions

1. Detect monorepo structure

Identify the monorepo tool in use:

• Check for pnpm-workspace.yaml → pnpm workspaces
• Check package.json for "workspaces" → npm/yarn workspaces
• Check for turbo.json → Turborepo
• Check for nx.json → Nx
• Check for lerna.json → Lerna (maintained by the Nx team; versioning and publishing)

Map all packages:

Monorepo: pnpm workspaces + Turborepo
Packages (14):
  apps/
    web          → Next.js 14 app
    api          → Express server
    admin        → React admin panel
  packages/
    ui           → Shared component library
    config       → ESLint/TS configs
    database     → Prisma schema + client
    utils        → Shared utilities
    types        → TypeScript type definitions

2. Audit dependency versions

Scan all package.json files and flag mismatches:

## Dependency Version Mismatches

| Package    | apps/web | apps/api | apps/admin | packages/ui |
|------------|----------|----------|------------|-------------|
| react      | 18.3.1   | —        | 18.2.0 ⚠️  | 18.3.1      |
| typescript | 5.4.2    | 5.3.3 ⚠️ | 5.4.2      | 5.4.2       |
| zod        | 3.22.4   | 3.21.1 ⚠️| —          | —           |

3 mismatches found across 14 packages.

3. Resolve conflicts

For each mismatch, recommend and apply fixes:

• Identify which version to standardize on (usually latest)
• Check for breaking changes between versions
• Update all package.json files
• Run the appropriate install command
• Verify build still passes

4. Analyze internal dependency graph

Map which packages depend on which:

packages/types ← packages/utils ← packages/ui ← apps/web
                                                ← apps/admin
               ← packages/database ← apps/api

Flag circular dependencies and suggest extraction points.

5. Optimize build configuration

For Turborepo/Nx, ensure:

• Build tasks declare correct dependsOn relationships ("^build" means "build my dependencies first"); in Turborepo 2.x tasks live under the tasks key of turbo.json (it was pipeline in 1.x)
• Caching is configured for all cacheable tasks
• Only affected packages rebuild on changes (turbo run build test --affected, nx affected -t build)
• CI pipeline uses remote caching (turbo login and turbo link, or Nx Cloud)

Examples

Example 1: Sync React versions

Input: "Our monorepo has 6 apps using different React versions. Sync them all."

Output:

Found React version mismatches:

| Package       | Current | Target |
|---------------|---------|--------|
| apps/web      | 18.3.1  | 18.3.1 ✅ |
| apps/admin    | 18.2.0  | 18.3.1 ⬆️ |
| apps/mobile   | 18.2.0  | 18.3.1 ⬆️ |
| packages/ui   | 18.3.1  | 18.3.1 ✅ |

Updated 2 package.json files. Run `pnpm install` to apply.

Breaking changes in 18.2→18.3: None (patch release).
Recommend running `pnpm turbo build` to verify all packages compile.

Example 2: Add shared dependency

Input: "Add date-fns to packages/utils and make sure all apps use the same version"

Output:

Current date-fns usage:
- apps/web: date-fns@3.3.1
- apps/api: date-fns@2.30.0 (major version behind!)
- apps/admin: not installed

Plan:
1. Add date-fns@^4.1.0 to the pnpm catalog and to packages/utils
2. Upgrade apps/web from 3.3.1 → 4.x (no code changes expected)
3. Upgrade apps/api from 2.30.0 → 4.x (major jump — see migration notes)
4. Remove direct date-fns deps from apps, import via packages/utils

⚠️ date-fns v2→v3+ breaking changes:
- Per-function default imports (`import format from 'date-fns/format'`) are gone; use named imports from 'date-fns'
- Check the changelog for removed or renamed helpers before merging

Updated 4 package.json files. Review the v3 migration in apps/api.

Guidelines

• Always map the full dependency graph before making changes
• Check for breaking changes before bumping major versions
• Prefer hoisting shared deps to the root when possible
• Use the catalog: protocol (versions defined once in pnpm-workspace.yaml, pnpm 9.5+) or resolutions in yarn for version pinning
• A tool like syncpack list-mismatches can find drifting versions automatically in large repos
• After any dependency change, verify builds across all affected packages
• Circular dependencies between packages are a code smell — suggest extraction
• For large monorepos (50+ packages), prioritize the most impactful mismatches first
• Internal packages should use workspace:* protocol, not pinned versions