TypeScript パスマッピング paths

paths は tsconfig.json の設定オプションで、モジュールのパスエイリアスを設定するために使用します。

これにより、インポートパスをより簡潔にし、コードの組織構造を明確に保つことができます。


SVG 図:パスマッピングの動作原理 背景 タイトル パスマッピング paths の動作原理 元のインポート 元のインポートパス import Button from "../../components/Button" 矢印 パスマッピング後 エイリアスを使用したインポート import Button from "@/components/Button" 矢印 tsconfig paths 設定 下半分:設定項目 paths 設定項目 設定1 baseUrl 基準パス 設定2 paths パスエイリアス 設定3 rootDirs ルートディレクトリ 矢印マーク

なぜパスマッピングが必要か

プロジェクトの規模が大きくなるにつれて、ファイルディレクトリはどんどん深くなります。

相対パスでのファイルインポート(例:../../../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

// webpack モジュールをインポート
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

// vite モジュールをインポート
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 は同期設定が必要です

推奨:よく使うディレクトリにパスエイリアスを設定し、コードの可読性と保守性を高めましょう。

その他の関連項目