Skip to content
Tutorials Center
My learning

Topics

TypeScript Reference ยท tsconfig: Projects, Files and Watch Options

TypeScript references option

Reference for the TypeScript references tsconfig field: how projects depend on each other, build order, the circular flag, and common errors.

references is a top-level tsconfig field (it sits beside compilerOptions, not inside it). It lists other projects that this one depends on. When you build with tsc --build, the compiler builds the referenced projects first, and imports of their files resolve to their generated declaration files.

This lets a big codebase be split into pieces that are checked and cached separately, with an enforced direction of dependencies.

JSON
{
  "compilerOptions": { "outDir": "dist" },
  "references": [
    { "path": "../core" },
    { "path": "../shared/tsconfig.base.json" }
  ]
}

Try it

These examples model a project graph in plain TypeScript to show what the build tool works out for you.

TypeScript Build order from references

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

TypeScript Detecting a circular reference

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

Syntax

JSON
{ "references": [ { "path": "../core", "circular": false } ] }
Property Description
path A folder containing a tsconfig.json, or a path to a specific config file. Required.
prepend Concatenates the referenced project's outFile output; deprecated together with outFile bundling.
circular Allows a cycle between projects when true; rarely a good idea.

Edge cases and errors:

  • The referenced project must set composite: otherwise TS6306 is reported.
  • References are not inherited through extends; each config lists its own.
  • A cycle without circular is an error, and the build stops.

Usage notes

  • Build with -b. tsc --build (or tsc -b) follows references; tsc -p does not build them first.
  • Output must exist. If a referenced project has never been built, imports of its modules fail until you build it.
  • Solution tsconfig. A root config with "files": [] and a references array lets tsc -b build everything from one command, while editors still find each sub-project.
  • Imports go through declaration files. That is what keeps each project independent, and why declaration is forced on.
  • Dependency direction is enforced. A project cannot import from a project it does not reference, which prevents accidental coupling.
  • --clean and --force remove outputs or rebuild everything.