Monorepo Patterns with References
What You'll Learn
You'll learn how to structure a TypeScript monorepo with multiple packages, shared libraries, and applications using project references to maintain clean boundaries and enable efficient incremental builds.
The Monorepo Structure Problem
A monorepo is a single repository containing multiple related projects—think shared utility libraries, core business logic packages, and several applications (web, mobile, admin) that consume them. Without proper organization, TypeScript struggles: build times explode, circular dependencies creep in, and type-checking becomes unbearably slow.
Project references solve this by letting you explicitly define the relationships between projects, enabling TypeScript to build only what changed and enforce architectural boundaries.
Common Monorepo Patterns
Pattern 1: Layered Libraries
Organize your monorepo into layers, where each layer depends only on layers below:
/packages
/utils (no dependencies)
/core (depends on utils)
/api-client (depends on core, utils)
/apps
/web-app (depends on api-client, core, utils)
/admin-app (depends on api-client, core)
Each folder has its own tsconfig.json with composite: true, and references pointing to dependencies:
// apps/web-app/tsconfig.json
{
"extends": "../../tsconfig.base.json",
"compilerOptions": {
"composite": true,
"outDir": "./dist",
"rootDir": "./src"
},
"references": [
{ "path": "../../packages/api-client" },
{ "path": "../../packages/core" },
{ "path": "../../packages/utils" }
],
"include": ["src"]
}
Pattern 2: Domain-Driven Packages
Group by business domain rather than technical layer:
/packages
/auth-domain
/billing-domain
/user-domain
/shared-types
/apps
/customer-portal
/internal-dashboard
Each domain can reference shared-types but domains don't reference each other directly, keeping boundaries clear.
Pattern 3: Application-Specific Libraries
Some libraries exist only to support specific apps:
/libs
/shared-ui (used by all apps)
/web-utils (web-app only)
/mobile-bridge (mobile-app only)
/apps
/web-app (refs: shared-ui, web-utils)
/mobile-app (refs: shared-ui, mobile-bridge)
This prevents bloating apps with unused code while sharing common foundations.
Benefits of This Approach
- Incremental builds: TypeScript only rebuilds changed projects and their dependents
- Enforced boundaries: Can't accidentally import from
admin-appintocustomer-portal - Clear dependency graph:
referencesexplicitly document what depends on what - Parallel builds: Independent projects can compile simultaneously
- Type safety across packages: No more loose
anytypes at package boundaries
Key Takeaway: Organizing a monorepo with project references creates explicit architectural boundaries—shared libraries provide reusable functionality, applications compose them together, and TypeScript ensures everything stays in sync with fast, incremental builds.