Project References

Project references link separate TypeScript projects with their own tsconfig.json files. Composite builds help large repositories enforce boundaries and build in dependency order using tsc --build. Unlike ordinary imports, references are build relationships; understand emitted declarations and project layout before adopting them.

The object illustrates a dependency graph that a real composite build might express through references. The extra configuration lab contains real shared/app files and tsconfig examples.

Just listing a project in references does not replace correct imports or compiler-compatible output paths.

Save as project-references.ts. The following program passed strict TypeScript compilation, and the displayed output was captured by executing its emitted JavaScript with Node.js 22.16.0.

TypeScript source

type Project = { name: string; dependencies: string[] };
const app: Project = { name: "app", dependencies: ["shared"] };
console.log(`${app.dependencies[0]} before ${app.name}`);

Verified output

shared before app

Compile: npx tsc --strict --target es2022 --module commonjs project-references.ts; run: node project-references.js. For Node.js API examples, install @types/node first. For browser projects, use the browser-specific instructions below.

The example demonstrates the code-level behavior; the related configuration or test commands are shown separately when needed.

The object illustrates a dependency graph that a real composite build might express through references. The extra configuration lab contains real shared/app files and tsconfig examples.

Predict what changes if you alter one input. Then run the code to compare your reasoning with the real output.

Practical project lab: These are real configuration and source-file examples, not a TypeScript object that merely describes settings. Place the files at the named paths relative to one project directory.

tsconfig.json

{"files":[],"references":[{"path":"./shared"},{"path":"./app"}]}

shared/tsconfig.json

{"compilerOptions":{"composite":true,"declaration":true,"target":"ES2022","module":"CommonJS","strict":true},"include":["*.ts"]}

shared/index.ts

export const greeting = (s: string): string => `Hi, ${s}`;

app/tsconfig.json

{"compilerOptions":{"composite":true,"target":"ES2022","module":"CommonJS","strict":true},"references":[{"path":"../shared"}],"include":["*.ts"]}

app/main.ts

import { greeting } from "../shared/index";
console.log(greeting("Asha"));

Commands

npx tsc --build

The composite build orders referenced projects and creates generated declaration outputs.

This local compiler or test-runner mini-project was validated in addition to the primary program.

Just listing a project in references does not replace correct imports or compiler-compatible output paths.

Identify whether the failure is a type-checking issue, a configuration issue, or a runtime behavior issue before choosing a fix.

Create a composite shared library and app project; run tsc --build and inspect which outputs build first.

Write down your expected result first. For configuration examples, compare compiler output and diagnostics; for test examples, make the assertion fail deliberately to verify that the tool reports it.

For the exact current options and platform behavior, consult the official documentation. These examples were verified using the tool versions described above.

Project references link separate TypeScript projects with their own tsconfig.

Run the primary example, then complete the practice task or environment-specific lab.