1. ホーム
2. web
3. TypeScript Path Aliases：スケールしたクリーンなインポート

TypeScriptパスエイリアスは../../../utils/helpersのような深い相対インポートを排除し、@utils/helpersのような明確なパスに置き換えます。本記事では設定方法、バンドラー統合、テスト、移行戦略を解説します。

baseUrlとpathsの設定

パスエイリアスの基礎はtsconfig.jsonのpathsマッピングとbaseUrlです：

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

baseUrlが非相対モジュール名解決の基準ディレクトリを設定し、pathsがエイリアスプレフィックスをファイルシステムの場所にマッピングします。ワイルドカード*はプレフィックス以降の任意のパスセグメントに一致します。

ワイルドカードパターンと高度なマッピング

複数のフォールバックパスや直接モジュールマッピングが可能です：

{
  "paths": {
    "@shared/*": ["./src/shared/*"],
    "@components/*": ["./src/components/*", "./src/shared/components/*"],
    "@config": ["./src/config/index.ts"]
  }
}

バンドラー統合

TypeScriptのpathsは型チェックとIDEサポートのみに機能します。各バンドラーに個別の設定が必要です：

Viteではvite-tsconfig-pathsプラグインで自動同期できます：

import { defineConfig } from 'vite';
import tsconfigPaths from 'vite-tsconfig-paths';

export default defineConfig({
  plugins: [tsconfigPaths()],
});

Node.js実行時にはtsconfig-pathsパッケージを使用します。

ESLintでの解決

eslint-import-resolver-typescriptパッケージがtsconfigのpaths設定を自動的に読み込みます：

settings: {
  'import/resolver': {
    typescript: { alwaysTryTypes: true }
  }
}

import/orderルールでエイリアスインポートをグループ化し、相対インポートより優先して整列できます。

テスト環境での設定

各テストランナーにもエイリアス設定が必要です：

// Jest - moduleNameMapper
{ "^@/(.*)$": "<rootDir>/src/$1" }

// Vitest - Viteの設定を自動継承
import { defineConfig } from 'vitest/config';
import tsconfigPaths from 'vite-tsconfig-paths';

export default defineConfig({
  plugins: [tsconfigPaths()],
});

移行戦略

段階的に導入します。新しいコードから@/エイリアスを使い始め、既存のインポートはcodemodツール（ts-migrateやjscodeshift）で段階的に書き換えます。移行完了後はimport/no-relative-parent-importsでリンティングを強化します。

エイリアスの過剰設定を避け、循環依存のリスクに注意してください。シンプルな@/エイリアスから始め、プロジェクトの成長に応じて拡張するのが最善の戦略です。

パスエイリアスは中〜大規模TypeScriptプロジェクトの保守性を大幅に向上させます。最大の課題はバンドラー、テストランナー、リンターの設定をtsconfigと同期させることですが、自動読み込みプラグインの活用で負担を軽減できます。