モジュール: TypeScript#

履歴
バージョン変更点
v24.3.0, v22.18.0

型情報の除去は、実験的な警告を出力しなくなりました。

v23.6.0, v22.18.0

型情報の除去はデフォルトで有効になりました。

v22.7.0

--experimental-transform-types フラグが追加されました。

安定性: 1.2 - Release candidate

有効化#

Node.js で実行時の TypeScript サポートを有効にするには2つの方法があります。

  1. TypeScript のすべての構文と機能を完全にサポートし、任意のバージョンの TypeScript を使用するには、サードパーティのパッケージを使用します。

  2. 軽量なサポートのためには、組み込みの型情報の除去サポートを使用できます。

TypeScript の完全なサポート#

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

  1. プロジェクトで使用しているパッケージマネージャを使用して、パッケージを開発依存関係 (development dependency) としてインストールします。例えば、npm の場合：

    npm install --save-dev tsx

  2. そして、以下のように TypeScript コードを実行できます。

    npx tsx your-file.ts

    あるいは、node を介して以下のように実行することもできます。

    node --import=tsx your-file.ts

型情報の除去 (Type stripping)#

v22.6.0 で追加。

デフォルトでは、Node.js は消去可能な TypeScript 構文のみを含む TypeScript ファイルを実行します。Node.js は TypeScript の構文を空白に置き換え、型チェックは実行されません。enum 宣言やパラメータプロパティなど、JavaScript コードの生成を必要とする消去不可能な TypeScript 構文の変換を有効にするには、--experimental-transform-types フラグを使用します。この機能を無効にするには、--no-experimental-strip-types フラグを使用します。

Node.js は tsconfig.json ファイルを無視するため、tsconfig.json 内の設定に依存する機能（パスや新しい JavaScript 構文の古い標準への変換など）は意図的にサポートされていません。完全な TypeScript サポートを得るには、TypeScript の完全なサポート を参照してください。

型情報の除去機能は軽量になるように設計されています。JavaScript コードの生成を必要とする構文を意図的にサポートせず、インラインの型を空白に置き換えることで、Node.js はソースマップを必要とせずに TypeScript コードを実行できます。

型情報の除去はほとんどのバージョンの TypeScript と互換性がありますが、バージョン5.8以降で以下の tsconfig.json 設定を使用することを推奨します。

{
  "compilerOptions": {
     "noEmit": true, // Optional - see note below
     "target": "esnext",
     "module": "nodenext",
     "rewriteRelativeImportExtensions": true,
     "erasableSyntaxOnly": true,
     "verbatimModuleSyntax": true
  }
}

ビルドスクリプトなど、*.ts ファイルのみを実行する予定の場合は、noEmit オプションを使用してください。*.js ファイルを配布する予定の場合は、このフラグは不要です。

モジュールシステムの決定#

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' ではなく import './file.ts' とします。後方互換性のため、require() 呼び出しでもファイル拡張子は必須です。CommonJS ファイルで .cjs 拡張子が必須であるのと同様に、require('./file') ではなく require('./file.ts') とします。

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

TypeScript の機能#

Node.js はインラインの型を削除するだけなので、TypeScript 構文を新しい JavaScript 構文に*置き換える*ような TypeScript の機能は、--experimental-transform-types フラグが渡されない限りエラーになります。

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

  • Enum 宣言
  • 実行時コードを含む namespace
  • 実行時コードを含むレガシーな module
  • パラメータプロパティ
  • インポートエイリアス

実行時コードを含まない namespaces と module はサポートされています。この例は正しく動作します。

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

これは ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX エラーになります。

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

デコレータは現在 TC39 Stage 3 プロポーザルであり、まもなく 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 と STDIN (標準入力) で型情報の除去を有効にできます。モジュールシステムは、JavaScript の場合と同様に --input-type によって決定されます。

TypeScript 構文は、REPL、--check、および inspect ではサポートされていません。

ソースマップ#

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

依存関係における型情報の除去#

パッケージの作者が TypeScript で書かれたパッケージを公開するのを防ぐため、Node.js は node_modules パス以下のフォルダにある TypeScript ファイルの処理を拒否します。

パスエイリアス#

tsconfig の "paths" は変換されないため、エラーが発生します。利用可能な最も近い機能はサブパスインポートですが、# で始まらなければならないという制限があります。