Babel-based builds
A project uses Babel or another single-file transpiler for JavaScript output while TypeScript performs type checking.
TypeScript · Const
isolatedModules
isolatedModules makes TypeScript report code that cannot be safely transpiled one file at a time. It is designed for pipelines using single-file transformers such as Babel or transpileModule.
How it works
Enable this compiler option when TypeScript files may be transpiled independently by tools such as Babel or by transpileModule. TypeScript then reports constructs whose correct JavaScript output requires whole-program type information, while leaving normal type-checking and emitting behavior unchanged.
Syntax
{"compilerOptions":{"isolatedModules":true}}Parameters
| Name | Type | Description |
|---|---|---|
isolatedModules | boolean | Whether to report source constructs that cannot be safely transpiled one file at a time. |
Returns
Compiler diagnostics for code that requires cross-file type information during transpilation; it does not alter emitted output behavior.
Key points
- The option targets build pipelines where a transpiler handles files independently rather than analyzing the entire TypeScript program.
- It flags source patterns whose JavaScript transformation needs type-system knowledge unavailable during isolated file processing.
- The flag changes diagnostics by warning about unsafe patterns instead of changing the generated code itself.
- Enabling the option does not alter runtime semantics or TypeScript’s ordinary checking and emit process.
- The same single-file limitations affect TypeScript’s transpileModule API, so the option is relevant to tools built around that API.
- A type-only export cannot be emitted as a runtime export, which is why isolated file processing must distinguish types from values.
Common mistakes
- With isolatedModules enabled, an imported name used only as a type must be marked with type-only syntax; otherwise a single-file transpiler cannot determine whether the import has a runtime value.
- A namespace declaration in a script without an import or export is rejected; adding module syntax or moving the declaration avoids this restriction.
- References to members of ambient const enums are disallowed because independent transpilers cannot replace them safely without information from other files.
Example: Marking a type import explicitly
// types.ts
export interface User {
name: string;
}
// main.ts
import type { User } from "./types";
export const greet = (user: User): string => `Hello, ${user.name}`;
The import is explicitly type-only, so a single-file transpiler can remove it without accidentally emitting a runtime import.
When to use it
transpileModule pipelines
A build tool calls TypeScript’s transpileModule API instead of compiling the complete program.
Cross-compiler safety
A large codebase wants diagnostics for source patterns that depend on whole-program type information.
Interview questions
QWhat does isolatedModules do?
It is a compiler option that checks whether each file can be safely transformed without relying on the complete program’s type information. It is useful with Babel and TypeScript’s transpileModule API, which process files independently. The option reports problematic patterns but does not otherwise change checking or emitting behavior.
Follow-up: What problem does it address that ordinary type checking may miss? A program can type-check while a single-file emitter still produces invalid runtime JavaScript for constructs such as type-only exports, namespaces, or ambient const-enum references.
QWhy are type-only imports relevant to isolatedModules?
A type-only import explicitly states that the imported name exists only for type analysis. This lets a single-file transpiler remove the import confidently instead of guessing whether it represents a runtime value.
Follow-up: How should a mixed type/value import be handled? Keep the value import as a normal import and mark only the type bindings with type-only syntax, using the supported import syntax for the project’s TypeScript version.
QWhich constructs does isolatedModules restrict?
With this option enabled, namespaces are permitted only in files that are modules, meaning the file has an import or export. Ambient const-enum member references are also rejected because their replacement requires information unavailable to a single-file transpiler.
Follow-up: Does the namespace restriction apply to declaration files? No; the documentation specifically excludes .d.ts files from that restriction.
Related
transpileModuleconst enumnamespacetype-only imports and exportsverbatimModuleSyntax