tsconfig.json 主要オプション

// tsconfig.json（JSON 形式）
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "strict": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

// 典型的な Web アプリ向け tsconfig.json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "lib": ["ES2020", "DOM"],
    "strict": true,
    "noEmit": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

// Node.js（サーバーサイド）向け tsconfig.json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "outDir": "dist",
    "rootDir": "src",
    "declaration": true,
    "sourceMap": true,
    "strict": true
  },
  "include": ["src/**/*"]
}

『target』は出力する JavaScript のバージョンを、『module』はモジュール形式を指定します。ブラウザ向けのバンドラを使う場合は『moduleResolution: "bundler"』（TypeScript 5.0+）が推奨されます。Node.js 向けは『module: "NodeNext"』と合わせて『moduleResolution: "NodeNext"』を使います。

厳格な型チェックに関しては strictモードの各オプション を参照してください。

『paths』は『baseUrl』と組み合わせて、インポートパスのショートカット（エイリアス）を定義する機能です。プロジェクトのフォルダ階層が深くなると、相対パスが長くなって読みづらくなります。

// paths を使わない場合（相対パスが長くなりがち）
import { db } from "../../../config/database";
import { logger } from "../../../lib/logger";

// paths を使う場合（@ がショートカットになる）
import { db } from "@/config/database";
import { logger } from "@/lib/logger";

設定方法

『tsconfig.json』に『baseUrl』と『paths』を設定します。

tsconfig.json

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

この設定により、@/config/database は ./src/config/database に解決されます。『baseUrl』はパス解決の基点となるフォルダで、"." はプロジェクトルート（tsconfig.json があるフォルダ）を指します。

注意: コンパイル後のパス解決

『paths』は TypeScript の型チェックとエディタの補完では正しく機能しますが、コンパイル後の .js ファイルでは @/ が自動的に書き換わりません。

// TypeScript のソース（.ts）
import { db } from "@/config/database";

// tsc がコンパイルした .js（@/ がそのまま残る）
const database_1 = require("@/config/database"); // Node.js はこれを解決できない

そのため、実行時にパスを解決する仕組みを別途用意する必要があります。主な方法は以下の通りで、プロジェクトの実行環境に合わせていずれかひとつを選びます。複数を同時に導入するとパスが二重に解決されて予期しないエラーの原因になります。

tsc-alias を使う場合

コンパイル後の .js ファイルを走査して、@/ を相対パスに置換するツールです。Node.js で直接実行するプロジェクトに向いています。

npm install --save-dev tsc-alias

『package.json』のビルドスクリプトに tsc-alias を追加します。tsc の後に実行する順番が重要です。

package.json

{
  "scripts": {
    "build": "tsc && tsc-alias",
    "build:watch": "concurrently \"tsc --watch\" \"tsc-alias --watch\""
  }
}

tsc がコンパイルした .js ファイルに対して tsc-alias を実行すると、@/config/database が ./config/database のような相対パスに書き換わります。--watch オプションを付けるとファイルの変更を監視して自動で書き換え続けます。

tsconfig-paths を使う場合

Node.js の require() にフックして、実行時にパスを解決するツールです。.js ファイルを書き換えず、実行時に動的に解決します。ts-node での開発実行に向いています。

npm install --save-dev tsconfig-paths

ts-node と組み合わせて使う場合は、『tsconfig.json』に以下を追加します。

tsconfig.json

{
  "ts-node": {
    "require": ["tsconfig-paths/register"]
  }
}

この設定により、ts-node で実行する際に @/ が自動的に解決されます。

ts-node src/index.ts

コンパイル後の .js を node で実行する場合は、-r オプションで登録します。

node -r tsconfig-paths/register dist/index.js

Vite（バンドラ）を使う場合

Vite や webpack などのバンドラを使う場合は、バンドラ側にもエイリアスの設定が必要です。バンドラがソースコードをまとめる段階でパスを解決するため、tsc-alias や tsconfig-paths は不要です。

npm install --save-dev vite

『vite.config.ts』に以下のエイリアス設定を追加します。

vite.config.ts

import { defineConfig } from "vite";
import path from "path";

export default defineConfig({
  resolve: {
    alias: {
      "@": path.resolve(__dirname, "./src"),
    },
  },
});

webpack の場合は『webpack.config.js』の『resolve.alias』で設定します。

webpack.config.js

const path = require("path");

module.exports = {
  resolve: {
    alias: {
      "@": path.resolve(__dirname, "src"),
    },
  },
};

『paths』は便利な機能ですが、TypeScript コンパイラ自身がコンパイル後のパス解決を行わないため、実行環境に合わせた追加の設定が必要になる点に注意してください。