为何TypeScript中declaration与isolatedModules不能同时使用？

Great question! Let's break down the conflict between these two TypeScript compiler options and why TypeScript explicitly blocks them from being used together.

First, let's recap what each option does: #

• declaration: This option tells TypeScript to generate .d.ts type declaration files for your code. These files describe the shape of your types, functions, and modules so other TypeScript (or even JavaScript) projects can understand your code's types. To generate accurate declarations, the compiler needs a full, global view of your codebase's type dependencies—like how types cross-reference between files, or the concrete values of shared constructs.
• isolatedModules: This option forces TypeScript to treat every file as a completely independent module. It disables cross-file type analysis, skips processing of constructs that require global knowledge (like const enum references across files), and enforces strict module rules (e.g., every file must have an import/export to be treated as a module).

The core conflict #

Generating valid .d.ts files relies on the compiler being able to analyze your entire codebase holistically. For example:

• If you export a type from one file and reference it in another, the declaration file needs to know the full definition of that type to represent it correctly.
• For const enums, their values are inlined at compile time—generating a declaration requires knowing those values, which isolatedModules doesn't track because it doesn't analyze cross-file dependencies.

When isolatedModules is enabled, the compiler intentionally limits its scope to individual files. This means it can't gather the necessary global context to generate complete, accurate .d.ts files. Instead of letting you generate broken or incomplete declarations, TypeScript throws the explicit error:

error TS5053: Option 'declaration' cannot be specified with option 'isolatedModules'

Workaround if you need both #

If you want type declarations and need the safety of isolatedModules (e.g., for tools like Babel that process files individually), you have a couple options:

• Use a two-step build: First compile with isolatedModules disabled to generate .d.ts files, then recompile with isolatedModules enabled for your runtime code.
• Switch to using enum instead of const enum (since regular enums are emitted as runtime objects and don't require cross-file inlining), and ensure all your code follows strict module rules—this might let you use tools that enforce isolated module behavior while still generating declarations.

内容的提问来源于stack exchange，提问作者Leon