TS 7.0 で baseUrl が使えなくなった今、パスエイリアスをどうするか

ブログ記事はこちら: https://tech.findy.co.jp/entry/2026/11/01/080000

今まで広く使われてきた baseUrl オプションは TypeScript 6.0 で非推奨となり、7.0 では廃止されエラーになりました。7.0 へのアップグレードを進める場合、この対応を避けて通れません。

本セッションでは、実際に @/（paths + baseUrl）から subpath imports の #/ へ移行した経験をもとに、baseUrl からの移行事例をお話しします。

TypeScript 6.0 からは #/ で始まる Subpath imports がサポートされ、@/ と同じ使い勝手のまま Node.js のモジュール解決を活用したパスエイリアスへ乗り換えることができるようになりました。

baseUrl 廃止の背景、paths 単体で置き換える方法との比較、工数が少ない移行手順、移行作業で踏んだハマりポイントに触れます。

プロジェクトで baseUrl の廃止をスムーズに進めるためのヒントになれば幸いです。Node.js の Subpath imports に興味がある方にも参考になる内容です。

TSKaigi Sendai 2026

Transcript

1. TS 7.0 で baseUrl が使えなくなった今、 パスエイリアスをどうするか 〜subpath imports という選択肢〜 ファインディ株式会社 ⼤⽯ 貴則 2026.11.01 © Findy Inc. 1
2. 登壇者紹介 ⼤⽯ 貴則 OISHI Takanori @bicstone_me @oishi.takanori @bicstone • ⾼専機械⼯学科卒、元機械設計エンジニア • 現在は Web 業界 6 年⽬の Web エンジニア • TypeScript / Ruby / PHP / Python / Dart • Certified ScrumMaster ® Certified ScrumMaster® is a certification mark of Scrum Alliance, Inc. Any unauthorized use is strictly prohibited. © Findy Inc. 2
3. 【背景】 baseUrl とは？ ./ なしの import の起点を決める設定 • AMD ローダー⽤の設定 • 便利な設定として普及 ◦ CRA、Next.js でも採⽤ • paths に baseUrl が必須だった ◦ TS 4.0 まで • ⼀度書いた baseUrl はそのまま残る // tsconfig.json { "compilerOptions": { "baseUrl": "src" } } // app/app.ts import Button from "components/Button"; // -> src/components/Button.ts ➔ 便利ツールとして使われてきた TSConfig Reference - baseUrl <https://www.typescriptlang.org/tsconfig/#baseUrl> © Findy Inc. 3
4. 【背景】 baseUrl が廃⽌された理由 baseUrl は import の起点としても機能 • paths にない import も解決 ◦ 型は通るが実⾏時に失敗 • この挙動はほとんど知られていない ◦ 本来は AMD ローダー⽤の設定 • 6.0 で⾮推奨、7.0 で廃⽌ // tsconfig.json { "compilerOptions": { "baseUrl": "./src", "paths": { "@app/*": ["app/*"], "@lib/*": ["lib/*"] } } } // app.ts import * as someModule from "someModule.js"; // -> src/someModule.js ➔ 思わぬ挙動をなくすため廃⽌ TypeScript 6.0 Release Notes <https://www.typescriptlang.org/docs/handbook/release-notes/typescript-6-0.html> © Findy Inc. 4
5. baseUrl からの移⾏⽅法は 2 つ ① paths への置き換えか、② subpath imports への置き換え ① paths ② subpath imports 解決するツール TypeScript + 各ツール Node.js + 各ツール 定義する場所 tsconfig.json package.json Node.js の実⾏時 Node.js は解決しない Node.js が解決 エイリアス名 ⾃由 (@/ など) # 始まりのみ ➔ どのツールがエイリアスを解決するかが異なる © Findy Inc. 5
6. baseUrl からの移⾏⽅法は 2 つ ① paths への置き換えか、② subpath imports への置き換え ① paths ② subpath imports 解決するツール TypeScript + 各ツール Node.js + 各ツール 定義する場所 tsconfig.json package.json Node.js の実⾏時 Node.js は解決しない Node.js が解決 エイリアス名 ⾃由 (@/ など) # 始まりのみ ➔ どのツールがエイリアスを解決するかが異なる © Findy Inc. 6
7. ① paths への置き換え paths を相対パスにして、baseUrl を消す • エイリアスの書き⽅は変わらない ◦ @/ がそのまま使える • ソースコードの変更はほぼ不要 ◦ 影響範囲が⼩さい • sed で⼀括変換 ◦ ts5to6 --fixBaseUrl でも可 // tsconfig.json "compilerOptions": { - "baseUrl": ".", "paths": { "@/*": ["src/*"] + "@/*": ["./src/*"] } } // app.ts import { formatDate } from "@/utils/formatDate.ts"; ➔ tsconfig.json の変更のみで完結 TypeScript 6.0 Release Notes <https://www.typescriptlang.org/docs/handbook/release-notes/typescript-6-0.html> © Findy Inc. 7
8. ① トラブル: Storybook でエイリアスが解決不可に 多段 extends のモノレポで発⽣ • paths は最奥の 1 ファイルのみ記載 ◦ 中間のディレクトリが起点に • tsconfig のキャッシュ共有が原因 ◦ 当時は置き換えを断念 • 現在の最新バージョンでは解決 // extends の連鎖 libs/ui/tsconfig.lib.json └ config/tsconfig.lib.json └ config/tsconfig.json └ tsconfig.base.json // エイリアスの解決先 期待 libs/components/… 実際 config/libs/components/… ➔ ツールごとに paths の解釈がずれる課題 aleclarson/vite-tsconfig-paths <https://github.com/aleclarson/vite-tsconfig-paths> © Findy Inc. 8
9. 【再掲】 baseUrl からの移⾏⽅法は 2 つ ① paths への置き換えか、② subpath imports への置き換え ① paths ② subpath imports 解決するツール TypeScript + 各ツール Node.js + 各ツール 定義する場所 tsconfig.json package.json Node.js の実⾏時 Node.js は解決しない Node.js が解決 エイリアス名 ⾃由 (@/ など) # 始まりのみ ➔ どのツールがエイリアスを解決するかが異なる © Findy Inc. 9
10. ② subpath imports への置き換え package.json の imports に定義 • #/ は Node.js 24.14 / 25.4 から ◦ TypeScript は 6.0 から • 起点は最も近い package.json ◦ tsconfig の設定とは無関係 • #/ 以外のエイリアスは変更が必要 // package.json { "imports": { "#/*": "./src/*" } } // app.ts import { formatDate } from "#/utils/formatDate.ts"; ➔ tsconfig に依存せず Node.js が解決 Node.js Docs - Modules: TypeScript <https://nodejs.org/api/typescript.html> © Findy Inc. 10
11. ② テストランナーとの相性 #/ が使えるかは Node.js のバージョン次第 ランナー Node.js 22 / 24.13 Node.js 24.14 以上 Vitest / Jest ◦ 利⽤可能 ◦ 利⽤可能 node:test / Mocha / AVA tsx / Playwright Test ✕ 利⽤不可 ◦ 利⽤可能 Bun ✕ 利⽤不可 ✕ 利⽤不可 ➔ 実⾏する Node.js のバージョンを揃えることが重要 ※ #src/* のような名前付きのエイリアスは、全ランナーで動作 検証: 2026-10-25 時点における各ツールの最新バージョン © Findy Inc. 11
12. どちらを選ぶか どちらの⽅法にもいくつかの制約がある A. Type Stripping で直接実⾏ ② subpath imports B. @org/pkg 形式のモノレポ ① paths C. Node.js 24.14 未満 または Bun ① paths どれでもない ② subpath imports © Findy Inc. 12
13. まとめ • baseUrl は TS 7.0 で廃⽌ ◦ 思わぬ挙動で、解決できない import が解決できてしまう • ① paths は tsconfig.json の変更のみで完結 ◦ TypeScript の機能のため、ツールごとに解釈がずれる • ② subpath imports はエイリアスが # 始まりに固定 ◦ Node.js の機能のため、#/ は Node.js バージョン次第 ➔ 使えるなら、トラブルの少ない ② subpath imports を選ぶ © Findy Inc. 13
14. 最後に 話しきれなかった内容をテックブログに書きました！ テックブログ (tech.findy.co.jp) ⼤⽯貴則 (@bicstone) 登壇資料 & SNS (bicstone.me) © Findy Inc. 14