モジュール: TypeScript

[履歴]

バージョン	変更内容
v22.7.0	--experimental-transform-types フラグを追加

[安定性: 1 - 試験段階]

安定性: 1 安定性: 1.1 - アクティブ開発中

有効化

Node.js でランタイム TypeScript サポートを有効にする方法は 2 つあります。

完全な TypeScript サポート

tsconfig.jsonを含むすべての TypeScript 機能を完全にサポートして TypeScript を使用するには、サードパーティのパッケージを使用できます。これらの手順では、例としてtsxを使用していますが、他にも多くの同様のライブラリがあります。

型の除去

追加バージョン: v22.6.0

[安定性: 1 - 試験段階]

安定性: 1 安定性: 1.1 - アクティブ開発中

フラグ--experimental-strip-typesにより、Node.js は TypeScript ファイルを実行できます。デフォルトでは、Node.js は、列挙型や名前空間など、変換を必要とする TypeScript 機能を含まないファイルのみを実行します。Node.js はインライン型注釈を空白で置き換え、型チェックは実行されません。このような機能の変換を有効にするには、フラグ--experimental-transform-typesを使用します。tsconfig.json内の設定に依存する TypeScript 機能（パスや新しい 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 は、TypeScript ファイルで CommonJS と ES Modules の両方の構文をサポートしています。Node.js は、一方のモジュールシステムからもう一方のモジュールシステムに変換することはありません。コードを ES モジュールとして実行する場合は、import と export 構文を使用する必要があり、CommonJS として実行する場合は、require と module.exports を使用する必要があります。

• .ts ファイルのモジュールシステムは、.js ファイルと同じ方法で決定されます。import と export 構文を使用するには、最も近い親の package.json に "type": "module" を追加します。
• .mts ファイルは、.mjs ファイルと同様に、常に ES モジュールとして実行されます。
• .cts ファイルは、.cjs ファイルと同様に、常に CommonJS モジュールとして実行されます。
• .tsx ファイルはサポートされていません。

JavaScript ファイルと同様に、import 文と import() 式では ファイル拡張子が必須です：import './file.ts'、import './file' ではありません。後方互換性のために、require() コールでもファイル拡張子が必須です：require('./file.ts')、require('./file') ではありません。これは、CommonJS ファイルの require コールで .cjs 拡張子が必須であることと同様です。

tsconfig.json のオプション allowImportingTsExtensions を使用すると、TypeScript コンパイラ tsc は、.ts 拡張子を含む import 指定子を持つファイルの型チェックを行うことができます。

TypeScript の機能

Node.js はインライン型のみを削除するため、TypeScript 構文を新しい JavaScript 構文で置換する TypeScript の機能は、フラグ --experimental-transform-types を渡さない限り、エラーになります。

変換を必要とする最も顕著な機能は次のとおりです。

• Enum
• namespaces
• legacy module
• パラメータプロパティ

デコレータは現在 TC39 Stage 3 proposal であり、まもなく JavaScript エンジンでサポートされるため、変換されず、パーサーエラーが発生します。これは一時的な制限であり、将来解決されます。

さらに、Node.js は tsconfig.json ファイルを読み取らず、パスや新しい JavaScript 構文の古い標準への変換など、tsconfig.json 内の設定に依存する機能をサポートしません。

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に対して有効にすることができます。JavaScript の場合と同様に、モジュールシステムは--input-typeによって決定されます。

REPL、STDIN 入力、--print、--check、inspectでは TypeScript 構文はサポートされていません。

ソースマップ

インライン型は空白で置き換えられるため、スタックトレースの行番号を正しく表示するためにソースマップは不要であり、Node.js は生成しません。--experimental-transform-typesを有効にすると、ソースマップがデフォルトで有効になります。

依存関係における型削除

Node.js は、TypeScript で記述されたパッケージのパッケージ作者による公開を抑制するために、デフォルトでnode_modulesパス下のフォルダ内の TypeScript ファイルの処理を拒否します。

パスエイリアス

tsconfig "paths"は変換されず、エラーが発生します。最も近い機能はサブパスインポートですが、#で始まる必要があるという制限があります。