【TypeScript】tsconfig.json 完全ガイド｜全オプション解説と目的別おすすめ設定

この記事で学べること

• tsconfig.json の役割と基本構造（compilerOptions, include, exclude, extends, files, references）
• 型チェック系オプション（strict, strictNullChecks, noImplicitAny, noUncheckedIndexedAccess 等）
• モジュール系オプション（module, moduleResolution, paths, baseUrl, esModuleInterop 等）
• 出力系オプション（target, lib, outDir, declaration, sourceMap 等）
• JavaScript連携オプション（allowJs, checkJs）とその他のオプション（jsx, isolatedModules, verbatimModuleSyntax 等）
• extends で設定を継承する方法（モノレポ対応）
• Project References（複合プロジェクト構成）
• 目的別おすすめ設定テンプレート（Webフロント / Node.js / React(Vite) / Next.js / ライブラリ開発 / monorepo）
• strictモードの段階的導入（既存JSプロジェクトの移行戦略）
• よくある設定ミスとトラブルシューティング
• 設定オプション早見表

前提知識：この記事はTypeScriptの基本的な型の書き方を理解している方を対象としています。型の基本から学びたい方は【TypeScript】型の書き方 完全入門を先にお読みください。

# TypeScript をグローバルインストール（未インストールの場合）
npm install -g typescript

# プロジェクトディレクトリで tsconfig.json を生成
cd my-project
tsc --init

# npx を使う場合（グローバルインストール不要）
npx tsc --init

注意：tsconfig.json はJSON形式ですが、TypeScript公式はコメント（// や /* */）を許容しています。これはJSON5ではなく、TypeScript独自のJSON拡張パーサー（JSONC: JSON with Comments）によるものです。

{
  // 他の tsconfig を継承（オプション）
  "extends": "./tsconfig.base.json",

  // コンパイラオプション（メイン設定）
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "strict": true,
    // ...その他のオプション
  },

  // コンパイル対象のファイル/ディレクトリ（glob パターン）
  "include": ["src/**/*"],

  // コンパイル対象から除外するファイル/ディレクトリ
  "exclude": ["node_modules", "dist"],

  // コンパイル対象ファイルを個別に指定（include の代わり）
  "files": ["src/index.ts"],

  // Project References（複合プロジェクト構成）
  "references": [
    { "path": "./packages/core" },
    { "path": "./packages/ui" }
  ]
}

ポイント：この記事ではまず compilerOptions の各オプションをカテゴリ別に詳しく解説し、その後で include / exclude / extends / references を取り上げます。

{
  "compilerOptions": {
    "strict": true
    // これだけで以下のオプションがすべて true になる：
    // - strictNullChecks
    // - strictFunctionTypes
    // - strictBindCallApply
    // - strictPropertyInitialization
    // - noImplicitAny
    // - noImplicitThis
    // - alwaysStrict
    // - useUnknownInCatchVariables
  }
}

ポイント：strict: true を設定した上で、個別のオプションを false にすることも可能です。例えば "strict": true, "strictPropertyInitialization": false とすれば、strictPropertyInitialization 以外の厳格チェックがすべて有効になります。

// strictNullChecks: true の場合
let name: string = "Alice";
name = null;      // エラー: Type 'null' is not assignable to type 'string'
name = undefined; // エラー: Type 'undefined' is not assignable to type 'string'

// null を許容したい場合は Union 型で明示する
let nickname: string | null = "Bob";
nickname = null;    // OK

// 使用時にはナローイングが必要
if (nickname !== null) {
  console.log(nickname.toUpperCase()); // OK: string に絞り込まれている
}

注意：strictNullChecks: false にすると、実行時に TypeError: Cannot read properties of null が発生するリスクが大幅に高まります。特別な理由がない限り、必ず true にしましょう。

// noImplicitAny: true の場合
function greet(name) {
  // エラー: Parameter 'name' implicitly has an 'any' type (TS7006)
  return `Hello, ${name}`;
}

// 修正: 型注釈を追加する
function greetFixed(name: string) {
  return `Hello, ${name}`;
}

// 推論可能な場合はエラーにならない
const numbers = [1, 2, 3];
numbers.map(n => n * 2); // OK: n は number と推論される

type Animal = { name: string };
type Dog = { name: string; breed: string };

type AnimalHandler = (animal: Animal) => void;

// strictFunctionTypes: true の場合
const dogHandler: AnimalHandler = (dog: Dog) => {
  console.log(dog.breed);
  // エラー! Animal に breed プロパティはないため危険
};

// AnimalHandler として呼ばれると Animal が渡される可能性がある
// その場合 dog.breed は undefined になってしまう

function add(a: number, b: number): number {
  return a + b;
}

// strictBindCallApply: true の場合
add.call(undefined, 1, 2);       // OK
add.call(undefined, "1", 2);     // エラー: string は number に代入できない
add.apply(undefined, [1, 2]);     // OK
add.apply(undefined, [1]);        // エラー: 引数の数が足りない

const boundAdd = add.bind(undefined, 1);
boundAdd(2);   // OK: (b: number) => number に推論される
boundAdd("2"); // エラー: string は number に代入できない

class User {
  name: string;  // エラー: コンストラクタで初期化されていない
  age: number;

  constructor(age: number) {
    this.age = age;
    // name が初期化されていない！
  }
}

// 解決策1: コンストラクタで初期化する
class UserFixed1 {
  name: string;
  constructor(name: string) {
    this.name = name;
  }
}

// 解決策2: デフォルト値を設定する
class UserFixed2 {
  name: string = "";
}

// 解決策3: undefined を許容する
class UserFixed3 {
  name: string | undefined;
}

// 解決策4: 明示的代入アサーション（非推奨 - 最終手段）
class UserFixed4 {
  name!: string;  // ! で「後で必ず初期化する」と宣言
}

// noImplicitThis: true の場合
function standalone() {
  return this; // エラー: 'this' implicitly has type 'any'
}

// 修正: this パラメータを明示する
function standaloneFixed(this: Window) {
  return this; // OK: this は Window 型
}

// noImplicitReturns: true の場合
function getLabel(code: number): string {
  if (code === 1) {
    return "OK";
  }
  // エラー: Not all code paths return a value
  // code !== 1 の場合に return がない
}

// 修正: すべてのパスで値を返す
function getLabelFixed(code: number): string {
  if (code === 1) {
    return "OK";
  }
  return "Unknown";
}

function getArea(shape: "circle" | "square") {
  switch (shape) {
    case "circle":
      console.log("円");
      // エラー: Fallthrough case in switch（break がない）
    case "square":
      console.log("四角");
      break;
  }
}

const colors: string[] = ["red", "blue", "green"];

// noUncheckedIndexedAccess: false（デフォルト）
const first = colors[0]; // string 型 - 存在しない添字でも string
const tenth = colors[9]; // string 型 - 実際は undefined なのに！

// noUncheckedIndexedAccess: true
const first2 = colors[0]; // string | undefined
const tenth2 = colors[9]; // string | undefined

// 使用前にチェックが必要になる
if (first2 !== undefined) {
  console.log(first2.toUpperCase()); // OK
}

// Record のインデックスアクセスにも適用される
const config: Record<string, number> = { width: 100 };
const val = config["height"]; // number | undefined

ポイント：noUncheckedIndexedAccess は strict に含まれていませんが、新規プロジェクトでは true にすることを強くおすすめします。配列の範囲外アクセスに起因するバグを防げます。

interface Theme {
  color?: string; // オプショナル: string | undefined
}

// exactOptionalPropertyTypes: true の場合
const theme1: Theme = {};              // OK: プロパティなし
const theme2: Theme = { color: "red" }; // OK: string
const theme3: Theme = { color: undefined }; // エラー!

// undefined も許可したい場合は明示的に書く
interface ThemeV2 {
  color?: string | undefined;
}

ポイント：Vite / webpack / Rollup 等のバンドラーを使用する場合は "esnext"、Node.js で直接実行する場合は "node16" または "nodenext" を選びましょう。

// バンドラー使用（Vite / webpack / Rollup 等）
{
  "module": "ESNext",
  "moduleResolution": "bundler"
}

// Node.js（ESM）
{
  "module": "NodeNext",
  "moduleResolution": "nodenext"
}

// Node.js（CommonJS）
{
  "module": "commonjs",
  "moduleResolution": "node"
}

// esModuleInterop: false の場合（CommonJS モジュールの読み込み）
import * as express from "express";  // 名前空間インポートが必要
import * as path from "path";

// esModuleInterop: true の場合（推奨）
import express from "express";  // デフォルトインポートが使える！
import path from "path";

// React も同様
import React from "react";  // esModuleInterop: true で可能

注意：esModuleInterop: true にすると allowSyntheticDefaultImports も自動で true になります。ほとんどのプロジェクトで true が推奨されます。

// resolveJsonModule: true
import packageJson from "./package.json";

console.log(packageJson.name);    // 型推論: string
console.log(packageJson.version); // 型推論: string

// 設定ファイルの読み込みにも便利
import config from "./config.json";
// config の各プロパティに型が付く

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

// Before: 相対パス地獄
import { Button } from "../../../components/Button";
import { formatDate } from "../../../utils/date";
import type { User } from "../../../types/user";

// After: パスエイリアスでスッキリ
import { Button } from "@components/Button";
import { formatDate } from "@utils/date";
import type { User } from "@types/user";

注意：paths は TypeScript のコンパイラにパスの解決方法を教えるだけで、実行時の変換は行いません。Vite なら vite.config.ts の resolve.alias、webpack なら resolve.alias、Node.js なら tsconfig-paths パッケージなど、ランタイム側でも同じエイリアス設定が必要です。

// ディレクトリ構造
// project/
//   src/
//     index.ts
//     utils/helper.ts

// rootDir: "src" + outDir: "dist" の場合
// dist/
//   index.js        ← src/ が取り除かれる
//   utils/helper.js

// rootDir 未指定 + outDir: "dist" の場合
// dist/
//   src/             ← src/ がそのまま残る
//     index.js
//     utils/helper.js

{
  "compilerOptions": {
    "rootDirs": [
      "src",
      "generated"  // 自動生成ファイル
    ]
  }
}

// src/app.ts から generated/api-types.ts を相対パスで参照できる
// import { ApiResponse } from "./api-types";

// TypeScript ソースコード
const greet = (name: string) => `Hello, ${name}!`;

// target: "ES2015" 以上 → そのまま
const greet = (name) => `Hello, ${name}!`;

// target: "ES5" → アロー関数とテンプレートリテラルが変換される
var greet = function(name) {
  return "Hello, " + name + "!";
};

ポイント：2025年以降の新規プロジェクトでは "ES2022" を基本として選ぶのがおすすめです。IE対応が不要なモダン環境であれば、不要なダウンレベル変換を避けてパフォーマンスとバンドルサイズを最適化できます。

{
  "compilerOptions": {
    "target": "ES2022",
    "lib": [
      "ES2022",     // ES2022 の組み込み型（Array.at 等）
      "DOM",        // ブラウザ DOM API（document, window 等）
      "DOM.Iterable" // NodeList の for...of 対応
    ]
  }
}

// Node.js の場合は DOM を含めない
{
  "compilerOptions": {
    "target": "ES2022",
    "lib": ["ES2022"] // DOM を含めない → document 等にアクセスするとエラー
  }
}

{
  "compilerOptions": {
    "outDir": "dist",   // コンパイル結果を dist/ に出力
    "rootDir": "src"    // ソースのルートを src/ に設定
  }
}

// src/index.ts       → dist/index.js
// src/utils/date.ts  → dist/utils/date.js

{
  "compilerOptions": {
    "declaration": true,        // .d.ts を生成
    "declarationDir": "types",  // types/ ディレクトリに出力
    "declarationMap": true,     // .d.ts.map も生成（Go to Definition 対応）
    "outDir": "dist"
  }
}

// 出力結果:
// dist/index.js          （実行用 JS）
// types/index.d.ts       （型定義）
// types/index.d.ts.map   （ソースマップ）

{
  "compilerOptions": {
    "sourceMap": true,         // .js.map ファイルを生成
    // "inlineSourceMap": true,  // 代替: JS ファイル内にマップを埋め込む
    // ↑ sourceMap と inlineSourceMap は同時に使えない
  }
}

// sourceMap: true の出力:
// dist/index.js
// dist/index.js.map  ← ソースマップ

// Vite + React プロジェクトでの典型パターン
{
  "compilerOptions": {
    "noEmit": true // tsc は型チェックだけ。JS変換は Vite(esbuild) に任せる
  }
}

// package.json の scripts
// "type-check": "tsc --noEmit"
// "build": "vite build"  ← JS の変換とバンドルは Vite が担当

// ライブラリ開発: JS は tsup/Rollup で、型定義は tsc で生成
{
  "compilerOptions": {
    "declaration": true,
    "emitDeclarationOnly": true,
    "outDir": "dist"
  }
}

{
  "compilerOptions": {
    "allowJs": true,   // .js ファイルをコンパイル対象に含める
    "checkJs": false  // .js ファイルの型チェックは行わない（段階移行の初期段階）
  }
}

// .ts ファイルから .js ファイルを import できる
// src/app.ts
import { legacy } from "./legacy-module"; // legacy-module.js

// utils.js - JSDoc で型情報を付与

/**
 * @param {string} name
 * @param {number} age
 * @returns {string}
 */
function introduce(name, age) {
  return `${name} (${age}歳)`;
}

introduce(123, "not a number"); // checkJs: true → 型エラー！

// 特定ファイルでチェックを無効化したい場合
// @ts-nocheck をファイル先頭に追加

{
  "compilerOptions": {
    "skipLibCheck": true  // 推奨: .d.ts の型チェックをスキップ
  }
}

ポイント：ほとんどのプロジェクトで skipLibCheck: true が推奨されます。node_modules 内の型定義の不整合でビルドが壊れることを防ぎ、コンパイル速度も改善されます。

// ファイル名: UserService.ts

// forceConsistentCasingInFileNames: true の場合
import { UserService } from "./userservice"; // エラー! 大文字小文字が一致しない
import { UserService } from "./UserService"; // OK

// isolatedModules: true の場合

// 1. 型のみの re-export は禁止
export { SomeType } from "./types"; // エラー（型か値か判別できない）
export type { SomeType } from "./types"; // OK: type キーワードで明示

// 2. const enum は禁止（ファイル横断の解析が必要なため）
const enum Direction { Up, Down } // エラー
enum Direction { Up, Down }       // OK: 通常の enum は許可

// 3. import/export のないファイルはモジュールとして扱えない
// 最低でも export {} を追加する

// verbatimModuleSyntax: true の場合

// import type で明示しないと型のみのインポートはエラー
import { User } from "./types";      // エラー（User が型のみの場合）
import type { User } from "./types"; // OK: import type で明示

// 値と型を混在させる場合
import { createUser, type User } from "./user"; // OK: インライン type

ポイント：TypeScript 5.0 以降の新規プロジェクトでは、isolatedModules の代わりに verbatimModuleSyntax: true を使うことを検討しましょう。型と値の区別がより明確になり、バンドラーとの互換性も向上します。

// React 17+ 推奨設定
{
  "compilerOptions": {
    "jsx": "react-jsx" // import React from "react" が不要に
  }
}

// Vite + React の場合は preserve が一般的
{
  "compilerOptions": {
    "jsx": "preserve" // Vite (esbuild) が JSX を処理する
  }
}

{
  "include": [
    "src",          // src ディレクトリ以下の全 .ts/.tsx/.d.ts
    "src/**/*",     // 上と同じ（明示的にサブディレクトリを含む）
    "*.config.ts"  // ルートの設定ファイル
  ]
}

// サポートされる glob パターン
// *     : 0文字以上の任意の文字列（ディレクトリ区切りを除く）
// ?     : 任意の1文字
// **/   : 任意の深さのサブディレクトリ

注意：include を省略すると、tsconfig.json があるディレクトリ以下のすべての .ts / .tsx / .d.ts ファイルが対象になります（exclude で除外されたものを除く）。意図しないファイルが含まれるのを防ぐため、include は明示的に設定することをおすすめします。

{
  "include": ["src"],
  "exclude": [
    "node_modules",      // デフォルトで除外（明示も可）
    "dist",              // 出力ディレクトリ
    "**/*.test.ts",      // テストファイル
    "**/*.spec.ts",      // テストファイル
    "coverage",          // カバレッジ出力
    "**/__tests__/**"    // テストディレクトリ
  ]
}

ポイント：exclude を省略した場合、node_modules、bower_components、jspm_packages、および outDir で指定したディレクトリがデフォルトで除外されます。exclude を明示的に設定した場合はこのデフォルトが上書きされるので、node_modules も含めるのを忘れないでください。

注意：exclude で除外したファイルでも、コンパイル対象のファイルから import されていれば自動的にコンパイル対象に含まれます。exclude はあくまで「直接の対象から除外する」だけで、依存関係経由の読み込みは防げません。

{
  "compilerOptions": {
    "strict": true,
    "target": "ES2022",
    "moduleResolution": "bundler",
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  }
}

{
  "extends": "./tsconfig.base.json",
  "compilerOptions": {
    "module": "ESNext",
    "jsx": "react-jsx",
    "outDir": "dist"
  },
  "include": ["src"]
}

// インストール
npm install -D @tsconfig/node18

// tsconfig.json
{
  "extends": "@tsconfig/node18/tsconfig.json",
  "compilerOptions": {
    "outDir": "dist"
  },
  "include": ["src"]
}

// 利用可能なパッケージ例:
// @tsconfig/node18, @tsconfig/node20, @tsconfig/strictest, @tsconfig/recommended

Project References の利点

• インクリメンタルビルド: 変更のあったサブプロジェクトだけ再ビルド（大幅な高速化）
• 論理的な分離: サブプロジェクト間の依存関係を明示的に宣言
• 高速なエディタ対応: エディタが各サブプロジェクトを独立して処理
• 安全な公開境界: .d.ts 経由の参照で内部実装の漏洩を防止

// ルート tsconfig.json
{
  "files": [],
  "references": [
    { "path": "./packages/core" },
    { "path": "./packages/ui" }
  ]
}

// packages/core/tsconfig.json（参照されるプロジェクト）
{
  "compilerOptions": {
    "composite": true,   // 必須: Project References で参照される場合
    "declaration": true, // composite で自動 true
    "outDir": "dist"
  },
  "include": ["src"]
}

// packages/ui/tsconfig.json（core に依存）
{
  "compilerOptions": { "composite": true, "outDir": "dist" },
  "include": ["src"],
  "references": [{ "path": "../core" }]
}

# 全プロジェクトをビルド（依存関係順に自動ビルド）
tsc --build

# 特定のプロジェクトだけビルド
tsc --build packages/core

# クリーンビルド / ウォッチモード
tsc --build --clean
tsc --build --watch

ポイント：Project References を使う場合、参照されるプロジェクトには "composite": true が必須です。このオプションは declaration: true と incremental: true を自動で有効にし、他プロジェクトから .d.ts 経由で参照できるようにします。

{
  "compilerOptions": {
    /* 型チェック */
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,

    /* モジュール */
    "module": "ESNext",
    "moduleResolution": "bundler",
    "esModuleInterop": true,
    "resolveJsonModule": true,
    "isolatedModules": true,

    /* 出力 */
    "target": "ES2022",
    "lib": ["ES2022", "DOM", "DOM.Iterable"],
    "noEmit": true,

    /* その他 */
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src"]
}

{
  "compilerOptions": {
    /* 型チェック */
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitReturns": true,

    /* モジュール */
    "module": "NodeNext",
    "moduleResolution": "nodenext",
    "esModuleInterop": true,
    "resolveJsonModule": true,

    /* 出力 */
    "target": "ES2022",
    "lib": ["ES2022"],
    "outDir": "dist",
    "rootDir": "src",
    "sourceMap": true,

    /* その他 */
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src"],
  "exclude": ["node_modules", "dist"]
}

{
  "compilerOptions": {
    /* 型チェック */
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitReturns": true,

    /* モジュール */
    "module": "ESNext",
    "moduleResolution": "bundler",
    "esModuleInterop": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "allowImportingTsExtensions": true,

    /* 出力 */
    "target": "ES2022",
    "lib": ["ES2022", "DOM", "DOM.Iterable"],
    "noEmit": true,

    /* JSX */
    "jsx": "react-jsx",

    /* パスエイリアス（vite.config.ts でも設定が必要） */
    "baseUrl": ".",
    "paths": { "@/*": ["src/*"] },

    /* その他 */
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src"]
}

{
  "compilerOptions": {
    /* 型チェック */
    "strict": true,
    "noUncheckedIndexedAccess": true,

    /* モジュール */
    "module": "ESNext",
    "moduleResolution": "bundler",
    "esModuleInterop": true,
    "resolveJsonModule": true,
    "isolatedModules": true,

    /* 出力 */
    "target": "ES2022",
    "lib": ["ES2022", "DOM", "DOM.Iterable"],
    "noEmit": true,

    /* JSX - Next.js が自動設定する場合もある */
    "jsx": "preserve",

    /* Next.js 固有 */
    "incremental": true,
    "allowJs": true,
    "baseUrl": ".",
    "paths": { "@/*": ["./src/*"] },

    /* Next.js プラグイン */
    "plugins": [{ "name": "next" }],

    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
  "exclude": ["node_modules"]
}

{
  "compilerOptions": {
    /* 型チェック（最大限に厳格） */
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "exactOptionalPropertyTypes": true,

    /* モジュール */
    "module": "ESNext",
    "moduleResolution": "bundler",
    "esModuleInterop": true,
    "verbatimModuleSyntax": true,

    /* 出力 */
    "target": "ES2022",
    "lib": ["ES2022"],
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "outDir": "dist",
    "rootDir": "src",

    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src"],
  "exclude": ["node_modules", "dist", "**/*.test.ts"]
}

{
  "compilerOptions": {
    "strict": true,
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "esModuleInterop": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitReturns": true,
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true
  }
}

{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "lib": ["ES2022", "DOM", "DOM.Iterable"],
    "jsx": "react-jsx",
    "noEmit": true
  },
  "include": ["src"]
}

{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "lib": ["ES2022"],
    "outDir": "dist",
    "rootDir": "src"
  },
  "include": ["src"],
  "exclude": ["node_modules", "dist"]
}

{
  "compilerOptions": {
    "allowJs": true,   // .js ファイルをコンパイル対象に
    "checkJs": false,  // まだ型チェックはしない
    "strict": false,   // strict はまだ無効
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "esModuleInterop": true,
    "skipLibCheck": true
  }
}

{
  "compilerOptions": {
    // Phase 1: 影響が小さいものから
    "alwaysStrict": true,               // "use strict" を付与（ほぼ影響なし）
    "strictBindCallApply": true,         // bind/call/apply のチェック
    "forceConsistentCasingInFileNames": true,

    // Phase 2: 関数周りの厳格化
    "noImplicitThis": true,             // this の暗黙 any を禁止
    "strictFunctionTypes": true,        // 関数引数の反変チェック

    // Phase 3: 最も影響が大きいもの
    "noImplicitAny": true,              // 暗黙の any を禁止（大量のエラーが出やすい）
    "strictNullChecks": true,           // null/undefined の区別（最も影響大）

    // Phase 4: クラス関連
    "strictPropertyInitialization": true,
    "useUnknownInCatchVariables": true
  }
}

{
  "compilerOptions": {
    "strict": true,  // すべてのサブオプションを一括で有効化
    "noUncheckedIndexedAccess": true,  // strict に含まれないので個別指定
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true
  }
}

段階的導入のコツ

• 各フェーズごとにPR を分けてマージすると、レビューとロールバックがしやすい
• // @ts-expect-error や // @ts-ignore を一時的に使い、後で解消する計画を立てる
• noImplicitAny と strictNullChecks が最も修正量が多い。この2つは十分な時間を確保する
• CI に tsc --noEmit を組み込み、型エラーが増えないようにゲートを設ける

// tsconfig.json の paths
"paths": { "@/*": ["src/*"] }

// Vite: vite.config.ts
resolve: { alias: { '@': path.resolve(__dirname, 'src') } }

// webpack: webpack.config.js
resolve: { alias: { '@': path.resolve(__dirname, 'src') } }

// Node.js: tsconfig-paths パッケージをインストール
npm install -D tsconfig-paths
node -r tsconfig-paths/register dist/index.js

解決策：そのファイルへの import 文を削除するか、テスト用の tsconfig.test.json を別途作成してテストファイル専用の設定を分離しましょう。

// 解決策1: @types パッケージをインストール
npm install -D @types/lodash
npm install -D @types/express

// 解決策2: @types がない場合は declare module で宣言
// src/types/custom.d.ts
declare module "some-untyped-lib" {
  const content: any;
  export default content;
}

// 解決策3: CSS / SVG 等のアセットファイル
// src/types/assets.d.ts
declare module "*.css" {
  const classes: { [key: string]: string };
  export default classes;
}
declare module "*.svg" {
  const src: string;
  export default src;
}

// rootDir 未設定の場合
// dist/src/index.js  ← src/ が残ってしまう

// rootDir: "src" を設定した場合
// dist/index.js      ← 期待通りの構造

// VS Code のコマンドパレット（Ctrl+Shift+P / Cmd+Shift+P）で:
TypeScript: Restart TS Server

// または、VS Code を再起動（Ctrl+Shift+P）:
Developer: Reload Window

tsconfig.json 設定のベストプラクティス

• 新規プロジェクトでは必ず "strict": true を設定する
• noUncheckedIndexedAccess、noImplicitReturns、noFallthroughCasesInSwitch も合わせて有効化する
• module と moduleResolution は環境に合った正しい組み合わせを選ぶ
• バンドラー使用時は noEmit: true で tsc は型チェック専用にする
• skipLibCheck: true でコンパイル速度を最適化する
• パスエイリアス（paths）を使う場合はランタイム側にも同じ設定をする
• モノレポでは extends で共通設定を継承し、各パッケージで差分だけ上書きする
• 既存プロジェクトの strict 化は段階的に行い、フェーズごとにPRを分ける

TypeScript シリーズ記事

• 【TypeScript】型の書き方 完全入門｜基本型・Union・Generics・型ガードまで ― TypeScriptの型システム全体を基本から学べる入門記事
• 【TypeScript】関数の型定義 完全ガイド｜引数・戻り値・オーバーロード・ジェネリクス関数まで ― 関数に特化した型定義を体系的に解説
• 【TypeScript】クラスの型定義 完全ガイド｜アクセス修飾子・抽象クラス・インターフェース実装まで ― クラスに特化した型定義を体系的に解説
• 【TypeScript】ジェネリクス（Generics）完全ガイド｜基礎から実務パターンまで ― ジェネリクスを基礎から実務レベルまで徹底解説
• 【TypeScript】よくあるエラーと解決方法 完全ガイド ― エラーコードごとに原因と対策を網羅