TypeScript 5.5 --isolatedDeclarations

TypeScript 5.5 a introduit --isolatedDeclarations, une option qui change radicalement la donne pour les monorepos. Si vous travaillez avec des dépendances imbriquées et que vos builds traînent, cet article va vous intéresser.

🚨 Le Problème des Builds Séquentiels

Dans un monorepo avec des dépendances imbriquées comme A → B → C → D, TypeScript doit tout type-checker dans l'ordre pour générer les fichiers .d.ts.

monorepo/
├── packages/
│   ├── core/          (package A)
│   ├── utils/         (package B, dépend de A)
│   ├── components/    (package C, dépend de B)
│   └── app/           (package D, dépend de C)
└── tsconfig.json

Résultat ? Des builds séquentiels qui durent :

• 30 secondes pour une lib moyenne
• Plusieurs minutes pour un monorepo complet
• Impossible de paralléliser car chaque package attend les .d.ts du précédent

✨ La Solution: --isolatedDeclarations

Le principe est simple mais puissant : chaque fichier peut être traité indépendamment, en parallèle. Plus besoin d'analyser tout le codebase pour générer les déclarations.

La génération de déclarations devient une simple opération syntaxique qui prend des millisecondes au lieu de minutes. Plus d'attente, plus de dépendances séquentielles.

📊 Benchmarks et Résultats Réels

Cas d'usage typiques

⚖️ Le Trade-off : Annotations Explicites

Pour que TypeScript puisse générer les déclarations de manière isolée, tu dois annoter explicitement tes exports publics. Pas le code interne, juste ce qui sort de ton module.

// ❌ Erreur avec --isolatedDeclarations
export function calculatePrice(items) {
  return items.reduce((sum, item) => 
    sum + item.price, 0
  );
}

// TypeScript doit inférer le type de retour
// → impossible en mode isolé

// ✅ OK avec --isolatedDeclarations
export function calculatePrice(
  items: Array<{ price: number }>
): number {
  return items.reduce((sum, item) => 
    sum + item.price, 0
  );
}

Code interne : inférence normale

// ✅ Code interne : pas besoin d'annotations
function internalHelper(x) {  // OK
  const result = x * 2;       // OK
  return result;              // OK
}

// ❌ Export public : annotation requise
export function publicAPI(x): number {  // ← annotation obligatoire
  return internalHelper(x);
}

🔧 Migration Pratique

Configuration tsconfig.json

{
  "compilerOptions": {
    // Active l'option (TS 5.5+)
    "isolatedDeclarations": true,
    
    // Requis pour générer les .d.ts
    "declaration": true,
    
    // Optionnel : pour monorepos avec project references
    "composite": true,
    
    // Recommandé
    "strict": true
  }
}

Migration d'un projet existant

npm run build

time npm run build

💡 Recommandations VOID

# .github/workflows/build.yml
- name: Build monorepo
  run: |
    # Avec --isolatedDeclarations, on peut paralléliser
    npm run build --workspaces --if-present --parallel
    
    # Ou avec Turborepo
    turbo run build --parallel

❓ FAQ Technique

🎯 Conclusion

L'adoption de --isolatedDeclarations n'est pas qu'une optimisation technique, c'est un investissement dans la productivité de votre équipe. Les gains de temps sur chaque build se cumulent rapidement : plusieurs heures économisées par semainepour une équipe de 5 développeurs.