"isolatedModules"
Makes sure every file can be translated to JavaScript on its own, without knowing about the rest of the project.
Example
#{
"compilerOptions": {
"isolatedModules": true,
"noEmit": true
}
}Definition and usage
#Tools such as esbuild, SWC, and Babel, used by Vite, Next.js, or Vitest, translate TypeScript to JavaScript file by file and don’t analyze types. The isolatedModules option reports constructs that can’t be translated correctly this way, before they turn into an error in a running program.
The option doesn’t change the generated code, it only adds checks. Most often it requires marking re-exports of types with export type, and forbids reading values from declare const enum, because a tool that sees a single file doesn’t know whether a name is a type, or what value stands behind a constant.
Project templates usually have it enabled, including the file created by tsc --init since TypeScript 5.9. The verbatimModuleSyntax option turns on the same checks, so with it isolatedModules is redundant.
Syntax
#"isolatedModules": trueMore examples
#// src/index.ts
export { Course, formatTitle } from './course'
// Error: Re-exporting a type when 'isolatedModules' is enabled requires using 'export type'.// src/index.ts
export { type Course, formatTitle } from './course'
// or on two lines:
// export type { Course } from './course'
// export { formatTitle } from './course'Good practices
#- Using Vite, Next.js, esbuild, or SWC? Enable
isolatedModules(orverbatimModuleSyntax). The compiler will warn you about code the bundler would translate incorrectly. - The option doesn’t speed up
tsc. Type checking still covers the whole project, only the set of allowed constructs changes. - When re-exporting types, write
export type { … }or mark individual names:export { type A, b }.
Related entries
#- "verbatimModuleSyntax"Imports without the word type stay in JavaScript unchanged, so type imports must be marked explicitly.
- import typeA type-only import that disappears completely from the generated JavaScript.
- enumA named set of constant values, either numbers or strings.
- "module"The module format of the generated code and how imports are understood.
- "target"The JavaScript version the compiler turns your code into.
Spotted a mistake or missing an example? Write to us.