TypeScript --erasableSyntaxOnly 플래그, 왜 생겼고 언제 쓰나

Source: Dev.to

What is --erasableSyntaxOnly?

--erasableSyntaxOnly is a new compiler flag introduced in TypeScript 5.8.
When enabled in tsconfig.json, the compiler reports errors for any TypeScript‑only syntax that cannot be simply stripped away without affecting the generated JavaScript runtime.

{
  "compilerOptions": {
    "erasableSyntaxOnly": true
  }
}

Prohibited Syntax

The flag blocks the following constructs because they require runtime code generation:

Erasable vs. Non‑erasable Syntax

Erasable

Erasable syntax can be removed entirely; only its type information is needed.

// ✅ Erasable – type can be stripped
function greet(name: string): string {
  return `Hello, ${name}`;
}

// After erasing types
function greet(name) {
  return `Hello, ${name}`;
}

Non‑erasable

Non‑erasable syntax must stay because it produces observable JavaScript.

// ❌ Non‑erasable – runtime behavior required
enum Status {
  Active,
  Inactive
}
console.log(Status.Active); // 0

Compiled output for the enum:

var Status;
(function (Status) {
    Status[Status["Active"] = 0] = "Active";
    Status[Status["Inactive"] = 1] = "Inactive";
})(Status || (Status = {}));

Removing the enum would cause a runtime error, so it is non‑erasable.

Why This Flag Exists?

Two related developments drive the need for --erasableSyntaxOnly:

1. Node.js experimental “strip‑types” mode (available from Node 23.6) lets you run a .ts file directly:

   node --experimental-strip-types app.ts

   This mode only strips type annotations; it does not support constructs that need JavaScript emission (e.g., enums, namespaces).

2. TC39 “Types as Comments” proposal (Stage 1).
   The proposal aims to let browsers ignore TypeScript‑style type annotations as if they were comments, enabling direct execution of TypeScript code without a build step. For this to work, only erasable syntax may be used; any construct that produces runtime artifacts is out of scope.

   “Enums, namespaces, and parameter properties would be out of scope for this proposal since they have observable runtime behavior.” — Daniel Rosenwasser, 2022

Relationship to Enums

The TypeScript team has not deprecated enum. A 2020 GitHub issue titled “Deprecate const enum” was declined, indicating a commitment to backward compatibility.

The official handbook merely suggests modern alternatives:

“In modern TypeScript, you may not need an enum when an object with as const could suffice… The biggest argument in favour of this format over TypeScript’s enum is that it keeps your codebase aligned with the state of JavaScript.”

So the guidance is not “stop using enums,” but consider alternatives that align with JavaScript’s direction.

Recommended Patterns for New Code

Below are idiomatic replacements for the prohibited constructs.

Replace enum

// Before
enum Status {
  Active = 'active',
  Inactive = 'inactive'
}

// After
export const Status = {
  Active: 'active',
  Inactive: 'inactive'
} as const;

export type Status = typeof Status[keyof typeof Status];

Replace namespace

// Before
namespace Utils {
  export function format(s: string) { /* ... */ }
}

// After (utils.ts)
export function format(s: string) { /* ... */ }

Replace parameter properties

// Before
class User {
  constructor(public name: string) {}
}

// After
class User {
  name: string;
  constructor(name: string) {
    this.name = name;
  }
}

FAQ

References

• TypeScript 5.8 Release Notes – details the new flag.
• TC39 Proposal – “Types as Comments”
• Node.js – --experimental-strip-types – documentation for running TypeScript files directly.
• TypeScript Design Goals – “Align with current and future ECMAScript proposals.”