resolve.alias
別名: パスエイリアス / module alias / エイリアス解決
バンドラが import のパス文字列を実ファイルへ解決するときに参照する別名テーブル。
tsconfig の paths は型解決だけを担うため、実行時の解決にはバンドラ側の設定が別に要る。
公開:
定義
resolve.alias は、バンドラが import のパス文字列を実ファイルへ変換するときに参照する別名テーブルである。@/components/Button のような短い指定を src/components/Button へ読み替えるために使う。Vite と Vitest、webpack はこのキー名を使い、Jest は同じ役割を moduleNameMapper が担う。
詳細
重要なのは、TypeScript の tsconfig.json にある paths とは 役割がまったく別 だという点である。paths はコンパイラに型定義を見つけさせるだけで、出力されるコードのパス文字列は書き換えない。
そのため型チェックは通るのに、ビルドや実行の段階でだけ「モジュールが見つからない」と落ちる、という食い違いが起きる。
解消するには、同じ別名をバンドラ側にも書くか、vite-tsconfig-paths のようなプラグインで paths の内容をバンドラの解決設定へ流し込む。
テストランナーも独立した解決設定を持つため、そこにも同じ定義が要る。
よくある誤解
- tsconfig に書けば動く: 型解決にしか効かない。TypeScript の tsconfig paths が解決されない はこの型である。
- 相対パスと同じように扱われる: 別名は前方一致で置換されるため、
@と@utilsのように前方一致する定義が並ぶと、書いた順によって意図しない側に当たることがある。
関連
アプリのビルドは通るのにテストだけ落ちる場合は、テストランナー側に別名が入っていないことがほぼ確実な原因になる。
型側の設定は tsconfig paths が受け持つ。