You lead a monorepo where `tsc` declaration emit dominates build time. What does TypeScript's `isolatedDeclarations` option require of the code, what does it buy, and how would you decide whether to adopt it?

## Why declaration emit is the slow part Emitting `.js` is close to a per-file transform: strip types, downlevel syntax, write output. Emitting `.d.ts` is not. Consider: ```ts import { buildConfig } from './config'; export const settings = buildConfig(); ``` To write the declaration for `settings`, the compiler must know what `buildConfig` returns, which may require checking `./config` and everything it imports. Declaration emit is therefore a whole-program operation, and in a monorepo it serialises: package B cannot be checked until package A's declarations exist. ## What the option demands `"isolatedDeclarations": true` makes the compiler report an error anywhere an export cannot be declared from its own file. The fix is always the same shape — write the type down: ```ts import { buildConfig, type Config } from './config'; export const settings: Config = buildConfig(); // return type required, not inferred export function makeId(prefix: string): string { return `${prefix}-${Date.now()}`; } ``` Non-exported code is untouched; inference inside function bodies and on local variables works exactly as before. The requirement lands only on the public surface of each module. ## What that guarantee unlocks Once every exported declaration is spelled out, producing a `.d.ts` becomes syntax-directed: read one file, copy the annotations, drop the bodies. Any tool can do it, files can be processed in parallel, and no cross-file type information is needed. This is deliberately the same bargain `isolatedModules` strikes for JavaScript emit — accept a constraint on the source so a single-file transpiler can be correct. It requires `declaration` or `composite` to be enabled, since it constrains declaration output. It pairs naturally with `emitDeclarationOnly` in a setup where `tsc` is the type-check gate and something else produces the runtime JavaScript. Note clearly what it does **not** do: it does not speed up `tsc` itself. Type checking still needs the checker. The gain is architectural — it makes declaration emit a job you can move off the critical path. ## The adoption decision **Measure first.** The prize only exists if declaration emit is genuinely your bottleneck. In many repos the checking pass dominates instead, and this option changes nothing there. Time a clean build with and without `emitDeclarationOnly` before committing. **Count the annotation surface.** The migration cost scales with how many exports rely on inference. A package that already annotates its public API costs almost nothing; one that re-exports inferred values everywhere is a large mechanical change. That change is not pure overhead — explicit public signatures are also a stability win, because a refactor inside a function can no longer silently alter your published type — but it is real work and it touches many files. **Scope it.** This is a per-project setting, so adopt it package by package. Turning it on for a leaf library with a small surface proves the workflow before you commit the whole repo. **Weigh it against the alternatives.** Project references with `composite` and incremental builds already cut rebuild cost by avoiding redundant work; that is often the cheaper first move. `isolatedDeclarations` matters most where you want a non-`tsc` tool to own emit entirely. **Consider the ergonomics.** Some engineers experience mandatory return-type annotations as friction, particularly on small internal helpers that happen to be exported. Others consider it good practice regardless. Land that debate before flipping the flag, not after the first review cycle. ## A reasonable rollout 1. Measure declaration-emit time in isolation and confirm it is the bottleneck. 2. Enable the option in one leaf package; fix the errors it reports — they are mechanical and the compiler tells you exactly where. 3. Wire the alternative emitter for that package's declarations and re-measure end to end. 4. Extend outward only if the numbers justify the churn, and write down the standard so new code arrives compliant. The honest summary: a targeted build-performance tool with a real source-level cost, worth adopting when declaration emit is measurably on the critical path and not before.