Project References Basics
What you'll learn: How to use the references array in your tsconfig.json to declare dependencies between TypeScript projects, enabling structured multi-project builds.
The Problem: Monoliths vs Multiple Projects
When your codebase grows, you often split it into separate projects—perhaps a shared utilities library, a server package, and a client application. Without project references, TypeScript treats each project independently, forcing you to compile them in the right order manually and losing valuable type information between projects.
The references Array Solution
Project references let you declare which projects depend on others using the references array in tsconfig.json:
{
"compilerOptions": {
"composite": true,
"outDir": "./dist"
},
"references": [
{ "path": "../shared-utils" },
{ "path": "../server-types" }
]
}
Each entry in the references array points to another TypeScript project (a directory containing a tsconfig.json with composite: true enabled). This tells TypeScript: "This project depends on those other projects."
How It Works
Think of project references like a dependency graph in a monorepo. When you reference another project:
- TypeScript knows to compile that project first
- It uses the compiled
.d.tsfiles from referenced projects for type-checking - Changes in referenced projects can trigger rebuilds intelligently
- The
--buildmode orchestrates everything automatically
Real-World Structure
/monorepo
/packages
/utils
tsconfig.json (composite: true)
/backend
tsconfig.json (references utils)
/frontend
tsconfig.json (references utils)
The backend and frontend both depend on utilities, so their references arrays point to ../utils. TypeScript ensures utilities builds first.
Key Takeaway: Project references enable TypeScript to understand and manage dependencies between separate projects in a monorepo or multi-project setup, providing ordered builds and proper type information sharing.