tsconfig.json Compiler Options

TypeScriptコンパイラ（tsc）がコードをJavaScriptに変換（トランスパイル）する際のルールや挙動を定義する設定項目。プロジェクトのルートディレクトリに配置する tsconfig.json ファイル内の "compilerOptions" オブジェクトに記述する。

基本設定 (Environment)

プロジェクトの出力形式や対象環境を定義する。

• module: コンパイル後のモジュールシステムを指定する。
  • "nodenext": Node.js の最新仕様（ES Modules と CommonJS の相互運用など）に準拠して出力する。package.json の "type": "module" とセットでの使用が推奨される。
  • "esnext": ブラウザなどの最新標準環境向け。import / export をそのままJavaScriptとして出力する。
    • ブラウザで読み込む際は、HTML側で <script type="module" src="..."> と記述する必要がある。
• target: 出力される JavaScript の構文バージョンを指定する。
  • "esnext": 常にその時点での最新の JavaScript 機能（最新のアロー関数やクラス構文など）で出力する。
• types: グローバルに読み込む型定義パッケージを指定する。
  • [] (空配列): node_modules/@types 内の型定義を自動的にグローバルに読み込まないようにする。必要な型は明示的に import して使用するスタイルになる。

出力設定 (Output)

コンパイル時に生成される補助ファイルに関する設定。

• sourceMap: true にすると .js.map ファイルを生成する。
  • ブラウザの開発者ツールやエディタのデバッガで、変換後の JavaScript ではなく元の TypeScript コードとしてデバッグが可能になる。
• declaration: true にすると .d.ts ファイル（型定義ファイル）を生成する。
  • 作成したコードをライブラリとして公開し、他のプロジェクトから型情報を維持したまま利用させる場合に必要。
• declarationMap: true にすると .d.ts.map ファイルを生成する。
  • エディタで「定義へ移動」を実行した際、型定義ファイル（.d.ts）ではなく、実装元の TypeScript ソースファイル（.ts）へジャンプできるようになる。

厳格な型チェック (Stricter Type Checking)

バグを未然に防ぐための、より厳しいチェックルール。

• strict: true にすると、TypeScript の厳格モード関連のオプション（noImplicitAny, strictNullChecks など）をまとめて有効にする。基本的には常に true が推奨される。
• noUncheckedIndexedAccess: true にすると、配列やオブジェクトへのインデックスアクセス（例: data[0]）の結果型に自動的に undefined を含める。
  • 「存在するかわからない要素」へのアクセスによる実行時エラーを防ぐ。
• exactOptionalPropertyTypes: true にすると、? がついたオプションプロパティに対し、明示的に undefined を代入することを禁止する。
  • 「プロパティ自体が存在しない」状態と「値として undefined を持つ」状態を明確に区別する。

モジュール・ビルド設定 (Module & Build)

バンドラーや外部ツールとの連携、モジュールの扱いに関する設定。

• jsx: JSX（React等のUI記述構文）の変換形式を指定する。
  • "react-jsx": React 17以降の変換方式。ファイルの先頭で import React from 'react' を記述しなくても JSX が使用可能になる。
• verbatimModuleSyntax: true にすると、import type や export type といった型のみの記述を、コンパイル後の JavaScript から確実に削除する。
  • Vite や Webpack などのバンドルツールとの整合性を高める。
• isolatedModules: true にすると、各ファイルを完全に独立したモジュールとして扱えない記述（例: 型情報のみの再エクスポートなど）をエラーにする。
  • ts-loader 以外のツール（esbuild, Vite, SWCなど）は1ファイルずつ変換を行うため、それらを使用する場合に必須の設定。
• noUncheckedSideEffectImports: true にすると、副作用のみのインポート（例: import "./style.css") でファイルパスが解決できない場合にエラーを出す。タイポ防止に役立つ。
• moduleDetection: "force" にすると、すべてのファイルをモジュールとして扱う。
  • ファイル内に import / export がなくても、変数がグローバルスコープに漏れ出すのを防ぐ。
• skipLibCheck: true にすると、node_modules 内にあるライブラリの型定義ファイル（.d.ts）のチェックをスキップする。
  • コンパイル時間を短縮し、ライブラリ側の型定義エラーによって自分のビルドが失敗するのを防ぐ。

// tsconfig.json の記述例
{
  "compilerOptions": {
    // 基本設定
    "module": "nodenext",
    "target": "esnext",
    "types": [],

    // 出力設定
    "sourceMap": true,
    "declaration": true,
    "declarationMap": true,

    // 厳格な型チェック
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,

    // モジュール・ビルド設定
    "jsx": "react-jsx",
    "verbatimModuleSyntax": true,
    "isolatedModules": true,
    "noUncheckedSideEffectImports": true,
    "moduleDetection": "force",
    "skipLibCheck": true
  },
  // コンパイル対象の指定
  "include": ["src/**/*"]
}