【テクニカル・上級編】 compilerOptions.moduleResolution – TypeScript実践ガイド

`moduleResolution` の深淵：なぜあなたのTypeScriptは「迷子」になるのか

フロントエンドのアーキテクチャにおいて、最も見落とされがちでありながら、一度こじれると開発チームの生産性を根底から腐らせる設定項目がある。それが `tsconfig.json` における `moduleResolution` だ。

多くのエンジニアは「とりあえず `node` にしておけば動く」という暗黙の了解でこの設定を放置している。だが、モダンなバンドラー（Vite, esbuild, Rspack）が支配する現代において、その「とりあえず」は、型の不整合、ランタイムの予期せぬ挙動、そして何よりビルドパフォーマンスのジレンマを引き起こす爆弾になり得る。

今日は、この設定が単なる「パス解決のルール」を超えて、いかにアプリケーションの堅牢性に寄与するのか、その深層を解き明かそう。

—

1. `classic` と `node`：歴史の墓標と現在地

まず、歴史的な経緯を整理しておく必要がある。

`classic`: TypeScript黎明期の産物。現在のエコシステムにおいては、もはやアンチパターンだ。相対パスしか解決できず、`node_modules` の深い階層まで自動探索する能力がない。これを使う理由は、レガシーなビルドシステムを維持する以外に存在しない。
`node`: CommonJSの解決アルゴリズムを忠実に再現したもの。`node_modules` の `package.json` にある `main` や `types` を探しに行く、いわば「Node.jsの挙動をTypeScriptに移植したもの」だ。

しかし、現代のフロントエンド開発において `moduleResolution: “node”` が抱える最大の欠陥は、「条件付きエクスポート（Conditional Exports）」に対応できないことにある。

// package.json の典型的な現代的構成
{
“exports”: {
“.”: {
“types”: “./dist/index.d.ts”,
“import”: “./dist/index.mjs”,
“require”: “./dist/index.cjs”
}
}
}

`node` 設定のままだと、TypeScriptは `exports` フィールドを正しく解釈できず、`.d.ts` ファイルを見失うか、あるいは間違ったビルド成果物を参照してランタイムエラーを誘発する。これを防ぐためには、`node16` や `nodenext` を選択し、Node.jsのモジュール解決の作法とTypeScriptの型システムを同期させる必要がある。

—

2. `bundler` の衝撃：なぜ今、これを推奨するのか

現在、TypeScript 5.0以降で推奨される設定、それが `moduleResolution: “bundler”` だ。

なぜこれが最強なのか？それは、「ブラウザ向けバンドラーがどのようにモジュールを解決しているか」という現実と、TypeScriptの型解決を完全に一致させられるからである。

`nodenext` が「Node.jsの厳格な仕様（拡張子の強制など）」を型チェックにも持ち込むのに対し、`bundler` は「拡張子を省略しても、ビルドツールがよしなにやってくれる」というフロントエンドの甘美な現実を型定義に許容する。

実践：`bundler` を採用すべき理由

// 拡張子なしのインポートは、Node.js的にはエラーだが、バンドラーならOK
import { User } from “./models/user”;

// nodenext だとここを “./models/user.js” と書くことを強要されるが、
// bundler なら “./models/user” で型チェックを通せる。
// これにより、ビルドツールとTypeScriptの設定差異による「型はあるのに実行時エラー」を撲滅できる。

この設定の真価は、「ランタイムの競合」を未然に防ぐことにある。ビルドツールが解釈するモジュールグラフと、TSが静的解析する依存関係グラフが乖離していると、メモリ効率やバンドルサイズに悪影響を及ぼす。`bundler` は、この両者の「解釈のズレ」を最小化するための架け橋なのだ。

—

3. パフォーマンス最適化とアーキテクチャの知見

上級エンジニアとして意識すべきは、モジュール解決戦略が「型推論のパフォーマンス」に与える影響だ。

`moduleResolution` を適切に設定しないと、TypeScriptは `node_modules` を探索する際に、不要なディレクトリの深層まで潜り込み、キャッシュを汚染し、再コンパイルの時間を増大させる。

特に、`paths` マッピングと複雑な `exports` が組み合わさった場合、解決戦略が不適切だとTypeScriptはバックグラウンドで膨大なシンボリックリンクのスタックを生成し、メモリを浪費する。

堅牢なアプリケーションのためのチェックリスト

1. Vite / Webpack 5以降を使っている場合: 迷わず `moduleResolution: “bundler”` を選べ。
2. ライブラリ開発を行っている場合: コンシューマーがどのような環境でも動かせるよう、`node16` を選択し、`package.json` の `exports` を極めて厳密に書く必要がある。
3. 非同期の競合回避: `moduleResolution` を `bundler` にすることで、ESMとCJSの相互運用（Interop）時の型定義の不一致による、ビルド後の `undefined` 参照問題を大幅に減らせる。

—

最後に：完璧な環境とは何か

フロントエンドのアーキテクトにとって、`tsconfig.json` は単なる設定ファイルではない。それは「開発環境という名のエンジン」の点火順序を定義する設計図だ。

`moduleResolution` を正しく理解することは、単にビルドエラーを消すことではない。ツールチェーンの挙動を掌中に収め、開発者が「なぜか型が通らない」「なぜか動かない」という非生産的なデバッグから解放され、価値あるコードを書くことに集中できる環境を整えることだ。

もし今、あなたのプロジェクトの `tsconfig.json` が数年前に作成されたまま放置されているなら、今日こそがそれを刷新するチャンスだ。`bundler` の世界へようこそ。そこには、より高速で、より予測可能で、より静かな開発体験が待っている。