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

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, они не преобразуются и приведут к ошибке парсера. Node.js не предоставляет полифилы и поэтому не поддерживает декораторы, пока они не будут поддерживаться в 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" не преобразуются и поэтому приводят к ошибке. Ближайшая доступная возможность — импорты подпутей, с ограничением: они должны начинаться с #.