Monorepo Patterns

Efficient workflows for navigating and working in monorepo codebases with Claude Code.

Quick Reference

Monorepo Structures

Common Layouts

# Packages Layout (Most Common)
monorepo/
  packages/
    core/
    ui/
    utils/
  package.json

# Apps + Packages Layout
monorepo/
  apps/
    web/
    api/
  packages/
    shared/
    ui/
  package.json

# Domain Layout
monorepo/
  domains/
    auth/
    billing/
    users/
  shared/
  package.json

Identifying Monorepo Type

# Check for workspace configuration
cat package.json | grep -A5 "workspaces"
ls turbo.json nx.json lerna.json pnpm-workspace.yaml 2>/dev/null

Context Scoping

Rule: Always Scope Before Working

Before making changes, identify which packages are relevant:

# Find the package you need to modify
rg -l "FunctionName" --type ts

# Check which workspace it belongs to
ls -la packages/*/package.json | head -20

# Read only the relevant package.json
cat packages/target-package/package.json

Scoping Workflow

1. Identify entry point - What file/feature are you modifying?
2. Find package boundary - Which package contains it?
3. Map dependencies - What does this package depend on?
4. Limit context - Only read files within scope

# Find package for a file
dirname $(rg -l "targetFunction" --type ts | head -1)

# List package dependencies
cat packages/target/package.json | grep -A20 "dependencies"

Navigating Large Codebases

Discovery Commands

# List all packages
ls packages/ 2>/dev/null || ls apps/ 2>/dev/null

# Find package by name
rg -l '"name".*"@org/package-name"' packages/

# Find packages using a dependency
rg '"dependency-name"' packages/*/package.json

# Find entry points
rg -l "export.*from" packages/*/src/index.ts

Understanding Package Relationships

# Show all internal dependencies
rg "@org/" packages/*/package.json --no-filename | sort -u

# Find packages depending on target
rg '"@org/target-package"' packages/*/package.json

# Visualize with tool (if available)
turbo run build --graph  # Opens browser
nx graph                 # Opens browser

Cross-Package Change Workflow

Step 1: Identify Scope

# What packages does this change affect?
rg -l "AffectedInterface" --type ts

# Check dependency direction
cat packages/affected/package.json | grep dependencies

Step 2: Determine Edit Order

Follow dependency graph - edit dependencies before dependents:

shared (no deps)      <- Edit first
    |
    v
utils (deps: shared)
    |
    v
core (deps: utils)
    |
    v
app (deps: core)      <- Edit last

Step 3: Edit in Order

• Edit shared types/interfaces first
• Update utility packages
• Modify core packages
• Update consuming apps
• Run affected tests

Step 4: Build and Test

# Build only affected packages
turbo run build --filter=...[HEAD^]
nx affected --target=build

# Test only affected packages
turbo run test --filter=...[HEAD^]
nx affected --target=test

Package-Specific Rules

Using Package-Level CLAUDE.md

Create .claude/CLAUDE.md in each package for specific instructions:

# packages/api/.claude/CLAUDE.md

## API Package Rules

- All routes in `src/routes/`
- Use Zod schemas from `@org/schemas`
- Tests must use `supertest`
- Run `bun test` before committing

## Common Patterns

- Route handlers export from index
- Middleware in `src/middleware/`

Workspace Root CLAUDE.md

# .claude/CLAUDE.md (root)

## Monorepo Rules

- Use `pnpm` for package management
- Run `turbo run build` for full build
- Run `turbo run test --filter=changed` for affected tests

## Package Locations

| Package | Purpose |
|---------|---------|
| `packages/core` | Business logic |
| `packages/ui` | React components |
| `apps/web` | Next.js frontend |
| `apps/api` | Express backend |

Build Optimization

Filtering Builds

# Build single package
turbo run build --filter=@org/package
pnpm --filter @org/package build
nx run @org/package:build

# Build package + dependencies
turbo run build --filter=@org/package...
pnpm --filter @org/package... build

# Build package + dependents
turbo run build --filter=...@org/package
pnpm --filter ...@org/package build

# Build only changed
turbo run build --filter=...[HEAD^]
nx affected --target=build

Cache Utilization

# Check cache status
turbo run build --dry-run

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

# Remote cache (if configured)
turbo run build --remote-only

Validation Checklist

After cross-package changes:

• Changed packages build successfully
• Dependent packages build successfully
• All affected tests pass
• No circular dependency introduced
• TypeScript resolves all cross-package types
• Exports are correctly defined in package.json

# Full validation
turbo run build test typecheck --filter=...@org/changed-package

Common Scenarios

Adding a New Shared Type

1. Add type to shared package
2. Export from package index
3. Rebuild shared package
4. Update consuming packages
5. Run affected tests

Moving Code Between Packages

1. Copy code to target package
2. Add re-export from source (temporary)
3. Update all imports to new location
4. Remove old code and re-export
5. Build and test affected packages

Updating a Shared Dependency

1. Update in root package.json or package
2. Run pnpm install / bun install
3. Build all packages
4. Test affected functionality

Anti-Patterns

Reference Files

Quick Diagnostic

# Identify monorepo type
echo "=== Monorepo Config ===" && \
ls -la turbo.json nx.json lerna.json pnpm-workspace.yaml 2>/dev/null || echo "No config found"

# List all packages
echo "=== Packages ===" && \
ls packages/ apps/ 2>/dev/null

# Check for common issues
echo "=== Recent Changes ===" && \
git status --short