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

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
• namespace с кодом времени выполнения
• Устаревшие module с кодом времени выполнения
• свойства параметров
• псевдонимы импорта

Поддерживаются namespaces и module, не содержащие кода времени выполнения. Этот пример будет работать правильно:

// This namespace is exporting a type
namespace TypeOnly {
   export type A = string;
} copy

В этом случае возникнет ошибка ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX:

// This namespace is exporting a value
namespace A {
   export let x = 1
} copy

Поскольку декораторы в настоящее время являются предложением 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'; copy

В этом случае возникнет ошибка во время выполнения:

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

Формы ввода, не являющиеся файлами

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

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

Исходные карты

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

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

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

Псевдонимы путей

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