Skip to content
Tutorials Center
My learning

Topics

TypeScript Reference ยท tsconfig: Language, Modules and Emit Options

TypeScript isolatedModules option

Reference for isolatedModules: the rules that make every file safe to transpile alone for esbuild, SWC, Babel and Node, including export type and const enum limits.

Tools such as esbuild, SWC, Babel and Node's type stripping convert each .ts file to JavaScript without looking at any other file. They cannot know whether import { User } from "./user" brings in a type (to be erased) or a value (to be kept). isolatedModules makes the compiler report the TypeScript constructs that cannot be handled correctly by such single-file tools.

It adds no new output; it only adds errors for risky patterns, so a successful tsc --noEmit means the fast transpilers will agree with tsc. Most bundler projects turn it on, and it is implied by verbatimModuleSyntax rules in practice.

JSON
{ "compilerOptions": { "isolatedModules": true } }

Try it

Node can strip types from one string without any project context, which is exactly the situation isolatedModules protects.

TypeScript Transpiling a single file

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

TypeScript Why a missing type keyword is a problem

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

Syntax

JSON
{ "compilerOptions": { "isolatedModules": true } }
Rule enforced Why
Re-exporting a type needs export type { T } from "./a" (error TS1205) A tool cannot tell if T is a type or a value.
Importing a type without type can be flagged when combined with verbatimModuleSyntax or importsNotUsedAsValues The unused import would otherwise vanish or remain inconsistently.
Ambient const enum declarations from other files cannot be inlined Inlining needs the other file. Local const enum is fine.
Every file must be a module (TS1208, in older versions) A script file has no import or export. Add export {};.
Namespace-merging and some export = forms are limited They need whole-program knowledge.

Usage notes

  • The option is an error filter. It does not change the output of tsc and does not speed it up.
  • export type and import type (or inline import { type A, b }) are the main habit to adopt.
  • Prefer a plain enum or an as const object over declare const enum, especially in libraries that others compile with a transpiler.
  • isolatedDeclarations (TypeScript 5.5) goes further: it requires explicit return types on exports so declaration files can also be generated per file.
  • Compile with tsc --noEmit in CI and let the bundler emit; isolatedModules keeps the two in agreement.
  • Code that passes here still needs correct module and moduleResolution settings.