// packages/web-app/tsconfig.json
{
"extends": "../../tsconfig.base.json",
"compilerOptions": {
"outDir": "./dist",
"rootDir": "./src"
},
"include": ["src"],
"references": [
{ "path": "../ui-kit" },
{ "path": "../shared-utils" }
]
}Dacă ai lucrat vreodată într-un monorepo unde tsc --noEmit dura două minute, știu prin ce treci. De cele mai multe ori, vinovatul nu este numărul de linii de cod, ci modul leneș în care configurăm tsconfig.json. Rezolvăm importurile cu un wildcard rapid în paths și ne mirăm de ce VS Code consumă 6 GB de RAM.
Capcana clasică: path aliases fără referințe
Toată lumea începe la fel: definești un tsconfig.base.json în rădăcină, bagi "@acme/*": ["packages/*/src"] și gata, importurile funcționează. Pare curat. Doar că TypeScript tratează acum tot monorepo-ul ca pe un singur proiect gigantic monolit.
Am pățit asta la un proiect cu 14 pachete interne — 2 aplicații Next.js, un API de NestJS și vreo 11 librării interne de UI și utilitare. De fiecare dată când cineva rula build-ul în CI, tsc recompila din sursă absolut tot graful, chiar dacă modificasem o singură interfață într-un package obscur. Timpul de typecheck în pipeline: 52 de secunde. La fiecare push.
Când folosești doar paths, TypeScript nu știe granițele dintre module. Reanalizează AST-ul pentru fiecare fișier importat direct ca sursă TS, ignorând complet caching-ul.
Salvarea: composite și Project References
Soluția oficială, dar ocolită de mulți pentru că cere rigoare, este combinația dintre composite: true și references. Când marchezi un pachet cu composite, forțezi câteva reguli sănătoase: pachetul trebuie să emită fișiere de declarații (.d.ts), să aibă rootDir explicit și generează automat un fișier .tsbuildinfo.
În loc ca aplicația ta principală să parseze miile de fișiere .ts din librăria de componente, ea va citi doar tipurile gata emise (.d.ts). Graful de dependențe devine topologic și organizat.
Comanda magică aici nu mai este simplul tsc. Treci obligatoriu pe tsc --build (sau prescurtat tsc -b). Flag-ul -b știe să citească secțiunea references, determină ordinea corectă de compilare și sare peste pachetele ale căror hash-uri din .tsbuildinfo nu s-au schimbat.
Pe proiectul de care ziceam, trecerea la Project References a redus pasul de typecheck de la 52 de secunde la 9 secunde la rece, iar la modificări incrementale în CI cache-ul coboară frecvent sub 2 secunde.
Trade-off-uri reale
Nu este totul roz, altfel ar folosi toți asta din prima zi:
- DX-ul la modificări locale: Dacă schimbi o funcție în
packages/utils, aplicația ta care o consumă nu o va vedea updatată până când nu rulezi build-ul pentruutils(sau nu ții untsc -b -wpornit în fundal). E frustrant dacă ești obișnuit cu bundlere moderne care fac transpiling direct din sursă. - Setup inițial migălos: Fiecare pachet are nevoie de propriul
tsconfig.jsoncu lista explicită a dependențelor interne înreferences. Dacă uiți o legătură, primești erori de compilare.
Merită efortul? Dacă ai 2 pachete mici, clar nu. Rămâi pe tsconfig simplu. Dar dacă ai depășit 5-6 pachete sau echipa are peste 4 developeri, lipsa Project References o să vă mănânce nervii pe măsură ce codebase-ul crește.
Voi cum gestionați tipurile între pachete: le compilați separat cu .d.ts sau vă bazați exclusiv pe bundler să înghită sursele direct?