TypeScriptのビルドが遅い？「incremental」という魔法でDXを劇的に改善する話
現場で開発していると、プロジェクトが肥大化するにつれて「`tsc`を走らせるたびにコーヒーを淹れに行く時間が必要になる」なんて状況に陥りがちだ。特にCI/CDのパイプラインや、巨大なモノレポ環境ではこの待ち時間が開発体験（DX）を著しく損なう。
今日は、そんなTypeScript開発のストレスを根こそぎ解消する、隠れた名機能「Incremental Build（増分ビルド）」について深掘りしよう。
なぜTypeScriptのビルドは遅いのか？
ご存知の通り、TypeScriptのコンパイラ（`tsc`）は、実行されるたびに全てのファイルを解析し、型チェックを行い、JSを生成する。たとえ1行の修正であっても、大規模プロジェクトでは依存関係のグラフをゼロから再構築する。
これがブラウザ側で見れば、たかが数百KBのJSを読み込むだけなのに、ビルド工程では数万行の静的解析が走っているわけだ。この「無駄な再計算」を省くのが、`incremental`設定の役割だ。
incrementalビルドの仕組み：`.tsbuildinfo`の正体
`tsconfig.json`で `incremental: true` を有効にすると、コンパイル時にプロジェクトのビルド状態を記録した `.tsbuildinfo` というファイルが生成される。
これは、いわば「前回のビルドの記憶」だ。
- グラフの保存: ファイル間の依存関係をキャッシュし、どのファイルがどのファイルに影響を与えているかを記録する。
- 差分検出: コンパイル時に、変更されたファイルだけを特定し、その影響範囲（依存しているファイル群）のみを再計算する。
- 結果の再利用: 変更のないモジュールは、キャッシュから型情報を読み込むだけで済むため、理論上のビルド時間は劇的に短縮される。
実践：tsconfig.jsonの設定
まずは、君のプロジェクトの`tsconfig.json`に以下の設定を追加してほしい。
{
“compilerOptions”: {
// これが今回の主役。インクリメンタルビルドを有効にする
“incremental”: true,
// キャッシュファイルの出力先。デフォルトはプロジェクトルートだが、
// 散らかるのが嫌なら特定のディレクトリにまとめるのが吉
“tsBuildInfoFile”: “./.cache/tsconfig.tsbuildinfo”,
// 基本的な設定
“target”: “ESNext”,
“module”: “NodeNext”,
“strict”: true,
“esModuleInterop”: true
}
}
ここがプロのポイント
1. `tsBuildInfoFile`の管理: チーム開発では `.tsbuildinfo` を `.gitignore` に入れるのが基本だ。だが、CI環境でこれを活用したい場合は、アーティファクトとしてキャッシュを保存し、次回ビルド時に復元する工夫をすると、CIのビルド時間が劇的に短縮される。
2. クリーンビルドとの使い分け: まれにキャッシュが汚れて型エラーが正しく出ないケースがある。「なんか挙動がおかしいな？」と思ったら、迷わず `rm -rf .cache` してフルビルドを走らせる。この「潔さ」も中級者には必要だ。
実務で知っておくべき「落とし穴」
この機能は魔法ではない。以下の事実は頭の片隅に置いておこう。
- ディスクI/Oのトレードオフ: キャッシュを読み書きする時間は発生する。極小規模のプロジェクトでは、逆にオーバーヘッドの方が大きくなることもある。
- 型推論の複雑さ: TypeScriptの型システムは非常に強力だが、複雑すぎるジェネリクスを多用していると、キャッシュが効きにくい場合がある。ビルドが遅いのはツールのせいではなく、コードの書き方の問題である場合も多い。
- 環境の差異: ローカルのNode.jsのバージョンやコンパイラの設定がチーム内で統一されていないと、キャッシュの不整合が起きる。`volta` や `asdf` 等を使って環境を揃えるのは大前提だ。
まとめ：開発体験を最大化するために
`incremental` を有効にすることは、単なるビルド時間の短縮ではない。「変更したコードが数秒で検証できる」というサイクルを回すことこそが、バグを減らし、コードの品質を高める。
まずは自分のプロジェクトの `tsconfig.json` を開き、この設定を一行加えるところから始めてみてほしい。設定一つで、午後のコーヒーブレイクを「仕事の進捗」に変えることができるはずだ。
もしビルドがまだ遅いと感じるなら、次は `ts-loader` の `transpileOnly` や、`esbuild`/`swc` を使ったビルドの高速化を検討するフェーズだ。それはまた別の機会に話すとしよう。
さあ、エディタに戻って、爆速のビルドを体感してくれ。応援している。
コメント