`include` と `exclude` を制する者は、TypeScriptのビルド時間を制する
やあ。現場でコードを書いていると、つい「`tsconfig.json`？ 初期設定からいじってないよ」なんてことになりがちだよね。だが、プロジェクトが中規模、大規模と育っていくにつれ、コンパイル速度が目に見えて落ちたり、予期せぬ場所のファイルが型チェックに引っかかってイライラした経験はないだろうか？
今日は、TypeScriptの設定における「隠れた主役」、`include` と `exclude` について深掘りしていく。ここを適当に済ませていると、君のPCのファンが唸りを上げるだけでなく、チーム全体の開発体験（DX）が確実に低下する。実務の現場で「おっ、わかってるな」と思われるレベルまで引き上げよう。
—
なぜ `include` と `exclude` が重要なのか
TypeScriptコンパイラ（`tsc`）は、設定ファイルが置いてある場所を起点に、プロジェクト内の全ファイルを探索しようとする。もし君が `node_modules` を除外せず、巨大なライブラリ群を全てコンパイラの監視下に置いたらどうなるか？
コンパイラはメモリを大量に消費し、修正を一つ加えるたびに、君が触れてもいないライブラリの型定義まで再スキャンを始めるんだ。これが「ビルドが遅い」という悲劇の正体の一つだ。
また、ブラウザ側での処理について補足しておくと、TypeScriptはあくまで開発時の「静的解析ツール」だ。ブラウザはTypeScriptを直接解釈できない。我々が `tsc` や `esbuild`, `vite` を通じて変換した後のJavaScriptだけを読み込む。つまり、`include` や `exclude` は「どのファイルをビルド対象として型安全を保証するか」という開発時の制約であり、ブラウザへのデプロイサイズとはまた別のレイヤーで管理すべきものなんだ。
—
現場で即戦力となる `tsconfig.json` の構成案
これが、モダンなフロントエンドプロジェクト（Next.jsやReact + Viteなど）で私が推奨する設定のベースラインだ。
{
“compilerOptions”: {
/ …省略… /
},
// コンパイル対象を「src」以下に限定する
“include”: [
“src”,
“vite.config.ts” // 設定ファイル自体も型チェックの対象に含めるのが吉
],
// 肥大化の元凶を確実に排除する
“exclude”: [
“node_modules”, // 基本中の基本。これがないと死ぬ
“dist”, // ビルド生成物を含めると無限ループの温床になる
“build”,
“/.spec.ts”, // テストファイルを除外してビルドを高速化する戦略
“/.test.ts”
]
}
実務でのポイント：なぜ `exclude` にテストファイルを入れるのか？
大規模開発では、コンパイル対象を減らすことが正義だ。もし君がVitestやJestを使っているなら、テストファイルは `ts-node` 等で別個に実行されることが多いはず。これらをメインのビルドパスから外すことで、IDEの反応速度が劇的に向上する。
—
「思わぬ罠」を回避するためのプロの知見
1. `files` プロパティとの使い分け
`tsconfig.json` には `files` という配列もある。これは「特定のファイルだけをピンポイントで含める」ものだ。しかし、現場では絶対に使うな。管理コストが肥大化し、数ヶ月後に新人が入ってきたときに「なぜこのファイルだけここにあるんだ？」と首を傾げる原因になる。`include` でディレクトリを管理するのが現代のスタンダードだ。
2. `exclude` は「デフォルト」を理解せよ
実は、`exclude` を明記しなくても、`node_modules` や `bower_components` などはデフォルトで除外される仕様になっている。しかし、あえて明記するのには理由がある。「明示的であることは、暗黙的であることよりも優れている（Explicit is better than implicit）」というPythonの格言は、TypeScriptにも通ずる。後から来たメンバーが設定を見ただけで「何が除外されているか」が即座に分かるようにしておくべきだ。
3. 複雑なプロジェクト構造の場合
`src` 以外にドキュメントやスクリプトがある場合、以下のように書いてもいい。
“include”: [
“src//”, // src下の全ファイル
“types//.d.ts”, // 独自定義の型ファイル
“scripts/.ts” // 運用スクリプト
]
—
最後に：エンジニアとしてのスタンス
設定ファイルというのは、単なる「動けばいい設定」ではなく、プロジェクトの設計図だ。`include` を適切に設定することは、「このプロジェクトにおいて、何が我々の管理するソースコードで、何が外部のブラックボックスか」という境界線を引く行為に他ならない。
もし今、君のプロジェクトのビルドが重いと感じているなら、まずは `tsconfig.json` を開いて `include` に不要なディレクトリが入っていないか、`exclude` から漏れている肥大化したキャッシュディレクトリがないかを確認してみてほしい。
小さなチューニングの積み重ねが、君のチームの生産性を大きく変える。さあ、エディタに戻って、プロジェクトの境界線を整理しようか。応援しているよ。
コメント