Const Enums Break Without Cross-File Context
What you'll learn: Why const enums fail when TypeScript compiles files independently, and how isolatedModules protects you from this trap.
The Cross-File Problem
Remember that const enums are completely inlined at compile time — the compiler replaces every reference with the actual value. This magic requires TypeScript to "see" the enum definition when processing code that uses it.
When isolatedModules is enabled (which bundlers like Babel, esbuild, and swc require), TypeScript compiles each file as if no other files exist. The compiler can't peek into enums.ts while processing app.ts. Without cross-file context, it has no idea what values to inline.
Why This Matters
// enums.ts
export const enum Direction {
Up = 1,
Down = 2
}
// app.ts
import { Direction } from './enums';
const move = Direction.Up; // What value should this be?
When isolatedModules: true, TypeScript compiles app.ts alone. It sees an import, but cannot read the enum definition to know that Direction.Up should become 1. The inlining breaks.
The Protection Mechanism
With isolatedModules enabled, TypeScript blocks const enums entirely to prevent runtime errors. You'll get a compile-time error if you try to use them, forcing you to use regular enums or string literal unions instead — both of which emit actual JavaScript that bundlers can handle file-by-file.
This is a safety guardrail: if your build pipeline can't do whole-program compilation, const enums simply won't work.
Key Takeaway: Const enums require TypeScript to see all files together during compilation; isolatedModules disables them because bundlers compile files independently without cross-file context.