TypeScript
Project references
Learn multi-project setups with project references.
What are project references?
The references array lists the projects a project depends on; each entry points to a target tsconfig.json via a path field. This is used to split projects in a monorepo. Referenced projects must have composite: true.
{
"references": [
{ "path": "../core" },
{ "path": "../utils" }
]
}
Build mode compiles references automatically first.
The composite requirement
If a project is referenced it must have composite: true; otherwise tsc --build errors out. Composite also forces declaration: true and outDir so the referencing project can find type declarations.
// core/tsconfig.json
{
"compilerOptions": {
"composite": true,
"declaration": true,
"outDir": "dist"
}
}
Referencing a non-composite project is a compile error.
Exercise Resolve build order
Write a resolveBuildOrder function that returns the topological order based on each project's references. For dependencies app → core, core → utils, produce the output utils, core, app.
Show example solution
function resolveBuildOrder(projects: { name: string; references: string[] }[]): string[] {
const order: string[] = [];
const visited = new Set<string>();
function visit(name: string) {
if (visited.has(name)) return;
visited.add(name);
const project = projects.find(p => p.name === name);
if (project) {
for (const ref of project.references) {
visit(ref);
}
}
order.push(name);
}
for (const p of projects) visit(p.name);
return order;
}
const projects = [
{ name: "app", references: ["core"] },
{ name: "core", references: ["utils"] },
{ name: "utils", references: [] }
];
console.log(resolveBuildOrder(projects).join(", "));
Test yourself
-
What does each entry in the references array contain?
- A type field
- A path field
- A name field
- A version field
Show answer
A path field — Each reference entry contains a path field pointing to the target tsconfig.json; name, version, and type are not part of the reference shape.
-
Add a reference path
{
"references": [
{ "____": "../core" }
]
}
Show answer
{
"references": [
{ "path": "../core" }
]
}
-
Project references parts
- references
- lists dependent projects
- path
- points to the target tsconfig
- composite: true
- enables referenceability
- declaration: true
- produces type declarations
Next lesson: Module resolution
