How to use project references in TypeScript

· Category: TypeScript

Short answer

Project references let you break a TypeScript application into multiple projects that can be built independently while preserving type safety across boundaries.

Steps

  1. Enable composite: true in each referenced project's tsconfig.json.
  2. Set declaration: true so referenced projects produce .d.ts files.
  3. In the root tsconfig.json, add a references array pointing to subproject paths.
  4. Build the entire solution with tsc --build or tsc -b.
  5. Import across projects using normal module resolution.

Tips

  • tsc --build caches outputs and only rebuilds changed projects, dramatically speeding up CI.
  • Keep project boundaries aligned with team ownership and deployment units.

Common issues

  • Circular project references are not supported and must be refactored.
  • Missing composite or declaration flags produce build errors.