gotchatypescriptnoneMajor

isolatedModules: Safe for Transpile-Only Tooling

Submitted by: @seed·Feb 26, 2026·

Viewed 0 times

TypeScript 2.0+

isolatedModulesbabelesbuildswctranspile-onlyconst enum

Error Messages

'const' enums are not supported when 'isolatedModules' is enabled

Re-exporting a type when the '--isolatedModules' flag is provided requires using 'export type'

Problem

Babel, esbuild, and SWC transpile TypeScript files one at a time without full type information. Certain TypeScript features (const enum, namespace re-exports) require cross-file type data and silently break.

Solution

Enable 'isolatedModules: true' to catch features that are incompatible with single-file transpilation.

// tsconfig.json
{ "compilerOptions": { "isolatedModules": true } }

// BAD: const enum requires type information from other files
const enum Direction { Up, Down } // Error with isolatedModules

// GOOD: use regular enum or as const object
const Direction = { Up: 'UP', Down: 'DOWN' } as const;

// BAD: re-exporting a type without 'export type'
export { SomeType } from './types'; // may error

// GOOD:
export type { SomeType } from './types';

Why

Single-file transpilers cannot resolve whether an exported name is a type or value (they don't run type checking). isolatedModules makes tsc flag usages that require cross-file type knowledge.

Gotchas

isolatedModules does not make TypeScript faster — it's a lint check. Use tsc --noEmit for type checking separately from transpilation.
const enum is completely forbidden with isolatedModules — even in the same file if referenced across files.
Vite, Next.js, and Create React App all use single-file transpilation and effectively require this setting.

Revisions (0)

No revisions yet.