What is `isolatedDeclarations` and how does it enable single-file transpilation for declaration emit?

Q: What is `isolatedDeclarations` and how does it enable single-file transpilation for declaration emit?

**Target Audience:** Developers who build or publish TypeScript libraries or large monorepos and want to understand why `.d.ts` generation is slow and what `isolatedDeclarations` changes. **Difficulty:** Hard **TypeScript version:** `isolatedDeclarations` arrived in TypeScript 5.5. The page compiler is TypeScript 5.4.5, which rejects the flag (`error TS5023: Unknown compiler option '--isolatedDeclarations'.`, checked here), so the page examples only show the underlying idea. Every `isolatedDeclarations` error and every `.d.ts` below was produced by TypeScript 5.9.3, by oxc's isolated-declaration transform as bundled in rolldown 1.0.3, and where noted by TypeScript 7.0.2. > **How to read this doc:** Each idea is explained in plain language first, then tagged with `📌 Interview term:` so you also learn the exact words an interviewer expects. All output was produced by actually running the code; the **Verified** section quotes it in full. How to write a whole library so that it passes t

The problem

Question presented to candidate: "Transpiling TypeScript to JavaScript can be done one file at a time by fast tools, but generating .d.ts files has always needed tsc. Why is that, and what does the isolatedDeclarations option change?"

What a strong answer should cover:

Why declaration emit needs a type checker: an unannotated export (a function return type, a variable set from a call) gets its type from inference, which can depend on other files and on the whole program
What isolatedDeclarations does (TypeScript 5.5+): it reports an error wherever an export's type cannot be written down from that file's syntax alone, so any tool can produce the .d.ts file by copying annotations, with no checker
What still needs no annotation ("trivially inferable"): literals, object literals of literals, as const arrays, type assertions; what does (calls, new, spreads, plain arrays, unannotated returns, parameters with non-literal defaults) and the TS90xx error family
What it does not do: it changes no emit by itself, needs declaration or composite, and tsc writes no .d.ts while those errors exist
The payoff: per-file, parallel declaration emit (ts.transpileDeclaration, oxc, bundler plugins) and starting downstream type checks before upstream projects finish

Code / implementation expected: Optional — an exported function that fails under the flag, the error, and the annotated version.

isolatedDeclarations
declarations

Try it yourself

Sketch your approach before you read the solution. That is what the interview tests.

Stuck? Get a hint.

A short nudge toward the approach. It will not give the answer away.

Solution

Target Audience: Developers who build or publish TypeScript libraries or large monorepos and want to understand why .d.ts generation is slow and what isolatedDeclarations changes. Difficulty: Hard TypeScript version: isolatedDeclarations arrived in TypeScript 5.5. The page compiler is TypeScript 5.4.5, which rejects the flag (error TS5023: Unknown compiler option '--isolatedDeclarations'., checked here), so the page examples only show the underlying idea. Every isolatedDeclarations error and every .d.ts below was produced by TypeScript 5.9.3, by oxc's isolated-declaration transform as bundled in rolldown 1.0.3, and where noted by TypeScript 7.0.2.

How to read this doc: Each idea is explained in plain language first, then tagged with 📌 Interview term: so you also learn the exact words an interviewer expects. All output was produced by actually running the

The solution is hidden so you can try first

13 min read · 11 sections

Run the code

Edit the code and run it here. Each console line with an expected value becomes a test.

TypeScriptWhy declaration emit normally needs other files

Practice

TypeScriptA toy model of the trivially inferable rule

Practice

Discussion

Other approaches, follow-ups and how it went in real interviews.

Sign in to join the discussion.

No comments yet. Share how you would answer it.

The solution is hidden so you can try first

Keep your momentum going.