Circular References Between Projects
You'll learn: why TypeScript forbids project references that form a cycle, and how to restructure your codebase to break circular dependencies between composite projects.
The Core Problem
When working with composite projects (via composite: true and project references), TypeScript enforces a critical rule: projects cannot reference each other in a circle. If Project A references Project B, and Project B references Project A, you've created a circular dependency — and TypeScript will reject it with a compile-time error.
Think of it like organizing books on shelves where each shelf's books can only reference books on shelves below it. You can't have books on Shelf 1 pointing to Shelf 2, while Shelf 2 points back to Shelf 1 — it creates an impossible ordering for which shelf to read first.
Why Circles Are Forbidden
TypeScript's build mode (--build) processes projects in dependency order: it builds dependencies before the projects that depend on them. With circular references, there's no valid build order — it's like asking "which came first, the chicken or the egg?"
Circular references also create tight coupling between projects, defeating the purpose of splitting them in the first place. If two projects always need each other, they might as well be one project.
How to Fix Circular Dependencies
The solution is always refactoring to break the cycle. Common strategies include:
- Extract shared code: Move code both projects need into a third, lower-level project that both can reference
- Invert the dependency: Make one project clearly foundational, and move shared interfaces/types there
- Split concerns: One project handles data models, another handles business logic — eliminate back-references
- Merge projects: If they're truly inseparable, combine them into a single project
Key Takeaway: TypeScript project references must form a directed acyclic graph (DAG) — no cycles allowed. Fix circular dependencies by extracting shared code into a common base project or reconsidering your project boundaries.