TypeScript "tsc --build" Project Reference Errors (TS6305/TS6202)

By Kaveh Alemi·Latchkey

In build mode (tsc --build/-b), TypeScript compiles a graph of referenced projects in dependency order. It errors when a referenced project is not composite, its declaration outputs are stale or missing (TS6305), or the references form a cycle (TS6202).

What this error means

tsc -b fails with TS6305: Output file '<x>.d.ts' has not been built from source file, TS6202: Project references may not form a circular graph, or a note that a referenced project must set composite: true. It is deterministic and names the project.

tsc output

error TS6305: Output file '/app/packages/core/dist/index.d.ts' has not been
built from source file '/app/packages/core/src/index.ts'.
  The file is in the program because:
    Referenced via '../core' from file '/app/packages/api/tsconfig.json'

Common causes

Referenced project missing composite or built outputs

A project referenced via references must set composite: true and emit declarations. If its dist was not built (or the cache is stale), the dependent project cannot find the .d.ts (TS6305).

Circular project references

Two projects reference each other (directly or transitively), which tsc -b rejects with TS6202 because it cannot order the build.

How to fix it

Make referenced projects composite and build the graph

Enable composite on referenced projects and let build mode compile them in order.

tsconfig.json

// packages/core/tsconfig.json
{ "compilerOptions": { "composite": true, "declaration": true, "outDir": "dist" } }
// then build the whole graph:
// tsc -b

Break reference cycles

Map the references graph and find the cycle the TS6202 error reports.
Extract the shared types into a third project both can reference one-directionally.
Force a clean rebuild with tsc -b --clean && tsc -b if outputs are stale.

How to prevent it

Set composite: true on every project referenced by another.
Build with tsc -b so the project graph is compiled in order.
Keep project references acyclic; share types via a leaf project.

Frequently asked questions

What causes ""TS6305 / TS6202""?

A project referenced via references must set composite: true and emit declarations. If its dist was not built (or the cache is stale), the dependent project cannot find the .d.ts (TS6305).

How do I fix "TS6305 / TS6202"?

Enable composite on referenced projects and let build mode compile them in order.