Elite Monorepo Workspace Config Blueprint

Enterprise-grade monorepo configuration setting for managing multi-package workspaces with shared tooling and dependency hoisting.

When to Use This Setting

Apply this setting when you need to:

• Configure a monorepo workspace with shared build tooling, linting, and testing across multiple packages
• Manage dependency hoisting, version synchronization, and cross-package references in a unified repository
• Set up workspace-aware CI/CD pipelines that only build and test packages affected by each change Consider alternatives when:
• Your project is a single package that does not benefit from monorepo tooling overhead
• You prefer separate repositories with clear ownership boundaries over a shared monorepo

Quick Start

Configuration

Copy
name: elite-monorepo-workspace-config-blueprint
type: setting
category: development

Example Application

Copy
claude setting:apply elite-monorepo-workspace-config-blueprint

Example Output

Setting applied. Changes:
- workspaces: packages/*, apps/*, libs/*
- package_manager: pnpm with workspace protocol
- dependency_hoisting: shared to root node_modules
- build_orchestration: turborepo or nx pipeline
- change_detection: affected packages only

Core Concepts

Monorepo Workspace Overview

Aspect	Details
Workspace Layout	Packages organized in packages/, apps/, and libs/ directories with glob patterns
Dependency Hoisting	Shared dependencies hoisted to root node_modules; package-specific deps stay local
Version Synchronization	Shared tooling versions (TypeScript, ESLint, Jest) pinned at root for consistency
Build Orchestration	Task pipeline via Turborepo or Nx for parallel, cached, and incremental builds
Change Detection	Affected-package analysis determines which packages need rebuild after each change

Monorepo Architecture

+-------------------+     +---------------------+     +-------------------+
| Root Config       |---->| Workspace Manager   |---->| Package Resolver  |
| pnpm-workspace    |     | pnpm/npm/yarn       |     | dependency graph  |
| turbo.json        |     | install + hoist     |     | cross-references  |
+-------------------+     +---------------------+     +-------------------+
         |                          |                          |
         v                          v                          v
  +----------------+      +-------------------+      +-------------------+
  | Shared Config  |      | Build Pipeline    |      | Change Detector   |
  | tsconfig.base  |      | turbo run build   |      | git diff analysis |
  | eslint.config  |      | parallel + cached |      | affected packages |
  +----------------+      +-------------------+      +-------------------+

Configuration

Parameter	Type	Default	Description
workspace_globs	string[]	["packages/","apps/","libs/*"]	Glob patterns defining workspace package directories
package_manager	string	"pnpm"	Package manager with workspace support: pnpm, npm, or yarn
build_tool	string	"turborepo"	Build orchestration tool for task pipeline management
hoist_pattern	string[]	["*"]	Dependency patterns to hoist to root node_modules
cache_dir	string	".turbo"	Directory for build cache storage

Best Practices

1. Use pnpm for strict dependency isolation - pnpm's strict node_modules structure prevents packages from accidentally importing undeclared dependencies. This catches missing dependency declarations that would break in production or when packages are published independently.
2. Share tsconfig through extends - Create a tsconfig.base.json at the root with shared compiler options and have each package extend it. This ensures consistent TypeScript settings while allowing per-package overrides.
3. Configure remote caching for CI - Enable Turborepo or Nx remote caching so CI pipelines can reuse build artifacts from previous runs. This dramatically reduces CI time for large monorepos where most packages are unchanged between commits.
4. Define clear package boundaries - Document which packages can depend on which others. Use tooling like dependency-cruiser or Nx project boundaries to enforce these rules and prevent circular dependencies.
5. Use changesets for versioning - Adopt the changesets tool for managing package versions and changelogs. Each PR that modifies a package includes a changeset file that describes the change and its semver impact.

Common Issues

1. Dependency resolution conflicts - Different packages requiring incompatible versions of the same dependency cause installation failures. Use pnpm overrides or npm resolutions to force a compatible version across the workspace.
2. Build order errors - Packages that depend on each other must build in dependency order. Ensure your build tool's pipeline configuration correctly declares package dependencies so builds execute in topological order.
3. IDE performance degradation - Large monorepos can slow down IDE features like TypeScript language service. Configure the IDE to use project references and exclude node_modules from file watching to maintain responsive editing.