TS×React import時のpathを絶対パスで書こう！

投稿目的

• よりよい方法をご教授いただきたい
• 現場での対応の備忘録

本題

きっかけ

上長「import文を書く際、絶対パスでpathを記載するようにしましょう」
現場ぼく「承知いたしました(｀･ω･´)ゞ」

src配下のファイル同士でimportをする際、srcディレクトリを基準としたパスでimport文のpathを記述したいです。
下記のようなディレクトリ構成だとすると、Page.tsx内でType.d.tsにて定義されたtype Exampleを使用したい場合、下記のような感じで記述したい、というイメージです。
とにかく、相対パス("../types/Type")でのpath記述をやめたい、とご理解ください。

import { Example } from "types/Type";

root
|
├── public
├── src
|    ├── pages
|    |     └─ Page.tsx
|    └── types
|          └─ Type.d.ts
├── index.html
├── package.json
├── tsconfig.json
├── tsconfig.app.json
├── tsconfig.node.json
└── vite.config.ts

環境について

TypeScript×React×viteのプロジェクトです。
主なパッケージ、バージョン、コマンドは以下のようになっているものとします。

package.json

{
  "scripts": {
    "dev": "npm run build && vite --host",
    "build": "tsc -b && npm run format && vite build",
    "format": "prettier --write src/**/*.{js,ts,jsx,tsx} && npm run lint",
    "lint": "eslint .",
    ...
  },
  "dependencies": {
    "react": "^18.3.1",
    ...
  },
  "devDependencies": {
    "typescript": "~5.6.2",
    "typescript-eslint": "^8.11.0",
    "vite": "^5.4.10"
    ...
  }
}

今回は、tsconfig.jsonでは具体的な設定を書かず、アプリケーションの設定はtsconfig.app.jsonに記述するものとします。

tsconfig.json

{
	"files": [],
	"references": [{ "path": "./tsconfig.app.json" }, { "path": "./tsconfig.node.json" }]
}

aliasを設定してpathを記載するようにしてみる

tsconfig.jsonにcompilerOptions.baseUrlを設定することによって、TypeScriptがimportしたいモジュールを探す際に基準となるディレクトリを設定することができます。
また「相対パスを使わずに書いているよ~」ということを分かってもらうために「@src」というprefixをimport時のpathに記載しようと思い、compilerOptions.pathsを設定しました。
今回の場合、baseUrlが/src、paths内の@src/*は/src/*、つまりsrcディレクトリを指すようなaliasとして設定されました。
よって、下記のようにimport文を記述できます。

import { Example } from "@src/types/Type";

tsconfig.app.json

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

各ファイルのimport文の記載を更新してみると、エラーがなくなり期待通りimportできるようになりました!

pushしてプルリク作るぞ~と思いnpm run build(ビルドコマンド)を実行すると、ESLintのエラーチェックは通過して、下記のようなviteのエラーが発生しました。
どうやら、ビルド時にimport文が正しく解釈されていないようです...

vite v5.4.10 building for production...
✓ 3 modules transformed.
x Build failed in 48ms
error during build:
[vite]: Rollup failed to resolve import "@src/page/Page" from "/home/USERNAME/PROJECT_NAME/src/main.tsx".
This is most likely unintended because it can break your application at runtime.
If you do want to externalize this module explicitly add it to
`build.rollupOptions.external`

TypeScriptのコンパイルに関する設定はいじってきましたが、ビルドを実行するvite側の設定はいじっていませんでした。
下記の設定を追加します。

vite.config.ts

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react-swc";

export default defineConfig({
	plugins: [react()],
    // 下記を追加
	resolve: { alias: [{ find: "@src", replacement: "/src" }] }
});

@srcというaliasは/srcに置換してくれ、とviteに設定します。
この状態でnpm run buildしてみると、ビルドが成功しました!!

aliasいらなくね?

無事プルリクを作成できましたが、コメントをいただきました。

上長「@srcのprefixいらなくない?」
ぼく「...」

すみません、勝手に設定してしまいました。
ということで、下記のようにimport文を記載できるように修正します。

import { Example } from "types/Type";

tsconfig.app.json

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

先ほどpaths内のkeyに設定していた@src/*を/*に変換しただけです。
vite.config.tsに設定していたresolve.aliasを削除して... あれ、ビルドがうまくいかないな...
ここから泥沼にはまってしまいました...

vite v5.4.10 building for production...
✓ 3 modules transformed.
x Build failed in 48ms
error during build:
[vite]: Rollup failed to resolve import "page/Page" from "/home/USERNAME/PROJECT_NAME/src/main.tsx".
This is most likely unintended because it can break your application at runtime.
If you do want to externalize this module explicitly add it to
`build.rollupOptions.external`

解決策 vite-tsconfig-paths

上長「vite-tsconfig-pathsを使うといいと思うよ」
ぼく「神ですね」

$ npm i -D vite-tsconfig-paths@latest

package.json

{
  ...
  "devDependencies": {
    "vite-tsconfig-paths": "^5.1.4",
    ...
  },
  ...
}

vite.config.ts

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react-swc";
import tsconfigPaths from "vite-tsconfig-paths";

export default defineConfig({
    // tsconfigPaths()を追加
	plugins: [react(), tsconfigPaths()]
});

vite-tsconfig-pathsはviteにimport解決能力を授けてくれるパッケージのようです。
このパッケージを用いることで、viteがいい感じにimport文を解釈してくれるようになり、無事プルリクもマージされましたとさ。

import { Example } from "types/Type";

最後に

いろいろ大変でしたが、vite-tsconfig-pathsのお陰で一件落着しました、便利なパッケージに感謝です。
vite.config.tsやtsconfig.jsonなど、環境周りは敬遠してきてしまっていたことを後悔です...

他にも良い方法があったり、vite.config.ts tsconfig.jsonなどのおすすめ設定があったりしたら、コメントいただけますと幸いです!