Node.jsでTypeScriptを直接実行する｜型検査を残してビルドを減らす条件

Node.js 26が2026年10月28日にLTSへ移行しました。運用スクリプトや小さなバックエンド処理をTypeScriptで管理するチームは、JavaScriptへ書き出してから実行する工程を残すべきか、Node.jsの直接実行へ絞れるかを再評価できます。ただし、TypeScriptのファイルが動いたことは、型検査が済んだことを意味しません。

本稿は11月1日に確認したNode.js 26.13.0の公式リリースと、同版表示の公式ドキュメントに基づく実践解説です。直接実行はLTS移行で初めて登場した機能ではありません。以下は導入判断のためのコード例で、この制作環境では実行していません。対象はNode.js内で使うスクリプトで、ブラウザー向けアプリのビルドを一括で置き換える手順ではありません。

直接実行で省くのは型検査ではなく変換工程

Node.jsのModules: TypeScript公式資料が説明する組み込み機能は、消去できる型構文を取り除いて実行するtype strippingです。型注釈を実行時の検証へ変える機能ではありません。引数にnumberと書いたからといって、外部入力が数値であることを自動で確認するわけではありません。

導入を考えやすいのは、実行するNode.jsの版を管理でき、特殊な変換へ依存しない集計、開発補助、データ整形などです。出力ファイルを残さずソースを実行できれば、その用途では変換用の起動設定を減らせます。一方、配布物の作成、ブラウザー向け最適化、フレームワーク固有の変換が目的なら、既存ツールの役割を先に確認します。

比較では、型検査、構文変換、実行、配布の四つを分けます。現在の一つのコマンドが全部を担っている場合、コマンドを短くするだけで品質ゲートまで消える可能性があります。何を省き、何を別コマンドへ残すのかを、スクリプトごとに決めてください。パッケージ数が減ることだけを採用条件にしない方が、変更の意図を説明しやすくなります。

最小例は型だけのimportと計算を分ける

次はscripts/model.mtsとscripts/report.mtsを作る説明例です。.mtsを使い、ES Modulesとして扱う意図を拡張子で明示します。値を外部から取得せず、定数の配列を集計するだけなので、最初の読み込み確認に使えます。実際の金額処理へ使う場合は、丸めや通貨などの業務条件を別途定義してください。

// scripts/model.mts
export type Item = {
  label: string;
  amount: number;
};

// scripts/report.mts
import type { Item } from './model.mts';

const items: Item[] = [
  { label: 'sample-a', amount: 120 },
  { label: 'sample-b', amount: 80 },
];

const total = items.reduce(
  (sum, item) => sum + item.amount, 0
);
console.log(total);

実行例はnode ./scripts/report.mtsです。ここでのimport typeは型情報だけの参照で、実行時の値としてItemを探す指定ではありません。値を提供しない型定義を通常のimportとして読むと、型の消去と実際の読み込みが食い違います。ファイルの拡張子も省略せず、実在する参照先と対応させます。

この例でamountへ文字列を入れた場合、型検査では数値との不一致を見つけたいところです。しかし直接実行は、その型契約の検査を行いません。意図しない値で計算が進む可能性を、実行成功の表示だけでは排除できません。外部APIやJSONから受ける値は、必要な実行時検証も残します。

tsconfigは実行用ではなく型検査用として読む

Node.jsの組み込み実行はtsconfig.jsonを読みません。設定ファイルを置いたからNode.jsの読み込みが変わる、という関係にはなりません。一方、TypeScriptコンパイラーへ検査対象と制約を渡すためには使えます。次はこの小さなscriptsディレクトリー用に分けたtsconfig.scripts.jsonの例です。

{
  "compilerOptions": {
    "target": "esnext",
    "module": "nodenext",
    "strict": true,
    "noEmit": true,
    "allowImportingTsExtensions": true,
    "erasableSyntaxOnly": true,
    "verbatimModuleSyntax": true
  },
  "include": ["scripts/**/*.mts"]
}

使用するTypeScriptは、この設定を扱える版をプロジェクトで固定します。Node.js資料は5.8以降を推奨しています。erasableSyntaxOnlyの公式説明に沿って、消すだけでは実行できない構文を検査で見つけます。これだけですべてのランタイム互換性を保証するわけではありません。

型参照を明示する方針はverbatimModuleSyntaxでそろえます。またnoEmitは出力ファイルを作らない指定です。今回の構成では検査に使い、実行はNode.jsへ任せます。既存のアプリ全体の設定へ、目的を確認せず上書きしないでください。

検査に成功した後だけ実行する

CIでは先にプロジェクト内のTypeScriptで検査し、失敗したら実行へ進めない順序を作ります。次はtypescriptが開発依存に入っているプロジェクトのpackage.jsonへ加えるscripts部分の例です。他の項目を削除するものではありません。検査と実行を別名にすると、どちらが失敗したかも追いやすくなります。

{
  "scripts": {
    "typecheck:scripts": "tsc --project tsconfig.scripts.json",
    "report": "node ./scripts/report.mts",
    "check-and-report": "npm run typecheck:scripts && npm run report"
  }
}

noEmitを指定した型検査は、JavaScriptの成果物を出しません。実行側で読むのは元の.mtsです。CIの後段でdistディレクトリーを配布する既存設定があれば、その前提も修正対象です。ビルドを外したのに古い成果物を配っていた、という取り違えを避けるため、起動ファイルと配布内容を一組で確認します。

開発端末だけでなく、CI、コンテナー、定期実行先のNode.jsの版を記録します。TypeScriptコンパイラーの版も別に残し、片方を更新したときの結果を区別します。スクリプトが動く端末で型検査を省いてもよい、という運用へ変えず、通常のレビューとCIで同じ検査コマンドを通す条件を維持します。

enumやパラメータープロパティは先に棚卸しする

組み込みの型消去は、新しいJavaScriptを生成する変換を行いません。enum、実行時コードを含むnamespace、コンストラクターのパラメータープロパティなどへ依存している場合は、そのまま動くと考えないでください。Node.js 26では、旧来のexperimental-transform-typesフラグも削除されています。古い記事のフラグを足して解決しようとする前に、対象版の仕様を確認します。

採否は二つの方向で考えられます。小さな補助スクリプトなら、消去可能な構文へ整理する工数を比較します。フレームワークや既存ライブラリーが広く変換へ依存するなら、そのツールチェーンを維持します。直接実行へ寄せるためだけにアプリ全体を書き換える必要はありません。どの機能を使っているかを見て対象範囲を限定します。

pathsと拡張子を実際の読み込みで確かめる

tsconfigのpathsで別名を定義していても、Node.jsの直接実行がその対応表を使うわけではありません。型検査で見つかったモジュールを、実行時にも同じ規則で見つけられるかを確認します。最初の移行では相対パスの小さな処理へ絞り、別名解決が必要な処理と分けると、不具合の境界を追いやすくなります。

型検査側でTypeScript拡張子を許すallowImportingTsExtensionsも、Node.jsへ変換機能を追加する設定ではありません。今回のnoEmit構成では元ファイルを読みます。JavaScriptを書き出す構成へ変えるなら、出力後に残る参照先まで改めて設計してください。

参照先の存在、拡張子、ファイル名の大文字小文字、モジュール方式を順に確認します。一つの端末だけで解決できたことを、Linuxの配布先でも成功する根拠にしません。型だけを読み込むファイルと、初期化処理を持つファイルも区別します。必要な副作用までimport typeへ変更して消さないように、レビューでは用途を確かめます。

パッケージ配布とブラウザー向け処理は別の判断

Node.js資料では、node_modules配下のTypeScriptファイルを組み込みの型消去で扱うことを拒否すると説明しています。アプリ内の補助スクリプトが動いたからといって、.tsのまま公開した依存パッケージを同じように使えるとは限りません。公開するライブラリーでは、利用側の実行環境、JavaScriptと型宣言の配布、exportsの設計を別に確認します。

また.tsxは組み込み実行の対象ではありません。ブラウザー向けのJSX、CSS、画像の取り込みやコード分割などを、型消去の機能だけで置き換えないでください。フロントエンドのバンドラーと、Node.js内で動く運用スクリプトは責任範囲が異なります。ビルド設定を減らす変更は、担当していた処理が残っていないかを確認してから進めます。

導入前の比較は正常系と失敗系を対にする

最初の比較では、正常な入力での結果を現行の実行方式とそろえます。次に型の不一致、存在しない参照先、未対応構文、実行時例外を試し、どの段階で止まるかを記録します。型検査に失敗しても実行コマンドだけなら進めてしまう構成を、CIが止められることも確認してください。未実行の例を検証済みとして報告しないことが大切です。

測定する場合は、変換時間と実行時間を分け、依存のインストールやキャッシュ条件をそろえます。本稿は速度や容量を実測していないため、必ず高速になるとは述べません。設定が減っても、対応版の管理や型検査の維持に必要な作業は残ります。戻せる小さな変更で比較し、運用上の負担まで含めて採否を決めます。

Node.jsによる直接実行は、型検査と実行を分担する選択肢です。消去可能な構文で完結するスクリプトから試し、検査コマンドと実行先の版を固定します。変換が必要な構文や配布要件がある場所では既存工程を残す。その単位で判断すれば、動いたという一回の確認だけで品質ゲートを外さず、構成を簡素化できる範囲を見つけられます。

関連記事

TypeScript 7.1 Betaのimport属性と型宣言の移行解説では、型定義と実際の読み込み機能の違いを扱っています。本稿はNode.jsの組み込み実行が対象です。ベータ版の型宣言を追加しても、Node.jsに未対応の読み込み機能が加わるわけではありません。

参考資料

Node.js：26.13.0のLTS公開（2026年10月28日）
Node.js：Modules: TypeScript（26.13.0表示を確認）
TypeScript：erasableSyntaxOnly
TypeScript：noEmit
TypeScript：verbatimModuleSyntax
TypeScript：allowImportingTsExtensions