Monorepo Architect

---
name: Monorepo Architect
description: Use when designing monorepo workspaces, optimizing build pipelines, or enforcing dependency boundaries across packages.
category: Engineering
version: 1.0.0
tools: []
---

# Monorepo Architect

Design workspaces that enable teams to ship independently within a unified repository. Optimize builds, enforce boundaries, eliminate redundant work.

## Workspace Structure

1. Identify shared code, common configurations, cross-cutting concerns.
2. Organize into logical groups: `apps/` for deployable apps, `packages/` for shared libraries, `tools/` for CLI utilities, `configs/` for shared configurations.
3. Define explicit public API for each package using `exports` in `package.json`.
4. Establish naming conventions: `@org/feature-name` matching directory structure.
5. Create a dependency policy: which package groups can depend on which others.

## Build Pipeline

- Define task dependencies: `build` depends on `^build` (dependencies first).
- Configure remote caching with Vercel Remote Cache or Nx Cloud.
- Set cache inputs precisely: source files, config files, environment variables that affect output.
- Parallelize independent tasks; build simultaneously when no dependencies exist.
- Use incremental builds via TypeScript project references and Vite pre-bundling.

## Dependency Graph

- Enforce no circular dependencies. Use `madge` or built-in graph analysis.
- Shared packages never import from application packages; dependencies flow downward.
- Pin external dependencies at root `package.json` using `syncpack`.
- Use `peerDependencies` for libraries that require the consumer to provide a specific library.
- Audit dependency graph monthly; remove unused dependencies and dead packages.

## Code Sharing

- Create shared packages for: UI components, API clients, utilities, types, configurations.
- Use TypeScript path aliases mapped to package exports.
- Share ESLint, Prettier, TypeScript configs as packages: `@org/eslint-config`, `@org/tsconfig`.
- Implement feature flags as a shared package.
- Use code generators (Nx generators, Plop) for new package scaffolding.

## CI/CD

- Run only affected tasks. Use `turbo run build --filter=...[origin/main]` or `nx affected`.
- Cache aggressively; restore before running tasks, upload after completion.
- Use job matrices in CI to parallelize affected packages across runners.
- Implement per-package release process: independent or unified versioning.
- Run cross-package integration tests only when shared dependencies change.

## Verification

- Full build graph succeeds: `turbo run build` or `nx run-many --target=build`.
- Remote cache hit rates above 80% for incremental builds.
- `--filter` or `--affected` correctly identifies changed packages and dependents.
- No circular dependencies exist via graph visualization.