TypeScript: project references и monorepo — пример кода

Question

Accepted Answer

## Пример

Root solution file — references only, no files of its own:

```jsonc
// tsconfig.json (repo root) — the "solution" that builds everything
{
  "files": [],
  "references": [
    { "path": "packages/utils" },
    { "path": "packages/core" },
    { "path": "packages/ui" }
  ]
}
```

A shared base plus a leaf package:

```jsonc
// tsconfig.base.json — one source of truth for compiler options
{
  "compilerOptions": {
    "composite": true,          // ← required for any referenced project
    "declaration": true,        // implied by composite, but be explicit
    "declarationMap": true,     // lets editors jump to SOURCE, not .d.ts
    "incremental": true,
    "strict": true
  }
}
```

```jsonc
// packages/core/tsconfig.json
{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "outDir": "dist",
    "rootDir": "src",
    "paths": { "@app/utils": ["../utils/src"] } // module RESOLUTION (separate concern)
  },
  "include": ["src"],
  "references": [{ "path": "../utils" }]          // build GRAPH edge
}
```

```bash
tsc -b                    # build the whole graph, skipping unchanged nodes
tsc -b --watch            # incremental watch across all packages
tsc -b --clean            # delete outputs + .tsbuildinfo
tsc -b --verbose          # see exactly which projects were up-to-date vs rebuilt
```

## Итог

`composite: true` обязателен; `paths` ≠ references — resolution vs build graph.