コンパイルの「無駄」を殺せ：tsconfig.jsonにおけるinclude/excludeの極意
TypeScriptのコンパイラ（`tsc`）は、あなたのプロジェクトの守護神であると同時に、設定次第では開発体験を劇的に悪化させる「足枷」にもなり得る存在だ。大規模なアプリケーションにおいて、`include`と`exclude`の設定を疎かにすることは、言語サーバーのメモリ消費を肥大化させ、型チェックのループを無限に近い遅延へと導く。
今回は、単なる「対象ファイルの指定」というレベルを超え、ビルドパイプラインのパフォーマンスと型安全性を最大化するためのアーキテクチャ思考を紐解いていこう。
—
1. なぜ「デフォルト」が罠なのか
多くのプロジェクトでありがちなのが、`include`を広大に設定し、`exclude`を放置することだ。`tsc`は指定された範囲内の全ファイルを解析し、依存関係グラフを構築する。もし、ビルド成果物である `dist` や、単なる静的アセット、あるいはテスト実行時に動的に生成される一時ファイルが解析対象に含まれていれば、コンパイラは無駄な「型解析」という名の重労働を強いられる。
これが引き起こすのは単なるビルド時間の増大だけではない。VS Codeの言語サーバー（tsserver）が、変更のたびに不要なファイルを再スキャンし、メモリ使用率が数GBに達して「型定義が追いつかない」という現象を引き起こす。これは、上級エンジニアが絶対に避けなければならない初歩的なボトルネックだ。
2. 「物理的隔離」によるパフォーマンス最適化
堅牢なアーキテクチャを目指すなら、「コンパイル対象の最小化」と「境界の明確化」が鉄則だ。以下は、私が大規模フロントエンド案件で推奨する、パフォーマンスを意識した `tsconfig.json` の雛形である。
{
“compilerOptions”: {
/ … 略 … /
},
// 物理的にsrc配下のみを監視対象とするのは基本中の基本
“include”: [“src”],
“exclude”: [
“node_modules”, // 言うまでもないが、絶対に外す
“/.spec.ts”, // テストコードは別コンパイル単位に分離すべき
“dist”, // ビルド生成物は型解析の敵
“/.d.ts” // 宣言ファイルはcompilerOptionsのtypesで制御する
]
}
なぜテストファイルを `exclude` するのか？
多くのプロジェクトでは、`src//.ts` を含めてしまい、テストファイルまで型チェックの対象にしている。しかし、テストコードの変更が本番ビルドの型チェックを遅延させる必要はない。テストは `tsconfig.test.json` を別途用意し、`extends` を使ってベース設定を継承させるのが正解だ。これにより、開発中の型チェックサイクルから「テスト」という重い負荷を物理的に切り離せる。
3. 非同期の競合と型定義の「汚染」を回避する
`include` の設定が甘いと、予期せぬ場所にある型定義ファイル（`d.ts`）がグローバルスコープを汚染するリスクがある。特に、サードパーティライブラリの一部が型定義を公開していない場合に、無理やり `src` 直下に置かれた `types.d.ts` が全ての型推論を狂わせることがある。
これを防ぐには、`typeRoots` の管理と併せて、`include` の範囲を厳格に制限することだ。
// 型定義の汚染を防ぐための高度な設計例
{
“include”: [
“src//.ts”,
“src//.tsx”,
“types//.d.ts” // 型定義のみを隔離したディレクトリを明示的に含める
],
“exclude”: [
“node_modules”,
“dist”,
“src/__generated__” // Codegenで自動生成されたコードは型チェックの対象外にするのが賢明
]
}
特にGraphQLのクライアントコードなどを自動生成している場合、それらは膨大かつ複雑な型定義を持つ。これらを毎回 `tsc` にチェックさせるのはリソースの無駄だ。生成されたコードは「信頼できる」という前提に立ち、`exclude` で除外して型チェックの負荷を軽減しよう。
4. 伝説のアーキテクトからの助言：境界を制するものが開発を制する
実務レベルにおいて、TypeScriptのパフォーマンスは「いかにコンパイラを無駄に働かせないか」という引き算の哲学にかかっている。
1. 深いディレクトリ構造を避ける: `include` は広すぎても狭すぎてもダメだ。`src` の直下にモジュールごとの `tsconfig.json` を配置する `Project References` を検討しよう。これにより、各モジュールが独立して型チェックされ、インクリメンタルビルドの効率が劇的に向上する。
2. 型チェックの「非同期負荷」を認識する: VS Codeで「型定義のホバー」が遅いと感じたら、それは `include` 範囲内でコンパイラが過剰な依存関係を辿っている証拠だ。
3. 除外は「守り」ではない: `exclude` を適切に設定することは、コンパイラのメモリ空間を保護し、レンダリング負荷の高いブラウザ環境での「型解析のフリーズ」を物理的に回避する、攻めのアーキテクチャ手法である。
TypeScriptの設定ファイルは、単なるテキストではない。それは、あなたのプロジェクトという巨大な生命体の「脳」の活動範囲を定義する、極めて重要なコードなのだ。設定を最適化し、コンパイラを飼い慣らす。それこそが、大規模開発を成功へ導く唯一の近道である。
コメント