Optimizarea Fișierului tsconfig.json și Arhitecturi Monorepo cu Project References în TypeScript

Fișierul tsconfig.json este inima oricărui proiect TypeScript. O configurare deficitară poate duce la timpi de build de câteva minute în pipeline-ul CI/CD, erori subtile de rezolvare a modulelor la rulare (CommonJS vs ECMAScript Modules) sau scăparea unor erori de tip Cannot read properties of undefined în producție. Acest ghid detaliază standardul recomandat de configurare și arhitectura monorepo bazată pe Project References.

{
  "compilerOptions": {
    /* 1. Mediu și Limbaj */
    "target": "ES2022",
    "lib": ["ES2022", "DOM", "DOM.Iterable"],
    
    /* 2. Module și Interoperabilitate Modernă */
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "verbatimModuleSyntax": true,
    
    /* 3. Verificare Strictă Maximă (Zero Compromisuri) */
    "strict": true,
    "noUncheckedIndexedAccess": true,  // Adaugă automat '| undefined' la arr[i] și dict[cheie]!
    "noImplicitOverride": true,        // Forțează cuvântul cheie 'override' în subclase
    "exactOptionalPropertyTypes": true,// Distinge între { opt?: string } și { opt?: string | undefined }
    "noFallthroughCasesInSwitch": true,
    
    /* 4. Viteză de Compilare */
    "incremental": true,               // Salvează cache-ul de build în fișierul .tsbuildinfo
    "skipLibCheck": true               // Nu verifică tipurile interne din fișierele .d.ts din node_modules
  }
}

Magia noUncheckedIndexedAccess

Opțiunea noUncheckedIndexedAccess este probabil cel mai util flag opțional din TypeScript. În modul implicit strict: true, TypeScript consideră că dacă aveți un array const lista: string[] = [], accesul lista[0] este de tip string. În realitate, lista[0] este undefined! Activând acest flag, TypeScript forțează verificarea existenței înainte de apelarea metodelor:

const orase: string[] = ['București'];
const oras = orase[5]; // Cu noUncheckedIndexedAccess: oras are tipul 'string | undefined'!
// oras.toLowerCase(); // EROARE DE COMPILARE: 'oras' is possibly 'undefined'.
if (oras) {
    console.log(oras.toLowerCase()); // Sigur 100%!
}

Arhitecturi Monorepo cu Project References

Într-un monorepo mare (format din zeci de pachete: core, ui, backend, mobile), rularea unui singur proces tsc care compilează tot proiectul dintr-o dată devine prohibitiv de lentă. Project References permite împărțirea codului în proiecte modulare independente:

// 1. În pachetul 'packages/core/tsconfig.json':
{
  "compilerOptions": {
    "composite": true,         // Permite altor proiecte să îl referențieze
    "declaration": true,       // Emite fișiere .d.ts pentru interfața publică
    "declarationMap": true,    // Permite editorului să navigheze la codul sursă .ts
    "outDir": "./dist"
  }
}

// 2. În aplicația principală 'apps/web/tsconfig.json':
{
  "compilerOptions": {
    "outDir": "./dist"
  },
  "references": [
    { "path": "../../packages/core" } // Referință directă către pachetul core!
  ]
}

// 3. Compilare ultra-rapidă cu modul Build:
// tsc --build --verbose

Comanda tsc --build (sau tsc -b) analizează graful de dependențe, compilează pachetele în ordine topologică și recompilează exclusiv pachetele ale căror fișiere au fost modificate efectiv, reducând timpii de CI/CD de până la 10 ori!

Diagnosticarea Compilărilor Lente

Dacă compilatorul devine lent, rulați comanda cu flag-uri de diagnostic pentru a identifica fișierele și tipurile problematice:

tsc --extendedDiagnostics --generateTrace ./urmarire-performanta

Folderul generat poate fi încărcat direct în chrome://tracing sau ui.perfetto.dev pentru a vedea grafic fiecare milisecundă petrecută de analizorul de tipuri.