TypeScriptのpaths（エイリアス）設定：tsconfig.jsonと主要ツールの連携手順

2026年5月7日

環境構築・ツール (tsc, ts-node, Bun, Deno)

TypeScriptを用いた大規模なアプリケーション開発において、ファイルのディレクトリ階層が深くなるにつれて相対パスによるインポートの複雑化は避けて通れない課題です。

例えば、import { User } from "../../../types/user"といった記述は、ファイルの移動や構造変更の際に修正コストを増大させるだけでなく、コードの可読性を著しく低下させます。

2026年現在のモダンな開発環境では、これらの問題を解決するためにパスエイリアス（paths）の設定が標準的に利用されています。

本記事では、TypeScriptの標準機能であるtsconfig.jsonでのパス設定方法から、ViteやRspack、Bunといった主要ツールとの連携手順までを詳しく紹介します。

メンテナンス性の高いプロジェクト構成を実現するための具体的な手法を確認していきましょう。

目次 [ close ]

TypeScriptにおけるpaths設定の基本

TypeScriptでパスエイリアスを導入する際、最も中心となるのがtsconfig.jsonの設定です。

この設定を行うことで、コンパイラに対して特定のディレクトリを短いキーワードで参照するよう指示できます。

compilerOptionsの構成

パスエイリアスを有効にするには、compilerOptions内のbaseUrlとpathsの2つのプロパティを組み合わせて使用します。

JSON

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    /* エイリアス設定の起点となるディレクトリ */
    "baseUrl": ".",
    /* エイリアスのマッピング定義 */
    "paths": {
      "@/*": ["src/*"],
      "@components/*": ["src/components/*"],
      "@hooks/*": ["src/hooks/*"],
      "@utils/*": ["src/utils/*"]
    }
  }
}

上記の例では、@/というプレフィックスをsrc/ディレクトリに対応させています。

これにより、プロジェクト内のどこからでもimport { Button } from "@/components/Button"といった形式でモジュールを呼び出すことが可能になります。

baseUrlの役割と重要性

baseUrlは、pathsで指定する相対パスの基準点を定義します。

多くの場合、プロジェクトのルートディレクトリを示す"."を指定しますが、大規模なモノレポ構成などでは特定のパッケージディレクトリを起点にすることもあります。

注意点として、pathsを設定する際には必ずbaseUrlを定義するか、あるいはTypeScript 5.0以降で推奨されているように、baseUrlを省略してpathsのみを記述する場合は、paths内のパスがプロジェクトルートからの相対パスとして解決されることを理解しておく必要があります。

主要ビルドツールとの連携手順

TypeScript自体の設定だけでは、コードの実行時やビルド時にパスが正しく解決されない場合があります。

これは、tscがパスの書き換え（トランスパイル）を行わないためです。

そのため、使用しているビルドツール側でもエイリアスの設定を同期させる必要があります。

Viteでの設定方法

2026年現在、フロントエンド開発のデファクトスタンダードとなっているViteでは、プラグインを利用することでtsconfig.jsonの設定を自動的に読み込むことができます。

vite-tsconfig-pathsの導入

手動でvite.config.tsにエイリアスを記述することも可能ですが、二重管理を防ぐためにvite-tsconfig-pathsを使用するのが一般的です。

TypeScript

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import tsconfigPaths from 'vite-tsconfig-paths';

export default defineConfig({
  // プラグイン配列に設定を追加
  plugins: [
    react(),
    tsconfigPaths()
  ],
});

この設定により、Viteは自動的にtsconfig.jsonのpathsフィールドを参照し、ビルドプロセスにおいて正しいパス解決を実行します。

Rspackによる高速なパス解決

Rustベースの超高速ビルドツールであるRspackを使用している場合、標準機能でパスエイリアスをサポートしています。

TypeScript

import { defineConfig } from '@rspack/cli';

export default defineConfig({
  resolve: {
    // tsconfig.jsonの設定を反映させる
    tsConfig: './tsconfig.json',
  },
});

Rspackではresolve.tsConfigを指定するだけで、複雑なエイリアス設定をそのままビルドエンジンに受け渡すことができます。

ランタイム環境でのパス解決

ブラウザ向けのビルドだけでなく、Node.js環境やサーバーサイドのTypeScript実行環境においてもパスエイリアスの考慮が必要です。

Node.js（tsx / ts-node）での対応

Node.js上で直接TypeScriptを実行する場合、エイリアスが解決できずにMODULE_NOT_FOUNDエラーが発生することがあります。

ts-nodeを使用する場合

ts-nodeを利用しているプロジェクトでは、tsconfig-pathsというライブラリを併用します。

Shell

# 実行コマンドの例
node -r tsconfig-paths/register node_modules/ts-node/dist/bin.js src/index.ts

tsxを使用する場合

2026年において、より軽量で高速なtsx（TypeScript Execute）を使用している場合、特別な設定なしでtsconfig.jsonのエイリアスを自動的に解釈してくれるため、設定の負担が大幅に軽減されます。

Bunでのネイティブサポート

モダンなランタイムであるBunを使用している場合、Bun自体がtsconfig.jsonをネイティブに読み込む機能を備えています。

TypeScript

// Bun環境では追加設定なしで動作する
import { logger } from "@utils/logger";

logger.info("Bun natively supports paths!");

Bunを利用するプロジェクトでは、ライブラリの追加なしにpaths設定がそのままランタイムの動作に反映されるため、開発体験が非常にスムーズです。

テストツール（Vitest / Jest）との同期

開発工程において欠かせないテスト環境でも、パスエイリアスの設定を同期させる必要があります。

Vitestの設定

VitestはViteの設定を継承するため、前述のvite-tsconfig-pathsが導入されていれば、特別な設定なしでテストコード内でもエイリアスを使用できます。

TypeScript

// vitest.config.ts
import { defineConfig, mergeConfig } from 'vitest/config';
import viteConfig from './vite.config';

export default mergeConfig(viteConfig, defineConfig({
  test: {
    globals: true,
    environment: 'happy-dom',
  },
}));

Jestの設定

依然として多くのプロジェクトで利用されているJestでは、moduleNameMapperプロパティを使用してエイリアスを手動で定義するか、ts-jestのヘルパー機能を利用します。

設定項目	説明
moduleNameMapper	正規表現を用いてエイリアスと実パスをマッピングする設定
pathsToModuleNameMapper	tsconfigのpathsをJest形式に変換するユーティリティ

TypeScript

import { pathsToModuleNameMapper } from 'ts-jest';
const { compilerOptions } = require('./tsconfig.json');

module.exports = {
  preset: 'ts-jest',
  moduleNameMapper: pathsToModuleNameMapper(compilerOptions.paths, { prefix: '<rootDir>/' }),
};

パスエイリアス運用のベストプラクティス

パスエイリアスを導入する際は、単に設定を記述するだけでなく、チーム全体で統一感のある運用ルールを策定することが重要です。

プレフィックスの統一

エイリアスであることを明示するために、@や~といった特定の記号をプレフィックスとして付与するのが一般的です。

@/: srcディレクトリ直下を指す。
@components/: コンポーネント層を指す。
@assets/: 画像やスタイルシートなどの静的リソースを指す。

このように用途ごとにエイリアスを細分化することで、インポート文を見るだけでそのモジュールの役割が推測できるようになります。

ESLintによるインポート順序の強制

エイリアスを導入するとインポート文が整理されますが、さらにeslint-plugin-importなどを活用して、エイリアスを使用したインポートを上部に配置するなどのルールを設けると、コードの美しさが保たれます。

JavaScript

// eslint.config.js (Flat Config形式)
export default [
  {
    rules: {
      "import/order": ["error", {
        "groups": ["builtin", "external", "internal", ["parent", "sibling"]],
        "pathGroups": [
          {
            "pattern": "@/**",
            "group": "internal",
            "position": "before"
          }
        ],
        "alphabetize": { "order": "asc" }
      }]
    }
  }
];