フロントエンドエンジニアの皆さん、お疲れ様です。
プロジェクトが中規模を超え、`node_modules`が肥大化し、開発サーバーを立ち上げた瞬間にPCのファンが爆音で回り出す……そんな「あるある」に悩まされていませんか？
`tsc –watch`（または`tsc –build –watch`）を実行した時、TypeScriptは裏側でOSのファイルシステムイベントを監視しています。しかし、デフォルトの挙動のままでは、不要なファイルまで監視対象にしてしまい、CPUリソースの無駄遣いや、不要な再ビルドを引き起こす原因になります。
今日は、意外と見落とされがちな `tsconfig.json` の隠し球、`watchOptions` について、現場のリアルな知見を共有しましょう。
—
なぜ `watchOptions` を触る必要があるのか？
現代のフロントエンド開発において、IDE（VS Codeなど）やビルドツールが「ファイルを監視している」という事実は、もはや空気のような存在です。しかし、この監視の仕組みには大きく分けて2つのアプローチがあります。
1. ネイティブイベント（fs.watch / fs.watchFile）: OSから「ファイルが変わったよ」という通知を受け取る方法。高速ですが、環境やディレクトリの深さによって不安定になることがあります。
2. ポーリング（Polling）: 一定間隔で「変わったか？」「変わったか？」と確認しにいく方法。安定していますが、監視対象が多いとCPUを食いつぶします。
特にDocker環境やWSL2上で開発している場合、OS間のファイルシステム同期の遅延やイベント通知の欠落により、`tsc –watch` が変更を検知してくれない……という絶望的な状況に陥ることがあります。ここで、`watchOptions` の出番です。
—
現場で即戦力となる設定例
まずは、多くのプロジェクトで「とりあえずこれを入れておけば事故が減る」という鉄板の設定を提示します。
{
“compilerOptions”: {
/ … 既存の設定 … /
},
“watchOptions”: {
// 監視戦略の指定。大抵は ‘useFsEvents’ で問題ないが、
// Docker/WSL2環境で「保存してもビルドが走らない」時は ‘dynamicPriorityPolling’ に切り替える
“watchFile”: “useFsEvents”,
// ディレクトリ監視も同様。
“watchDirectory”: “useFsEvents”,
// 監視対象から除外するパス（重要！）
// node_modulesやビルド成果物、テストのキャッシュ等は明示的に外す
“excludeFiles”: [
“temp//”,
“dist//”
],
“excludeDirectories”: [
“/node_modules”,
“/dist”,
“/coverage”
]
}
}
設定のポイントを噛み砕く
- `watchFile` / `watchDirectory`:
- `useFsEvents`: OSのネイティブAPIを使います。爆速です。
- `fixedPollingInterval`: 一定間隔（ミリ秒）でチェックします。低速ですが、古いネットワークドライブ上など、ネイティブイベントが届かない環境での最終兵器です。
- `dynamicPriorityPolling`: 変更頻度の高いファイルは頻繁に、そうでないものは稀にチェックする賢いモード。迷ったらこれか `useFsEvents` です。
- `excludeFiles` / `excludeDirectories`:
ここは「何を監視しないか」という断捨離です。特に `node_modules` を監視対象から外すのは基本中の基本ですが、大規模プロジェクトでは `dist` フォルダ（ビルド成果物）を監視対象から外すだけで、再ビルドのループ（ビルドしてファイルが生成される → それを検知してまたビルドが走る）を防止できます。
—
シニアからのアドバイス：なぜこの設定が「守り」になるのか
僕が現場でよく見る悲劇は、「VS Codeの監視」と「TSコンパイラの監視」が競合しているケースです。
`tsconfig.json` の設定を最適化していないと、TSコンパイラが本来見る必要のない巨大な `dist` や `coverage` フォルダの中身までスキャンしに行きます。すると、エディタのレスポンスが極端に悪くなったり、メモリ不足でビルドが落ちたりします。
特にCI/CD環境ではなく、「ローカルでのDX（開発者体験）」を改善したい場合、この設定は非常に強力です。
最後に：トラブルシューティングの極意
もし、`watchOptions` を設定しても「変更が検知されない」という事態に陥ったら、まずは以下のコマンドを打ってみてください。
どのファイルが監視されているかを確認できるデバッグモード
tsc –watch –extendedDiagnostics
これを使うと、TSコンパイラがどのファイルにリソースを割いているかがログで分かります。案外、「思わぬログファイル」や「一時的に作成された巨大なJSONファイル」が監視対象に入っていることに気づくはずです。
TypeScriptは賢い言語ですが、その環境設定は非常に人間味のある泥臭い調整が求められます。ぜひ一度、自分のプロジェクトの `tsconfig.json` を見直して、快適な開発環境を取り戻してください。
何か困ったことがあれば、またいつでも聞いてください。応援していますよ。
コメント