エイリアスの「その先」へ：Viteとtsconfigの完全同期がもたらす開発体験の極致
「`../../../../components/Button`」というimport文を目にするたびに、私は開発者の生産性がドブに捨てられているような感覚を覚えます。
ディレクトリ階層が深くなるにつれ、相対パスの解決は脳のメモリを無駄に消費し、リファクタリングのたびにパスの修正に追われる。これは単なる「書き心地」の問題ではなく、コードベースのメンテナンス性を著しく低下させる構造的負債です。
本稿では、ViteとTypeScriptの連携を完璧に同期させ、開発者が「コードを書くこと」にのみ集中できる環境を構築するための、テックリード視点の「パス管理術」を伝授します。
—
1. なぜ「同期」が不可欠なのか？
多くのエンジニアが犯すミスは、Vite（`vite.config.ts`）にだけエイリアスを設定し、`tsconfig.json`を放置することです。これではIDE（VS Codeなど）がパスを解決できず、定義へのジャンプや自動インポートが機能しません。
Viteはビルド時にパスを解決しますが、IDEは`tsconfig.json`を見て型定義やシンボルを辿ります。この両者に「同じ地図」を渡さなければ、DX（Developer Experience）は向上しません。
実践：ベストプラクティスな設定構成
まずは `tsconfig.json` にプロジェクトの「規約」を定義します。
{
“compilerOptions”: {
“baseUrl”: “.”,
“paths”: {
// @/ で始まるパスは src/ 配下を指すというプロジェクトの憲法
“@/”: [“./src/”],
// コンポーネントやhooksなど、頻出ディレクトリに直接アクセスするためのショートカット
“@components/”: [“./src/components/”],
“@hooks/”: [“./src/hooks/”]
}
}
}
次に、この設定を Vite に教え込みます。ここで重要なのは、`path` モジュールの利用です。
// vite.config.ts
import { defineConfig } from ‘vite’;
import path from ‘path’;
export default defineConfig({
resolve: {
alias: {
// __dirname を使うことで、OSに依存しない絶対パスとして定義する
‘@’: path.resolve(__dirname, ‘./src’),
‘@components’: path.resolve(__dirname, ‘./src/components’),
‘@hooks’: path.resolve(__dirname, ‘./src/hooks’),
},
},
});
—
2. チーム開発で「崩壊」を防ぐためのルール
個人の設定だけで終わらせてはいけません。チーム開発では「エイリアスを使いすぎる」という別の問題が発生します。
「絶対パス階層」の深追い禁止令
`@/features/auth/components/LoginForm/Button` のような深いエイリアスは、逆にディレクトリ構造を隠蔽し、コードの移動を困難にします。
- ルール: エイリアスは `src` 直下の主要レイヤー（`components`, `hooks`, `services`, `types`）までとする。
- 理由: それ以上深い階層は、バレルファイル（`index.ts`）を適切に配置して解決する。これが「疎結合」を維持する境界線です。
—
3. 開発スピードを劇的に高める「神ツール」と設定
エイリアスを設定したら、次はそれを活かしきるための「武器」を導入します。
【絶対入れるべきプラグイン】: `vite-tsconfig-paths`
毎回 `vite.config.ts` にエイリアスを追記するのは非効率です。このプラグインを導入すれば、`tsconfig.json` の `paths` を自動的に Vite が読み取ってくれます。
npm install -D vite-tsconfig-paths
// vite.config.ts
import { defineConfig } from ‘vite’;
import tsconfigPaths from ‘vite-tsconfig-paths’;
export default defineConfig({
plugins: [tsconfigPaths()], // これだけで設定が同期される
});
【VS Codeの隠れた最強設定】
インポート時に `../` が出てくるのを防ぐために、`.vscode/settings.json` に以下を記述してください。
{
// 自動インポート時に相対パスではなくエイリアスを優先的に選択する
“typescript.preferences.importModuleSpecifier”: “non-relative”,
“javascript.preferences.importModuleSpecifier”: “non-relative”
}
—
4. 現場で震えるほど役立つ「プロのTips」
最後に、私が現場で必ず導入している生産性向上テクニックを一つ。
「Barrel File (index.ts) の自動化」
エイリアスを使うと、`import { A } from ‘@/components/A’; import { B } from ‘@/components/B’;` となりがちです。各ディレクトリに `index.ts` を置き、以下のようにエクスポートを整理してください。
// src/components/index.ts
export from ‘./Button’;
export from ‘./Input’;
export from ‘./Modal’;
これにより、呼び出し側は `import { Button, Input } from ‘@components’;` と一行で済むようになります。これを手動でやるのは苦行なので、`barrelsby` などの CLI ツールを `pre-commit` フックに仕込み、自動生成させるのが「プロの現場」の作法です。
—
結びに：技術は「脳のメモリ」を節約するためにある
エンジニアの仕事は、コードを書くことではなく「思考を形にすること」です。エイリアス設定という小さな手間を惜しまないことは、数ヶ月後の自分やチームメンバーの認知負荷を劇的に軽減します。
環境構築は、一度整えて終わりではありません。常に「もっと楽に、もっと速く」書ける余地がないか、設定ファイルと対話してください。それが、優れたテックリードの条件です。
さあ、あなたのプロジェクトの `tsconfig.json` を開いて、最初のエイリアスを追加してみてください。そこから、あなたの開発体験は劇的に変化します。