skip to content

With TypeScript's `erasableSyntaxOnly` on, `namespace Rt { export const x = 1; }` fails with TS1294 while `namespace Ty { export interface P {} }` compiles; why, and how do you fix the first one?

level: seniorimportance: should knowfreq 28%

answer

  1. erase versus generate
  2. the flag arrived in 5.8
  3. no JavaScript equivalent for the wrapper
  4. types-only and declare forms survive
  5. keep call sites with a star import

basics

~20 s

A namespace holding values needs generated code, so deleting its type syntax cannot produce working JavaScript, and erasableSyntaxOnly (TypeScript 5.8) rejects it. A types-only namespace erases cleanly. Move the values into a module, and star-import it to keep call sites.

solid answer

~50 s

`erasableSyntaxOnly`, added in TypeScript 5.8, rejects runtime constructs that are not part of ECMAScript. The test is whether deleting the TypeScript syntax leaves working JavaScript. `namespace Rt` holding a value fails it, because `Rt.x` needs an object and a generated wrapper function. `namespace Ty` holds only an interface and emits nothing, so it erases cleanly, as does `declare namespace`. The flag exists for tools that only strip types: Node's type stripping throws `ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX` on the first and runs the second, and the flag reports that in `tsc` and the editor before anything crashes. It only reports; `tsc` still emits the wrapper unless `noEmitOnError` is set. To fix it, move the members to top-level exports of their own file and write `import * as Rt from './rt'`, which keeps `Rt.x` at call sites. Merged members become class statics or plain functions.

code

typescript · 5 lines
typescript
namespace Rt {
  export const x = 1;
}

console.log(Rt.x);

go deeper

for a junior

Recall that some TypeScript can simply be deleted to leave JavaScript and some cannot, and that a namespace holding values is in the second group.

for a middle

Explain the split inside one keyword: a types-only or declare namespace emits nothing and passes, while a value namespace needs generated code and fails.

for a senior

Demonstrate the migration: use the flag as the inventory, convert with a star import to limit churn, and leave erasable namespaces alone.

for a principal

Decide whether the flag belongs in your standard based on whether strip-only execution is actually planned, and weigh the rewrite of enums and namespaces against that.

## Two kinds of TypeScript syntax Most TypeScript syntax is **erasable**: delete the annotations, interfaces and type aliases and what remains is valid JavaScript that does the same thing. A smaller set of constructs is **not erasable**, because they mean something at runtime that JavaScript has no syntax for, and the compiler has to generate code for them. A namespace can be on either side, depending on what is inside it. ```ts namespace Rt { export const x = 1; } // TS1294 under the flag namespace Ty { export interface P { x: number } } // allowed declare namespace Am { const y: number; } // allowed ``` `Rt` compiles to a variable, a wrapper function and a property assignment. None of that is in the source, so a tool that only deletes syntax cannot produce it. `Ty` and `Am` contribute no JavaScript, so deleting them entirely is exactly right. ## What the flag does `erasableSyntaxOnly` arrived in TypeScript 5.8. The Compiler Options reference describes it as "Do not allow runtime constructs that are not part of ECMAScript", and it defaults to `false`. When it is on, the compiler reports TS1294, "This syntax is not allowed when 'erasableSyntaxOnly' is enabled." Three properties are easy to get wrong: - **It is a check, not a transform.** `tsc` reports the error and still writes the wrapper unless `noEmitOnError` is set. Nothing about the emit changes. - **It covers more than namespaces.** `enum` declarations, parameter properties such as `constructor(public x: number)`, and `import x = Some.Name` aliases are rejected as well. - **It leaves erasable syntax alone.** `abstract` classes, `interface` and `import type` are all fine. - **It is not a deprecation.** The flag is opt-in, and namespaces stay legal for every project that leaves it off. ## Why a tool refuses it Type-stripping runtimes execute TypeScript by removing type syntax and running what is left. Node's type stripping is the common example. Run the two namespaces directly and you see the same split as the flag: - The value namespace throws `ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX`, with the message "TypeScript namespace declaration is not supported in strip-only mode". - The types-only namespace and the `declare` form run normally. The refusal is about generating code and not about reading types. The flag moves the failure from a crash when the program runs to an error in your editor and CI. ## Fixing each form | Form under the flag | Fix | |---|---| | Value namespace | top-level exports in its own module file | | Dotted `namespace App.Utils` | one module per level, or one file with named exports | | Function merged with a value namespace | direct property assignment, or a plain exported function | | Class merged with a value namespace | `static` members or a separate exported class | | `import q = A.B` alias | `const q = A.B` for values, a type alias for types | | Types-only or `declare namespace` | leave it | An alias that pointed at a namespace used for both values and types needs both replacements, unless the module import covers it. The rewrite for the common case keeps call sites unchanged: ```ts // rt.ts export const x = 1; // consumer.ts import * as Rt from './rt'; console.log(Rt.x); ``` ## Rolling it out 1. Turn the flag on and let the compiler list every violation. This is the honest inventory, since it separates value namespaces from harmless types-only ones. 2. Convert value namespaces one at a time, with the star import to limit churn. 3. Where a block was reopened across files, turn each bare name the compiler used to rewrite, such as `salt` for `App.Utils.salt`, into an explicit import. 4. Keep the flag on in CI so the construct cannot return. Do not rewrite types-only namespaces just to clear a pattern from the code. They pass the flag, and the churn buys nothing unless the team has a separate reason for it. A fair judgment call is whether to adopt the flag at all. It is worth it when the code runs through a strip-only tool, or may do so soon. If a compiler or a transforming build step always runs first, the flag is a style choice, and the existing enums and namespaces may not justify the rewrite yet.

  • Does turning on TypeScript's `erasableSyntaxOnly` change what `tsc` emits for a namespace?
    No. It adds error TS1294 and leaves emit alone, so `tsc` still writes the wrapper function unless `noEmitOnError` stops it. The value of the flag is the report: it tells you in the editor and CI what a strip-only tool would refuse at run time.
  • A class merged with a types-only namespace passes `erasableSyntaxOnly`. Why does that merge survive when a merge with values does not?
    The types-only namespace emits nothing, so deleting it leaves the class unchanged and the program behaves the same. A merge with values needs a generated wrapper that assigns members onto the class, and deleting that would remove real behaviour. The test is always whether erasure preserves the meaning.
  • How do you replace a TypeScript `import q = Shapes.Polygons` alias when `erasableSyntaxOnly` rejects it?
    Replace it according to what it aliases. For a value, write `const q = Shapes.Polygons`; for a type, use a type alias. Once the namespace has become a module, the import itself takes over: `import * as Polygons from './polygons'`, with any name you choose.

  • erasableSyntaxOnly rejects every namespace, including declare namespace and types-only ones.
  • Turning on erasableSyntaxOnly makes tsc strip namespaces out of its output.
  • Strip-only tools refuse namespaces because they cannot read type information across files.
  • Enums pass erasableSyntaxOnly because they are only values with fixed names.
  • Abstract classes are rejected because abstract has no JavaScript equivalent.

Assumes TypeScript 5.8 or later, where erasableSyntaxOnly exists; the Node behaviour was checked on Node 25.1 in strip-only mode.