Модули: TypeScript

[История]

Версия	Изменения
v22.7.0	Добавлен флаг --experimental-transform-types.

[Стабильность: 1 - Экспериментально]

Стабильность: 1 Стабильность: 1.1 - Активная разработка

Включение

Существует два способа включить поддержку TypeScript во время выполнения в Node.js:

Полная поддержка TypeScript

Для использования TypeScript с полной поддержкой всех функций TypeScript, включая tsconfig.json, можно использовать сторонний пакет. В этих инструкциях используется tsx в качестве примера, но существует множество других подобных библиотек.

Удаление типов

Добавлено в: v22.6.0

[Стабильность: 1 - Экспериментально]

Стабильность: 1 Стабильность: 1.1 - Активная разработка

Флаг --experimental-strip-types позволяет Node.js запускать файлы TypeScript. По умолчанию Node.js будет выполнять только файлы, которые не содержат функций TypeScript, требующих преобразования, таких как перечисления или пространства имен. Node.js заменит встроенные аннотации типов пробелами, и проверка типов выполняться не будет. Для включения преобразования таких функций используйте флаг --experimental-transform-types. Функции TypeScript, зависящие от настроек в tsconfig.json, такие как пути или преобразование нового синтаксиса JavaScript в более старые стандарты, намеренно не поддерживаются. Для получения полной поддержки TypeScript см. Полная поддержка TypeScript.

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

Удаление типов работает с большинством версий TypeScript, но мы рекомендуем версию 5.7 или новее со следующими настройками tsconfig.json:

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

Определение системы модулей

Node.js поддерживает синтаксис как CommonJS, так и ES Modules в файлах TypeScript. Node.js не будет преобразовывать одну систему модулей в другую; если вы хотите, чтобы ваш код выполнялся как ES-модуль, вы должны использовать синтаксис import и export, а если вы хотите, чтобы ваш код выполнялся как CommonJS, вы должны использовать require и module.exports.

• Система модулей для файлов .ts определяется так же, как и для файлов .js. Чтобы использовать синтаксис import и export, добавьте "type": "module" в ближайший родительский package.json.
• Файлы .mts всегда будут выполняться как ES-модули, аналогично файлам .mjs.
• Файлы .cts всегда будут выполняться как модули CommonJS, аналогично файлам .cjs.
• Файлы .tsx не поддерживаются.

Как и в файлах JavaScript, расширения файлов являются обязательными в операторах import и выражениях import() : import './file.ts', а не import './file'. Из-за обратной совместимости расширения файлов также являются обязательными в вызовах require() : require('./file.ts'), а не require('./file'), аналогично тому, как расширение .cjs является обязательным в вызовах require в файлах CommonJS.

Параметр tsconfig.json allowImportingTsExtensions позволит компилятору TypeScript tsc выполнять типизацию файлов с спецификаторами import, которые включают расширение .ts.

Функции TypeScript

Поскольку Node.js только удаляет встроенные типы, любые функции TypeScript, которые включают замену синтаксиса TypeScript новым синтаксисом JavaScript, будут вызывать ошибку, если не будет передан флаг --experimental-transform-types.

Наиболее заметные функции, требующие преобразования:

• Enum
• namespaces
• legacy module
• свойства параметров

Поскольку декораторы в настоящее время являются предложением TC39 на стадии 3 и вскоре будут поддерживаться движком JavaScript, они не преобразуются и приведут к ошибке парсера. Это временное ограничение, которое будет решено в будущем.

Кроме того, Node.js не читает файлы tsconfig.json и не поддерживает функции, которые зависят от настроек в tsconfig.json, такие как пути или преобразование более нового синтаксиса JavaScript в более старые стандарты.

Импорт типов без ключевого слова type

Из-за особенностей удаления типов ключевое слово type необходимо для правильного удаления импортов типов. Без ключевого слова type Node.js будет обрабатывать импорт как импорт значения, что приведет к ошибке времени выполнения. Для соответствия этому поведению можно использовать опцию tsconfig verbatimModuleSyntax.

Этот пример будет работать корректно:

import type { Type1, Type2 } from './module.ts'
import { fn, type FnParams } from './fn.ts'

Это приведет к ошибке времени выполнения:

import { Type1, Type2 } from './module.ts'
import { fn, FnParams } from './fn.ts'

Нефайловые формы ввода

Удаление типов может быть включено для --eval. Система модулей будет определяться с помощью --input-type, как и для JavaScript.

Синтаксис TypeScript не поддерживается в REPL, вводе из STDIN, --print, --check и inspect.

Карты источников

Поскольку встроенные типы заменяются пробелами, карты источников не нужны для правильных номеров строк в трассировках стека; и Node.js их не генерирует. Когда включен параметр --experimental-transform-types, карты источников включаются по умолчанию.

Удаление типов в зависимостях

Чтобы препятствовать авторам пакетов публиковать пакеты, написанные на TypeScript, Node.js по умолчанию откажется обрабатывать файлы TypeScript в папках под путем node_modules.

Алиасы путей

tsconfig "paths" не будут преобразованы и, следовательно, приведут к ошибке. Ближайшей доступной функцией являются импорты подпутей с ограничением, что они должны начинаться с #.