tsconfig paths
別名: paths / パスエイリアス / モジュールエイリアス
TypeScript の tsconfig.json で import "@/foo" のような短いパスを実体パスに対応させるエイリアス設定。
型解決専用で、実行時には別途バンドラやローダの設定が必要。
公開: 更新:
定義
tsconfig paths は、TypeScript の tsconfig.json 内 compilerOptions.paths で定義する、モジュール解決のエイリアスである。
値のパスは tsconfig.json のある場所からの相対で書く。
{
"compilerOptions": {
"paths": {
"@/*": ["./src/*"],
"~/utils/*": ["./src/utils/*"]
}
}
}これにより import { foo } from "@/lib/foo" のように、ファイルの位置に関係なく src からのパスで書ける。
詳細
tsc は paths を「型解決」だけに使う。
コンパイル後の JS に書かれる import 文は置換されないので、実行時の扱いは実行方法ごとに次のようになる。
- Node で直接
node dist/main.jsを実行すると、Cannot find module "@/lib/foo"で落ちる。 - ts-node を使うときは、
tsconfig-pathsを-rオプションで読み込む。 - バンドラ(webpack / Vite)を使うなら、同じエイリアスを
resolve.alias等で重複して定義する。
esbuild はバンドル時なら tsconfig の paths をそのまま解決する。 - 出力 JS そのものを書き換えたいなら、
tsc-aliasのようなツールを後段に入れる。
よくある誤解
- paths を書いても、実行時には解決されない。
paths が効くのは型チェックだけである。 - Next.js / Vite が paths を自動で読むかどうかは、ツールごとに違う。
Next.js は読み、内部で resolve.alias を生成する。
Vite は 8.0 で組み込みのresolve.tsconfigPathsオプションが入ったが、既定はfalseである。
明示的に有効化するかvite-tsconfig-pathsプラグインを入れない限り、Vite は paths を読まない。
関連
paths に baseUrl は要らない。baseUrl は TypeScript 6.0 で非推奨(TS5101)になり、7.0 で削除された(TS5102)。
残っている tsconfig からは外し、値を ./ で始まる相対パスに書き換える。