TypeScript Isolated Declarations: Boost Monorepo Speed
Monorepo builds often slow down because of how TypeScript handles declaration files. By default, TypeScript analyzes every import chain before it creates a single .d.ts file. This creates a long line where packages must wait for each other.
You can fix this with the --isolatedDeclarations flag.
This flag allows parallel builds. Instead of waiting for dependencies, each package generates its own declarations independently. Teams see build speeds increase by 3x to 15x.
The Problem: TypeScript usually infers types across module boundaries. If Package A depends on Package B, the compiler must fully resolve B before it can start on A. In a large monorepo, most packages sit idle while the compiler works one by one.
The Solution: The --isolatedDeclarations flag changes the rules. It requires you to write explicit type annotations for everything you export.
The Tradeoff: Your code will have more text. You must manually add return types to functions and types to constants. You cannot rely on the compiler to guess these types from your code.
The Result: Because every export has a clear type, the compiler does not need to look at other packages to understand them. It can process every package at the same time.
Real World Results:
- A monorepo with 18 packages dropped build times from 47 seconds to 3.2 seconds.
- A 32-package monorepo saw 8x gains on CI pipelines.
- Performance scales with your CPU cores. More cores mean more packages build at once.
How to Migrate:
- Enable the flag in your root tsconfig.json and every package config.
- Use the "composite" flag to allow project references.
- Add explicit return types to exported functions:
// Before export function add(a: number, b: number) { return a + b; }
// After export function add(a: number, b: number): number { return a + b; }
- Add explicit types to exported constants:
// Before export const SETTINGS = { port: 3000 };
// After export const SETTINGS: { port: number } = { port: 3000 };
If you do not add these types, the compiler will throw errors. This ensures your types are deterministic and fast.