Project References
In this page:
Basic Project Reference
The references property points from one TypeScript project's config to another project's config, letting a large codebase be split into smaller, independently-buildable pieces that still type-check against each other.
Example: Basic Project Reference
// app/tsconfig.json
// { "references": [{ "path": "../shared" }] }
console.log("references points from one project's config to another's");Referenced Project Configuration
A referenced project needs a compatible configuration, most importantly composite: true, so the TypeScript compiler can generate the declaration output that other projects referencing it will depend on.
Example: Referenced Project Configuration
// shared/tsconfig.json
// { "compilerOptions": { "composite": true, "declaration": true } }
console.log("composite: true lets other projects depend on this one's output");Application and Library Projects
A common structure separates reusable library code into its own referenced project from the application that consumes it, so the library can be built, tested, and versioned somewhat independently.
Example: Application and Library Projects
// packages/lib/tsconfig.json (composite: true)
// packages/app/tsconfig.json references: [{ path: "../lib" }]
console.log("Library and app split into separately buildable projects");Building Referenced Projects
TypeScript's build mode (tsc -b) understands project references and builds referenced projects in the correct dependency order automatically, skipping projects that haven't changed since the last build.
Example: Building Referenced Projects
// tsc -b
console.log("tsc -b builds referenced projects in correct dependency order");Benefits of Project References
Project references pay off on large codebases by separating concerns, reducing unnecessary recompilation, and making the dependency graph between packages explicit instead of implicit through shared node_modules.
Example: Benefits of Project References
// Faster incremental builds, clear dependency graph, separated concerns.
console.log("Project references scale TypeScript to large, multi-package codebases");Chapter Quiz — Complete all 7 topics to unlock
0/7 topics done
Complete these topics first: