eduardweb.
TypeScriptAvansat#architecture#performance#typescript#monorepo

Configurarea corectă de tsconfig în monorepo: de la paths la Project References

De Ioana Marinescu, 17 oct. 2026 · 21 vizualizări · 3 like-uri

Postat 17 oct. 2026
json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "composite": true,
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "incremental": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "tsBuildInfoFile": "./dist/.tsbuildinfo"
  },
  "include": ["src/**/*"],
  "references": [
    { "path": "../shared-types" },
    { "path": "../logger" }
  ]
}

Monorepo-urile pe TypeScript încep mișto, până când adaugi al cincilea pachet intern și observi că tsc verifică aceleași fișiere de zece ori. Am făcut greșeala asta acum doi ani pe un proiect cu 14 pachete: am trântit un paths gigant în root și am zis că-i gata. Rezultatul? Un build în CI de 3 minute și 40 de secunde pentru nici 50k linii de cod.

După ce am restructurat totul pe Project References și build incremental, timpul a coborât la 48 de secunde la cold build și vreo 6 secunde incremental. Diferența e uriașă, dar setup-ul are câteva chichițe pe care documentația oficială le cam bagă sub preș.

De ce paths este doar o iluzie

Mulți încep prin a defini aliasuri în root tsconfig.json de forma "@app/ui": ["packages/ui/src"]. Merge impecabil în VS Code, autocompletion-ul e fericit, importurile arată curat. Problema apare când începi să compilezi.

TypeScript tratează fiecare import prin paths ca și cum fișierele din packages/ui ar face parte din proiectul curent. Dacă ai 4 aplicații (să zicem două de Next.js, un worker și un API de NestJS) care depind de pachetul de UI, compilatorul va re-parsa, re-analiza și re-genera tipurile pentru packages/ui de patru ori. În plus, dacă pachetul partajat are dependențe diferite de TS, te trezești cu erori subtile de runtime pentru că ai compilat codul cu reguli diferite de la un consumer la altul.

composite: true și contractul de tipuri

Soluția corectă este să separi fiecare pachet ca unitate autonomă. Aici intervine flag-ul composite: true.

Când activezi composite, TypeScript te obligă la trei lucruri: declaration: true (să genereze fișiere .d.ts), un fișier de manifest/intrare clar și emiterea de fișiere .tsbuildinfo. Practic, îi spui compilatorului: „Pachetul ăsta produce un contract strict de tipuri la output, consumă-l pe ăla, nu mai citi sursele mele brute din src/”.

Recomand neapărat și "declarationMap": true. Fără el, când dai Cmd+Click pe o funcție importată dintr-un pachet intern, IDE-ul te va arunca direct în fișierul .d.ts generat, nu în fișierul .ts sursă. E frustrant să editezi din greșeală într-un fișier din dist/ crezând că lucrezi în codul sursă.

Legarea prin references și comanda tsc -b

În aplicația sau pachetul care consumă librăria partajată, înlocuiești dependența fantomă din paths cu array-ul de references.

Șmecheria este că nu mai rulezi tsc simplu. Trebuie să folosești tsc --build (sau prescurtat tsc -b). Flag-ul -b înțelege arborele de dependențe din references, compilează pachetele în ordinea corectă topologică și sare peste pachetele neschimbate verificând hash-urile din .tsbuildinfo.

Trade-off-uri: unde apar bătăile de cap

Nu e totul lapte și miere. Principalul trade-off este disciplina strictă de build. Dacă folosești Turborepo sau Nx, ai două opțiuni: lași un singur task global tsc -b la nivel de repo, sau spargi task-urile per package și lași tool-ul de monorepo să facă caching la folderele dist.

Dacă amesteci ambele abordări fără grijă, riști invalidări bizare de cache. Am pățit des ca VS Code să rămână agățat pe definiții vechi dacă uiți să rulezi un watch pe packages (tsc -b -w), pentru că editorul se uită în dist/*.d.ts, nu în src/. Merge fantastic pentru proiecte medii și mari, dar dacă ai doar 2 pachete și 3 fișiere shared, complexitatea adăugată s-ar putea să te enerveze mai mult decât te ajută.

Voi cum gestionați type checking-ul în monorepo: mergeți pe tsc -b la nivel de repo sau orchestrați verificarea independent prin Turborepo/Nx?

Răspunsuri 0

Se încarcă răspunsurile…

Loghează-te pentru a răspunde

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