eduardweb.
TypeScriptAvansat#typescript#dx#monorepo#build-tools

Cum am scăpat de build-uri de 4 minute în monorepo configurând corect tsconfig-ul

De Cristian Barbu, 17 oct. 2026 · 26 vizualizări · 3 like-uri

Postat 17 oct. 2026
json
{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "outDir": "./dist",
    "rootDir": "./src",
    "composite": true,
    "declaration": true,
    "declarationMap": true
  },
  "include": ["src/**/*"],
  "references": [
    { "path": "../core" },
    { "path": "../tokens" }
  ]
}

Dacă ai un monorepo cu mai mult de trei pachete și tsc rulează lent pe CI, știu prin ce treci. La un proiect cu vreo 14 pachete interne și peste 120k linii de cod, typecheck-ul dura aproape 4 minute la fiecare push. Problema n-a fost volumul de cod, ci faptul că ne-am bazat exclusiv pe alias-uri de paths în loc să facem setup-ul cu Project References.

Capcana clasică: doar paths fără referințe reale

Mulți dezvoltatori trântesc în root paths: { "@acme/ui/*": ["packages/ui/src/*"] } și consideră problema rezolvată. Funcționează local în VS Code, dar e o iluzie periculoasă.

Când rulezi comanda de build, TypeScript tratează tot proiectul ca pe un monolit uriaș. Nu există cache granular per pachet. Dacă modifici o virgulă într-un fișier de tipuri din utils, compilatorul va lua la rând și va reanaliza UI-ul, API-ul și worker-ul de background. Practic, ignori complet separarea pe care ai încercat s-o faci prin foldere.

În plus, ajungi rapid la importuri circulare ascunse pe care bundlerul le ignoră până când crapă urât la runtime în producție.

Salvarea: composite: true și Project References

Soluția curată presupune să tratezi fiecare pachet ca pe o entitate izolată, compilabilă separat. Asta implică trei pași obligatorii:

  1. Activezi composite: true în tsconfig-ul fiecărui sub-pachet. Acest flag forțează TypeScript să genereze fișiere .d.ts și metadata în fișiere .tsbuildinfo.
  2. Pui declaration: true și neapărat declarationMap: true. Hărțile de declarații sunt salvarea ta când dai "Go to Definition" în editor: te duc direct în fișierul .ts sursă, nu în fișierul compilat .d.ts.
  3. Legi pachetele între ele folosind nodul references: [{ "path": "../shared" }].

Când rulezi tsc --build (sau pe scurt tsc -b), TypeScript citește graful de dependențe și compilează pachetele în ordinea corectă topologică. În cazul nostru, timpul de build a scăzut de la 3m50s la 38 de secunde pe o rulare curată și sub 5 secunde la incremental build dacă modifici un modul izolat.

Trade-off-ul sincer: dubla mentenanță

Sună excelent pe hârtie, dar există o problemă practică enervantă. Apare o dublă mentenanță la nivel de dependențe. Când adaugi @acme/core ca dependență în @acme/auth, trebuie să-l adaugi în package.json, dar ești obligat să-l treci și în tsconfig.json la secțiunea references.

Dacă uiți să adaugi referința în tsconfig.json, pnpm build ar putea rula fără erori din bundler, dar typecheck-ul va pica pe CI sau vei avea întârzieri bizare de sincronizare în IDE. Noi am rezolvat problema scriind un script mic de 40 de linii în pre-commit care verifică dacă referințele din tsconfig se pupă cu cele din dependencies.

Un alt compromis: composite: true este mult mai strict. Te obligă să pui tipuri explicite pe funcțiile exportate acolo unde TypeScript nu poate deduce ușor tipul fără să citească module private.

Voi cum ați abordat problema asta? Păstrați sincronizarea manual sau folosiți un tool dedicat gen manypkg?

Răspunsuri 0

Se încarcă răspunsurile…

Loghează-te pentru a răspunde

Doar membrii comunității pot lăsa comentarii.