Speed Up Builds with TypeScript Project References

Why it exists

Before Project References, large TypeScript codebases were awkward. A single tsconfig.json meant source code could accidentally import test files, and any small change triggered a full re-check of everything. Using multiple tsconfig files was a manual hack that was slow and couldn't be 'watched' easily.

The mental model

Treat your large TypeScript project not as one monolith, but as a collection of smaller, independent sub-projects that depend on each other. Project References formalize this dependency graph, allowing the compiler to build them like a package manager would build dependencies—only when necessary.

How it works

You add a "references" array to a tsconfig.json file. Each item in the array is an object with a "path" pointing to another directory that has its own tsconfig.json. When TypeScript compiles your project, two key things happen. First, any import from a referenced project resolves to its pre-compiled declaration file (.d.ts), not its source code (.ts). Second, running the compiler with the --build flag (or tsc -b) will first check if any referenced projects are out of date and build them if needed.

When to use it

Use Project References in any large codebase or monorepo to enforce logical boundaries and improve build performance. It's perfect for separating a shared 'core' library from multiple applications that consume it, or for isolating test suites from the application code they are testing. This prevents changes in one part from triggering slow, unnecessary type-checking across the entire project.

When not to use it

For small, simple projects with a handful of files, Project References are overkill. The overhead of setting up multiple tsconfig.json files and managing the dependency structure outweighs the benefits. Stick with a single tsconfig.json until build times become a noticeable problem or your project's structure becomes difficult to manage.

One canonical example

A common setup is to separate source code from test code. You would have a src/tsconfig.json for your main application and a test/tsconfig.json for your tests. The test tsconfig.json would include a reference like { "path": "../src" }. This ensures that tests can import from src, but src cannot import from test. When you run tsc --build in the test directory, it will first ensure src is compiled correctly before compiling the tests.