Why does TypeScript's `isolatedModules` flag reject references to an ambient `declare const enum`, and what does a per-file transpiler do with an ordinary `const enum`?

## What makes const enum special An ordinary `enum` emits a real JavaScript object, so `Colors.Red` at runtime is a property access on a thing that exists. A `const enum` opts out of that: the compiler does not emit the object, and instead **inlines** each member reference as its value. ```ts const enum Colors { Red = 0, Green = 1 } const c = Colors.Red; // emitted as: const c = 0 /* Colors.Red */; ``` The attraction is that the abstraction costs nothing at runtime. The catch is that inlining is a *cross-file* operation: to replace `Colors.Red` in your file, the compiler must have read the file where `Colors` is declared and know that `Red` is `0`. ## Why the ambient form is unfixable per file `declare const enum` goes one step further. The `declare` keyword means "this exists, do not emit a definition for it": ```ts // somewhere.d.ts declare const enum Level { Debug = 0, Info = 1 } ``` No file anywhere emits an object for `Level`. `tsc` still works, because it read the declaration and can inline `Level.Info` as `1`. But a per-file transpiler is in an impossible position: it cannot inline, because it never read the declaration; and it cannot emit a property access, because there is no runtime object to access. Either output is wrong. That is exactly the situation `isolatedModules` exists to prevent, so it reports references to ambient const enums as an error. There is no clever workaround at the use site — the construct itself is incompatible with single-file compilation. ## What happens to an ordinary const enum A non-ambient `const enum` is more forgiving, because its declaration is at least *somewhere* in your source. Per-file tools generally handle it by emitting it as an ordinary enum object rather than inlining across files, since a tool that sees the declaration and the use site in the same file may inline locally but has no basis to do so anywhere else. The consequence matters more than the mechanism: the emitted code contains the enum object you were trying to avoid, and member accesses become real property lookups. Nothing crashes, but the one reason to write `const enum` instead of `enum` has quietly gone away, and you are left with the construct's downsides — a runtime value with reverse-mapping behaviour for numeric members — and none of its benefit. It also means the *same source* produces materially different output depending on which tool built it, which is precisely the divergence `isolatedModules` is meant to eliminate. (`tsc` itself has a `preserveConstEnums` option, which makes it emit the object too while still inlining uses — useful when something outside the compilation needs the object to exist.) ## Namespaces and the same reasoning The other construct that sits badly with single-file compilation is `namespace`. A namespace containing only type declarations emits nothing, while one containing values emits an object and an IIFE — and which case you are in depends on the contents, sometimes spread across merged declarations in several files. For code that a per-file tool will process, the durable advice is to express modules as ES modules and reserve `namespace` for declaration files, where it is a description rather than something to emit. ## What to write instead When you want a small closed set of values in a codebase compiled by fast tools: ```ts export const Level = { Debug: 0, Info: 1 } as const; export type Level = (typeof Level)[keyof typeof Level]; ``` This is plain JavaScript with a derived type — no cross-file magic, identical output from every tool, and the values are available at runtime when you need them. A plain string-literal union is even lighter when you never need a runtime object at all. The general rule to carry away: any TypeScript construct whose *emitted* form depends on information in another file is a liability in a modern build, and `isolatedModules` is the flag that tells you where those constructs are.