moduleResolution
別名: モジュール解決 / module resolution / --moduleResolution
moduleResolution は、import や require に書いたモジュール指定子を TypeScript がどのファイルに結び付けるかを決める tsconfig.json のオプションである。
動かす環境に合わせて nodenext か bundler を選ぶ。
公開:
定義
moduleResolution は、import や require に書いた文字列(モジュール指定子)を、TypeScript がディスク上のどのファイルに結び付けるかを決める tsconfig.json のオプションである。
TypeScript は実行時にモジュールを読み込まない。
そのため、この値は実際に動かす Node.js やバンドラーの解決方法と揃えておく。
詳細
いま選ぶ値は nodenext(node16)と bundler の 2 つである。nodenext は Node.js の解決規則をなぞり、ES モジュールとして扱われるファイルでは相対パスに .js などの拡張子を求める。"module": "nodenext" と書けば、moduleResolution も既定で nodenext になる。
bundler は Vite や webpack のようなバンドラー向けの値で、package.json の "exports" を読みつつ、相対パスの拡張子を省略できる。
古い node(別名 node10)は TypeScript 6.0 で非推奨になり、残したままだと tsc がエラーで止まる。classic は 6.0 で廃止された。
値ごとの違いは公式ドキュメント(新しいタブで開く)に表で載っている。
よくある誤解
moduleResolution を変えても、出力される JavaScript の import 文は書き換わらない。bundler で拡張子を省いたコードを、バンドルせずに Node.js でそのまま動かすと、実行時にモジュールが見つからずに落ちる。
型検査が通ることと、実行時に解決できることは別に確かめる。
関連
NodeNext で拡張子が要る場面は TypeScript で NodeNext の import に .js を付けないと解決されない にある。
6.0 で node が使えなくなる経緯は TypeScript「Option 'baseUrl' is deprecated」の原因と直し方 を参照する。
別名の対応表は tsconfig paths で説明している。