Як запускати TypeScript прямо в Node.js без збірки і що таке erasableSyntaxOnly?

Сучасний Node.js виконує .ts-файли без окремої збірки: він замінює анотації типів пробілами (type stripping) і запускає те, що лишилося.

node scripts/import-vacancies.ts

Зняття типів увімкнене за замовчуванням з Node.js 22.18 / 23.6 і стабільне з 24.12 / 25.2. Перевірки типів при цьому немає - помилки типів не зупинять запуск.

Обмеження - лише «стиранний» синтаксис. Node.js не генерує код, він тільки прибирає типи. Конструкції TypeScript, що створюють JavaScript, не підтримуються:

• enum;
• namespace з кодом під час виконання;
• параметри-властивості в конструкторі (constructor(private repo: Repo));
• import x = require(...) і псевдоніми імпорту;
• декоратори (поки їх немає в самому JavaScript).

Прапорець --experimental-transform-types, що їх перетворював, у Node.js 26 прибрали.

erasableSyntaxOnly (з TypeScript 5.8) змушує tsc повідомляти про такі конструкції заздалегідь:

enum Status { Draft, Published }   // error TS1294: This syntax is not allowed when 'erasableSyntaxOnly' is enabled

Замість enum - об'єкт з as const і тип-об'єднання; замість параметрів-властивостей - звичайні поля.

Рекомендовані Node.js налаштування tsconfig.json:

{
  "compilerOptions": {
    "noEmit": true,
    "target": "esnext",
    "module": "nodenext",
    "rewriteRelativeImportExtensions": true,
    "erasableSyntaxOnly": true,
    "verbatimModuleSyntax": true
  }
}

Інші особливості:

• розширення обов'язкові: import { x } from './utils.ts';
• import type для типів - інакше Node.js залишить імпорт і впаде (тому verbatimModuleSyntax);
• tsconfig.json ігнорується: paths не працюють - замість них subpath imports у package.json ("#/*");
• файли в node_modules не виконуються - пакети мають публікуватися як JavaScript;
• .tsx не підтримується.

Коли це доречно: скрипти, утиліти, інструменти розробки, невеликі сервіси - там, де збірка була зайвим кроком. Для повної підтримки TypeScript (paths, enum, JSX) - інструменти на кшталт tsx або звичайна збірка.

Докладніше в документації: Node.js: TypeScript