Course contentsShow
← TypeScript
Lesson 1227 of 1,79628. tsconfig in DepthFree lesson

Cross-Project Imports

How TypeScript resolves imports between referenced projects using declaration files rather than source files.

Cross-Project Imports in TypeScript

What you'll learn: How TypeScript resolves imports between referenced projects using declaration files rather than source files.

The Declaration File Boundary

When you set up project references in a composite project setup, something subtle but important happens at the boundaries between projects. Instead of directly importing the .ts source files from another project, TypeScript actually imports the generated declaration files (.d.ts) from that project's outDir.

This is a fundamental shift from how imports work within a single project, where TypeScript looks directly at your .ts source code.

Why Use Declarations Instead of Source?

Think of project references like building with LEGO sets. Each set (project) gets fully assembled once, then you connect the completed sets together using their standardized connection points (declaration files). You don't disassemble one set to see how it was built when connecting it to another — you just use its exposed interface.

This approach provides:

  • Faster builds: TypeScript doesn't need to re-parse and re-check all source files from referenced projects
  • Clearer boundaries: Only the public API (what's exported) is visible, enforced by declarations
  • Incremental compilation: Changes in one project's internals don't trigger rebuilds in dependent projects unless the API changes

How It Works

When Project B references Project A:

  1. Project A must have composite: true and generates .d.ts files in its outDir
  2. Project B's tsconfig.json references Project A via the references array
  3. When you import from Project A in Project B, TypeScript resolves to Project A's declaration files, not its source files
  4. The .tsbuildinfo file tracks whether Project A's outputs are up-to-date

This means you must build referenced projects (or use tsc --build) before importing projects can see their latest types.

Key Takeaway: TypeScript treats cross-project imports differently from in-project imports — it reads compiled declaration files from the referenced project's output directory, not the raw source files, enabling faster incremental builds and stronger API boundaries.