"isolatedModules"

Makes sure every file can be translated to JavaScript on its own, without knowing about the rest of the project.

On this page

Example

#
JSON
{
  "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

#
Syntax
"isolatedModules": true

More examples

#
Re-exporting a type
TypeScript
// src/index.ts
export { Course, formatTitle } from './course'
// Error: Re-exporting a type when 'isolatedModules' is enabled requires using 'export type'.
The fixed export
TypeScript
// 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 (or verbatimModuleSyntax). 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

#

Spotted a mistake or missing an example? Write to us.