なぜ「tsconfig.jsonのパス指定」でプロジェクトの寿命が決まるのか
現場でよく見る悲劇がある。中規模以上のプロジェクトで、コンパイル時間が異常に長かったり、`node_modules`内の型定義までコンパイラが律儀に追いかけてパンクしたりするケースだ。これらは大抵、`tsconfig.json`の `files`, `include`, `exclude` の設定がガバガバなことが原因だ。
TypeScriptのコンパイラ（`tsc`）は、指定されたファイルを起点に依存関係をグラフ化する。この「探査範囲」を適切に制限することは、単にビルドを速くするだけでなく、チーム開発における「予期せぬ型エラーの混入」を防ぐための最初の防衛ラインになる。
今日は、中級エンジニアが避けて通れないこの設定について、深層まで掘り下げよう。
—
1. 「files」「include」「exclude」の優先順位を知る
まず、この3つを混同していると事故る。ルールはシンプルだが厳格だ。
- `files`: 指定したファイルのみをコンパイル対象にする。極めて限定的で、小さなライブラリや単一スクリプト向け。
- `include`: コンパイル対象とするディレクトリやファイルを指定（globパターン可）。
- `exclude`: `include`で指定した範囲から「除外」するものを指定。
注意すべきは「優先順位」だ。
`files` が最も強く、次に `include`、最後に `exclude` が適用される。つまり、`exclude` に書いても `include` で個別に指定されたファイルはコンパイルされてしまう。ここを理解していないと、「除外したはずなのにエラーが出る」という不毛なデバッグに時間を溶かすことになる。
—
2. 実務で「これだけは守れ」という鉄板テンプレート
実務では、以下のような構成が最も安全で保守性が高い。
{
“compilerOptions”: {
/ … 略 … /
},
// 1. 基本は src 配下だけを見させる
“include”: [
“src//”,
“next-env.d.ts”, // Next.jsなどのメタデータ用
“.eslintrc.js” // 設定ファイル自体の型チェックをしたい場合
],
// 2. 不要な場所を徹底的に叩き出す
“exclude”: [
“node_modules”,
“dist”,
“build”,
“/.test.ts”, // テストコードは別設定（tsconfig.test.json）にするのが吉
“/.spec.ts”
]
}
なぜテストコードを `exclude` するのか？
現場レベルの知見として、テストコードとソースコードを同じ `tsconfig` で管理するのは推奨しない。テストには `jest` や `vitest` の型定義が必要だが、本番コードには不要だ。これらを混ぜると、テスト用の型定義が本番コードに漏れ出し、プロダクトの型安全性が揺らぐ。「テスト用と本番用で `tsconfig` を分ける（`extends`を使う）」のが、熟練者の作法だ。
—
3. ブラウザはどう処理しているのか？（勘違いを正す）
ここで一つ、非常に重要な補足をしておこう。
「tsconfig.jsonで除外したからといって、ブラウザ上の動作が変わるわけではない」という点だ。
TypeScriptのコンパイルはあくまで「開発時の静的解析」に過ぎない。`tsc` はファイルを読み込み、AST（抽象構文木）を生成してエラーチェックを行い、最終的にJavaScriptへとトランスパイルする。`tsconfig` は「コンパイラにどこまで深く探索させるか」を制御する地図に過ぎない。
したがって、`exclude` で除外したファイルが、結果としてバンドル（WebpackやViteなど）に含まれてしまうことは往々にしてある。「コンパイル対象の制御」と「ビルド時のバンドル対象の制御」は、似ているようで全く別のレイヤーの話だ。ここを混同して、「tsconfigから消したのにバンドルサイズが変わらない！」と悩むのは中級者が一度は通る道である。
—
4. 現場のシニアとしてのアドバイス
最後に、明日からの開発に役立つTipsを置いておく。
1. `files` は基本使わない: プロジェクトが大きくなると管理不能になる。globパターン（`/`）を活用して、ディレクトリ単位で制御しよう。
2. `node_modules` は明示しなくてもいいが、あえて書く: 規約として `exclude` に含めておくことで、チームメンバーに対する「ここはコンパイル対象外である」という明示的な意思表示になる。
3. `tsc –showConfig` を使え: 設定が複雑になってきたら、ターミナルで `npx tsc –showConfig` を打ってみよう。実際にTypeScriptが解釈している設定値がJSONで出力される。これが真実だ。
TypeScriptの環境構築は「面倒くさい」と感じるかもしれないが、ここを疎かにするエンジニアは、一生「謎のエラー」に振り回されることになる。プロジェクトの土台を強固に保つこと。それこそが、フロントエンド・スペシャリストへの第一歩だ。
健闘を祈る。また何かあればいつでも聞いてくれ。
コメント