Course contentsShow
← TypeScript
Lesson 1255 of 1,79629. The Build PipelineFree lesson

Const Enums Break Without Cross-File Context

Why const enums require whole-program compilation and fail with isolatedModules enabled.

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.