tsconfig paths

定義

tsconfig paths は、TypeScript の tsconfig.json 内 compilerOptions.paths で定義する、モジュール解決のエイリアス。baseUrl と組み合わせて使う。

{
  "compilerOptions": {
    "baseUrl": "./src",
    "paths": {
      "@/*": ["*"],
      "~/utils/*": ["utils/*"]
    }
  }
}

これにより import { foo } from "@/lib/foo" のようにルートからの相対パスを書ける。

詳細

注意点：tsc は paths を「型解決」だけに使う。
コンパイル後の JS に書かれる import 文は 置換されない。
そのため

• Node で直接 node dist/main.js を実行すると Cannot find module "@/lib/foo"
• ts-node を使うときは tsconfig-paths を -r オプションで読み込む
• バンドラ（webpack / Vite / esbuild）を使うなら 同じエイリアスを resolve.alias 等で重複定義する
• 出力 JS そのものを書き換えたいなら tsc-alias のようなツールを後段に入れる

ことが必要。

よくある誤解

• paths を書けば実行時も解決される：解決されない。
  型チェック限定。
• Next.js / Vite は paths を自動で読む：Next.js は読む（内部で resolve.alias を生成）。
  Vite は vite-tsconfig-paths プラグインを入れない限り読まない、など個別。

関連

paths を使う場合は 必ず baseUrl を併記する（paths の解決は baseUrl 起点になる）。