混沌とした相対パスから脱却せよ：`paths`と`baseUrl`で実現する「筋のいい」ディレクトリ構造
大規模なフロントエンド開発において、最も精神を削る小さなストレスの一つ。それが `import { … } from ‘../../../components/ui/Button’;` といった、地獄のような深い相対パスの記述だ。
「これ、ディレクトリを一つ移動しただけで全部書き換えなきゃいけないの？」
そう思った瞬間が、君がアーキテクチャを見直すべきタイミングだ。今日は、TypeScriptの `tsconfig.json` を駆使して、この悪夢を解決し、メンテナンス性の高いコードベースへと昇華させるための「パス解決の最適解」を伝授する。
—
1. なぜ「パスエイリアス」が必須なのか
まず、前提を共有しておこう。TypeScriptにおける `paths` と `baseUrl` は、コンパイラに対して「このエイリアスを見たら、実際にはこの物理パスを見に行け」と指示するためのものだ。
これを設定することで、コードはこう変わる。
- Before: `import { UserCard } from ‘../../../../features/users/components/UserCard’;`
- After: `import { UserCard } from ‘@/features/users/components/UserCard’;`
一目瞭然だろう。物理構造に依存しないインポートパスを定義することで、コンポーネントの移動やリファクタリングが劇的に楽になる。さらに、コードの可読性が上がり、何より「どこからインポートしているか」が明確になるため、コードベースの心理的安全性も向上する。
2. tsconfig.json の設定：現場でコピペして使えるテンプレ
まずは設定ファイルだ。プロジェクトのルートディレクトリにある `tsconfig.json` に以下の設定を追加してほしい。
{
“compilerOptions”: {
“baseUrl”: “.”, // プロジェクトのルートを起点にする
“paths”: {
“@/”: [“src/”], // srcディレクトリ以下を @/ でエイリアス設定
“@components/”: [“src/components/”], // よく使うディレクトリを個別に定義
“@hooks/”: [“src/hooks/”]
}
}
}
ここで重要なポイントを一つ。
`baseUrl` は `paths` を機能させるための土台だ。これがないと、TypeScriptはパスをどう解釈していいか分からなくなる。必ず `.`（プロジェクトルート）を指定するのが、現代のフロントエンド開発におけるベストプラクティスだ。
3. 注意！「TypeScriptだけ」では動かない罠
ここが初心者が一番ハマる落とし穴だ。`tsconfig.json` の設定は、あくまで「TypeScriptコンパイラ」のためのものだ。
ViteやWebpack、あるいはJestといった「ビルドツール」や「テストランナー」は、`tsconfig.json` を自動では読んでくれない。そのまま実行しようとすると、ビルド時に「モジュールが見つかりません」というエラーで爆死する。
Vite (Vitest) を使っている場合の解決策
Viteを使っているなら、`vite.config.ts` にも同様の設定を書き込む必要がある。
import { defineConfig } from ‘vite’;
import path from ‘path’;
export default defineConfig({
resolve: {
alias: {
// __dirname を使って絶対パスに解決するのが安全
‘@’: path.resolve(__dirname, ‘./src’),
‘@components’: path.resolve(__dirname, ‘./src/components’),
},
},
});
これでようやく、型チェックと実際のビルド・実行環境の両方でパス解決が機能するようになる。
4. プロの視点：アーキテクチャとしての「制約」
最後に、一つアドバイスがある。パスエイリアスを導入すると、何でもかんでもエイリアスにしたがるエンジニアがいるが、それは賢明ではない。
例えば、`@utils` のような広範なエイリアスを切りすぎると、どの機能がどの依存関係にあるのかが曖昧になり、循環参照の温床になる。
- 鉄則: `features` や `components` など、ディレクトリの階層が深いものに限定する。
- 視認性: `import { … } from ‘@/features/auth/api’` と書くことで、「これは認証機能のAPIだな」と、ファイルの中身を見ずとも依存関係の質感が伝わるような命名を心がけること。
最後に：綺麗なコードは、綺麗な地図から生まれる
パスエイリアスを整えることは、単なる「記述量の削減」ではない。プロジェクトという広大な地図において、迷子にならないための「道標」を立てる作業だ。
コードが複雑になればなるほど、こうした細部の丁寧さが開発効率の差として跳ね返ってくる。まずは君の `tsconfig.json` を開き、この設定を一行追加することから始めてみてほしい。
その小さな一行が、数ヶ月後の君を救うことになるはずだ。頑張れよ。
コメント