Запуск TypeScript нативно

Вы можете писать код, который является валидным TypeScript, прямо в Node.js без необходимости сначала его транспилировать.

Node.js выполняет TypeScript через лёгкий процесс под названием отбрасывание типов (type stripping). Он удаляет стираемый (erasable) синтаксис TypeScript, такой как аннотации типов и интерфейсы, а затем выполняет оставшийся JavaScript.

Если вы используете v22.18.0 или новее и ваш исходный код содержит только стираемый синтаксис TypeScript, вы можете выполнять код на TypeScript без каких-либо флагов.

node example.ts

Если вы используете версию ниже v22.18.0, можно использовать флаг --experimental-strip-types, чтобы запускать файлы TypeScript напрямую в Node.js.

node --experimental-strip-types example.ts

Вот и всё! Теперь вы можете запускать код на TypeScript прямо в Node.js без необходимости сначала его транспилировать.

Node.js не проверяет типы вашего кода, когда выполняет файлы TypeScript. Используйте компилятор TypeScript отдельно, если хотите ловить ошибки, связанные с типами:

npx tsc --noEmit

При необходимости это можно отключить флагом --no-experimental-strip-types.

node --no-experimental-strip-types example.ts

У поддержки TypeScript в Node.js есть ограничения, которые стоит держать в голове:

Больше информации можно получить в документации API.

Отбрасывание типов работает только для синтаксиса TypeScript, который можно удалить без изменения выполняемого JavaScript. Сюда входит распространённый синтаксис только для типов, такой как аннотации типов, интерфейсы, псевдонимы типов (type alias) и import type.

Синтаксис, требующий генерации JavaScript-кода, одним лишь отбрасыванием типов не обрабатывается. Примеры: enum, свойства-параметры (parameter properties), namespace с runtime-кодом и import-псевдонимы. Используйте runner или отдельный шаг транспиляции, если вашему проекту нужны эти возможности.

Запуск .ts-файла через node — это не то же самое, что запуск tsc. Node.js выполняет файл после отбрасывания поддерживаемого синтаксиса типов, но не сообщает об ошибках типов.

Для разработки распространённая связка — запускать Node.js напрямую для быстрой обратной связи и запускать tsc --noEmit отдельной командой или в CI-задаче для проверки типов.

Загрузчик TypeScript в Node.js (Amaro) не нуждается в tsconfig.json и не использует его для запуска кода на TypeScript.

Мы рекомендуем настроить ваш редактор и tsc так, чтобы они отражали поведение Node.js, создав tsconfig.json с compilerOptions, перечисленными здесь, а также использовать TypeScript версии 5.7 или выше.