迷走するパス解決に終止符を：TypeScriptのエイリアスを「実戦」で完結させるアーキテクチャ論
フロントエンドの規模が肥大化し、ディレクトリがネストの深淵へと沈んでいくにつれ、我々を悩ませるのが「相対パス地獄」だ。`../../../../components/Button` のようなコードを見て「汚い」と感じないエンジニアは、おそらくコードベースを愛していない。
しかし、`tsconfig.json` で `paths` を設定してめでたし、というのは素人の仕事だ。TypeScriptコンパイラ（`tsc`）は、生成されたJavaScript内のパスを書き換えてくれない。そのままNode.jsやブラウザで動かそうとすれば、「Module not found」というお決まりの絶望が待っている。
今日は、この「コンパイル後のパス解決」という古典的かつ厄介な課題に対し、単なるツールの紹介ではなく、堅牢なアーキテクチャを構築するための「現場の知見」を語ろう。
—
なぜ `tsc` はパスを書き換えないのか？
ここを理解していないと、設計で必ず躓く。TypeScriptの `compilerOptions.paths` は、あくまで「型チェック時」のモジュール解決を補助するためのものだ。ランタイム（Node.jsやブラウザ）は、TypeScriptの独自仕様である `paths` の存在など知る由もない。
だからこそ、我々はビルドパイプラインに「パスの正規化」を組み込む必要がある。ここで登場するのが `tsc-alias` だ。
なぜ `tsc-alias` を選ぶのか
世の中には `module-alias` のようなランタイム依存の解決策もあるが、私はおすすめしない。なぜなら、それらは「実行時のオーバーヘッド」を招くからだ。
- メモリ効率とパフォーマンス: ランタイム解決は、モジュールを読み込むたびにパスの変換処理を走らせる。小規模なスクリプトなら誤差だが、数千モジュールを抱える大規模アプリでは、解決処理のスタックが積み重なり、起動速度やメモリ消費に悪影響を及ぼす。
- 解決策: ビルド時にパスを確定（静的解決）させる `tsc-alias` が圧倒的に合理的だ。一度ビルドしてしまえば、生成されるJSは「純粋な相対パス」を持つ。つまり、ランタイムには一切の負荷をかけない。これが「プロの選択」だ。
—
実装：堅牢なビルドパイプラインの構築
単にツールを入れるだけでなく、開発体験（DX）とビルドの信頼性を両立させる設定を見ていこう。
1. tsconfig.json の構成
まずは基本のベースラインだ。`baseUrl` と `paths` を設定し、型安全性を確保する。
{
“compilerOptions”: {
“baseUrl”: “.”,
“paths”: {
“@core/”: [“src/core/”],
“@features/”: [“src/features/”]
},
// ここが重要：ビルド後の出力先を指定
“outDir”: “dist”
}
}
2. tsc-alias によるビルドの自動化
`package.json` のビルドスクリプトで、`tsc` の後に `tsc-alias` を走らせるのが定石だ。ここで重要なのは、`tsc` が終了した直後に、整合性を保った状態でパスを書き換えることである。
{
“scripts”: {
// && で連結し、tscの成功を保証してから書き換えを実行する
“build”: “tsc && tsc-alias -p tsconfig.json”
}
}
—
アーキテクトとしての一歩先：非同期の競合とモジュール解決
パスエイリアスを解決したとしても、大規模アプリケーションでは「循環参照」や「非同期モジュールの解決ミス」が致命的なバグを引き起こすことがある。
特に、`import()` を多用するコード分割（Code Splitting）環境では、パス解決が不完全だと、ブラウザがチャンクファイルを読み込めず、突如として画面がホワイトアウトする。
最適化へのヒント：
1. 静的解析の徹底: `tsc-alias` は強力だが、複雑なプラグイン環境下ではパス解決が漏れることがある。ビルド後、必ず `dist` ディレクトリ内のJSファイルを `grep` 等で確認し、`@core` のような文字列が残っていないか自動テストで弾くフローをCIに組み込むべきだ。
2. ESMとCommonJSの混在: もしプロジェクトが ESM (`”type”: “module”`) を採用しているなら、パスは「完全なファイル名（拡張子付き）」である必要がある。`tsc-alias` はこの辺りの追従が優秀だが、設定次第では解決に失敗する。必ず `resolveJsonModule: true` や `esModuleInterop: true` との整合性を検証してほしい。
—
最後に：ツールに頼らず、コードを美しく保つ
結局のところ、`tsconfig-paths` や `tsc-alias` は、TypeScriptの言語仕様が抱える「未完成な部分」を埋めるための絆創膏に過ぎない。
真に優れたアーキテクトは、パスエイリアスを使いすぎない。
`@features/auth/types` のような深いエイリアスを多用すると、プロジェクトはディレクトリ構造に依存しすぎて柔軟性を失う。エイリアスは「パッケージの境界（ドメインの境界）」を定義するために使い、それ以外の深いネストは、可能な限りディレクトリの責務を分離して解消すべきだ。
TypeScriptのビルド環境構築は、単なる設定作業ではない。アプリケーションの血液循環を設計する行為だ。正しく設定し、余計なランタイム負荷を削ぎ落とし、最高のパフォーマンスを引き出してほしい。
健闘を祈る。
コメント