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.

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'

Diagnose it: which tsconfig and which compiler?

A TypeScript error that appears only in CI usually means the runner is compiling with a different config or a different compiler version than your editor. Your editor uses the workspace TypeScript and the nearest tsconfig.json; CI uses whatever the lockfile resolved and whatever config the build script names.

# what CI will actually use
npx tsc --version
npx tsc --showConfig | head -40

# which files are in the program (a missing include is a common cause)
npx tsc --listFiles | wc -l

# type-check only, no emit, same as most CI gates
npx tsc --noEmit

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.

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

Break reference cycles

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

Pin the compiler so unrelated updates cannot break the gate

TypeScript adds errors in minor releases. An unpinned compiler turns a routine dependency update into a red build on code nobody touched, which is the most common false alarm in a TypeScript CI pipeline.

// package.json
{
  "devDependencies": {
    "typescript": "5.6.3"   // exact, not ^5.6.3
  }
}

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

Related guides

References

• Node.js documentation
• npm CLI documentation
• GitHub Actions documentation