TypeScript 5.5 --isolatedDeclarations

TypeScript 5.5 introduced --isolatedDeclarations, a game-changing option for monorepos. If you're dealing with nested dependencies and slow builds, this article is for you.

🚨 The Sequential Build Problem

In a monorepo with nested dependencies like A → B → C → D, TypeScript must type-check everything in order to generate .d.ts files.

monorepo/
├── packages/
│   ├── core/          (package A)
│   ├── utils/         (package B, depends on A)
│   ├── components/    (package C, depends on B)
│   └── app/           (package D, depends on C)
└── tsconfig.json

Result? Sequential builds that take:

• 30 seconds for an average library
• Several minutes for a complete monorepo
• Impossible to parallelize because each package waits for the previous .d.ts

✨ The Solution: --isolatedDeclarations

The principle is simple but powerful: each file can be processed independently, in parallel. No need to analyze the entire codebase to generate declarations.

📊 Real Benchmarks

🔧 Practical Migration

tsconfig.json Configuration

{
  "compilerOptions": {
    // Enable the option (TS 5.5+)
    "isolatedDeclarations": true,
    
    // Required to generate .d.ts
    "declaration": true,
    
    // Optional: for monorepos with project references
    "composite": true,
    
    // Recommended
    "strict": true
  }
}

Migration Steps

npm run build

🎯 Conclusion

Adopting --isolatedDeclarations isn't just a technical optimization, it's an investment in your team's productivity. Time savings on each build add up quickly: several hours saved per week for a team of 5 developers.