TypeScript の設定

Volardev 編集部 April 29, 2026

1. はじめに

tsconfig.json ファイルは、あらゆる TypeScript プロジェクトの「心臓部」です。
このファイルは、TypeScript コンパイラ（Compiler）に対して、コードをどのようにプロセス（Process）し、どのファイルを対象に含め、どの機能を有効または無効にするかを指示します。

適切に構成された tsconfig.json は、スムーズな開発体験（DX）と信頼性の高いビルド（Build）を支える基盤となります。

2. 主要なコンセプトと解説

tsconfig.json で頻繁に使用される主要な項目について解説します。

compilerOptions: TypeScript がコードをどのようにコンパイル（Compile）するかを制御します（例：ターゲット、モジュール、厳格さの設定など）。
include: コンパイル対象に含めるファイルまたはフォルダを指定します。
exclude: コンパイル対象から除外するファイルまたはフォルダを指定します。
files: コンパイルに含めるファイルの明示的なリストです（include と併用されることは稀です）。
extends: 他の設定ファイルからオプションを継承します。
references: モノレポ（Monorepos）やマルチパッケージ構成において、プロジェクト参照を有効にします。

3. ステップ・バイ・ステップの例

3.1 最小限の tsconfig.json

まずは、最もシンプルな構成から見ていきましょう。

例：最小限の設定

{
  "compilerOptions": {
    "target": "es6",
    "module": "commonjs"
  },
  "include": ["src/**/*"]
}

3.2 高度な tsconfig.json

実際の開発現場で使用される、より実戦的な設定例です。

例：高度な設定

{
  "compilerOptions": {
    "target": "es2020",
    "module": "esnext",
    "strict": true, // 厳格な型チェックを有効化
    "baseUrl": ".",
    "paths": {
      "@app/*": ["src/app/*"] // パスエイリアスの設定
    },
    "outDir": "dist", // コンパイル後の出力先
    "esModuleInterop": true // CommonJSとES Modules間の相互運用性を向上
  },
  "include": ["src"],
  "exclude": ["node_modules", "dist"]
}

tsconfig.json ファイルを新規生成するには、以下のコマンドを実行します。

例

tsc --init

4. 実践的なシナリオ

プロジェクトの種類に応じて、最適な設定は異なります。

モノレポ（Monorepo）: references と extends を活用して、パッケージ間で設定を共有します。
ライブラリ（Library）: 型定義ファイルを出力するために declaration を設定し、outDir を適切に指定します。
アプリケーション（App）: 最高の互換性を確保するために strict モードと esModuleInterop を有効にします。

5. よくある落とし穴とトラブルシューティング

開発中にハマりがちなポイントをまとめました。

include/exclude の設定ミス: ファイルが読み込まれなかったり、予期しないファイルが含まれたりする原因になります。
パスが解決できない: パスエイリアス（Paths）が正しく動作しない場合は、baseUrl と paths の設定を再確認してください。
strict 変更後の型エラー: strict モードを途中で有効にすると大量のエラーが出ることがありますが、これはコードの型安全性を高めるための「避けて通れない儀式」です。

6. ベストプラクティス

常に strict を有効にする: より安全なコードを書くための鉄則です。
extends を活用する: モノレポや複数プロジェクト間で設定の重複を避けましょう。
ビルド出力フォルダをコミットしない: dist などの出力フォルダは、バージョン管理（Gitなど）の対象から外すのが標準的です。