できない.dev

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 からは外し、値を ./ で始まる相対パスに書き換える。