TypeScript パスマッピング paths
paths は tsconfig.json の設定オプションで、モジュールのパスエイリアスを設定するために使用します。
これにより、インポートパスをより簡潔にし、コードの組織構造を明確に保つことができます。
SVG 図:パスマッピングの動作原理
なぜパスマッピングが必要か
プロジェクトの規模が大きくなるにつれて、ファイルディレクトリはどんどん深くなります。
相対パスでのファイルインポート(例:../../../components/Button)は、コードの可読性や保守性を損ないます。
パスマッピングを使用すると、エイリアス(例:@/components/Button)を使って冗長な相対パスを置き換えることができます。
エイリアス:パスエイリアスはインポートパスを簡潔にし、プロジェクト構造の調整も容易にします。
基本設定
tsconfig.json で paths と baseUrl を設定します。
tsconfig.json
"compilerOptions": {
// 基準パス:すべてのパスエイリアスのルートディレクトリ
"baseUrl": ".",
// パスマッピング設定
"paths": {
// @/ で始まるエイリアス。src ディレクトリを指す
"@/*": ["src/*"],
// @components で始まるエイリアス
"@components/*": ["src/components/*"],
// @utils で始まるエイリアス
"@utils/*": ["src/utils/*"],
// @services で始まるエイリアス
"@services/*": ["src/services/*"],
// @assets で始まるエイリアス
"@assets/*": ["src/assets/*"],
// @types で始まるエイリアス
"@types/*": ["src/types/*"]
}
}
}
baseUrl:baseUrl を設定すると、paths 内のパスはこのディレクトリを基準に解決されます。
パスエイリアスの使用
設定が完了すると、コード内でエイリアスを使ってモジュールをインポートできます。
src/components/Button.tsx
import { Button } from '@/components/Button';
import { User } from '@types/user';
import { fetchUser } from '@services/userApi';
import { formatDate } from '@utils/date';
// スタイルをインポート
import styles from '@/components/Button.module.css';
// 画像をインポート
import logo from '@assets/logo.png';
// インポートしたモジュールを使用
const handleClick = () => {
console.log('ボタンクリック');
};
const userButton = new Button({
text: 'ユーザー',
onClick: handleClick
});
console.log('コンポーネントの読み込みに成功しました');
構文:paths 設定では * をワイルドカードとして使用し、インポート時に * で実際のパスにマッチさせます。
Webpack エイリアス設定
Webpack を使用する場合は、実行時をサポートするために resolve.alias の設定も必要です。
webpack.config.js
const path = require('path');
// Webpack 設定
module.exports = {
// その他の設定...
resolve: {
// パスエイリアス設定。tsconfig.json と一致させる必要があります
alias: {
// @ で始まるエイリアス
'@': path.resolve(__dirname, 'src'),
// その他のエイリアス
'@components': path.resolve(__dirname, 'src/components'),
'@utils': path.resolve(__dirname, 'src/utils'),
'@services': path.resolve(__dirname, 'src/services'),
'@types': path.resolve(__dirname, 'src/types'),
'@assets': path.resolve(__dirname, 'src/assets')
},
// ファイル拡張子
extensions: ['.ts', '.tsx', '.js', '.jsx', '.json']
}
};
実行時の整合性:Webpack の alias 設定は TypeScript の paths 設定と一致している必要があります。一致していないと、実行時にモジュールが見つからないエラーが発生します。
Vite 設定
Vite を使用する場合、tsconfig.json と vite.config.ts の両方で設定する必要があります。
vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import path from 'path';
// Vite 設定
export default defineConfig({
plugins: [react()],
// パスエイリアス設定
resolve: {
alias: {
'@': path.resolve(__dirname, './src'),
'@components': path.resolve(__dirname, './src/components'),
'@utils': path.resolve(__dirname, './src/utils'),
'@services': path.resolve(__dirname, './src/services'),
'@types': path.resolve(__dirname, './src/types'),
'@assets': path.resolve(__dirname, './src/assets')
}
}
});
Vite:Vite はバンドルエンジンとして Rollup を使用するため、resolve.alias でエイリアスを設定する必要があります。
マルチプロジェクトのパス設定
Monorepo プロジェクトでは、パッケージをまたぐパスエイリアスを設定できます。
tsconfig.json (Monorepo)
"compilerOptions": {
// 基準パス
"baseUrl": ".",
// パスマッピング。パッケージ間の参照をサポート
"paths": {
// 現在のパッケージのモジュールを参照
"@/*": ["src/*"],
// 他のパッケージのモジュールを参照
"@my-ui/button": ["packages/ui-button/src/index.ts"],
"@my-ui/modal": ["packages/ui-modal/src/index.ts"],
"@my-utils/date": ["packages/utils-date/src/index.ts"],
"@my-hooks/useFetch": ["packages/hooks-use-fetch/src/index.ts"]
}
}
}
Monorepo:Monorepo プロジェクトでは、paths で他のパッケージのソースパスを参照できます。
注意事項
- baseUrl 必須:paths は baseUrl と組み合わせて使用する必要があります
- ワイルドカードマッチング:* を使用して任意のパスにマッチ
- 整合性を保つ:Webpack/Vite 設定は tsconfig と一致させることが必須です
- 相対パス:paths 内のパスは baseUrl を基準とします
ベストプラクティス:パスエイリアスを使用するとコードが簡潔になりますが、乱用は避け、命名規則を統一することをお勧めします。
まとめ
パスマッピングは、TypeScript プロジェクトでインポートパスを管理するための重要なツールです。
- paths:パスエイリアスの設定
- baseUrl:基準パスの設定
- ワイルドカード:* を使用して任意の文字にマッチ
- ビルドツール:Webpack/Vite は同期設定が必要です
その他の関連項目推奨:よく使うディレクトリにパスエイリアスを設定し、コードの可読性と保守性を高めましょう。