TypeScriptの型定義地獄から抜け出す：`typeRoots`と`types`でプロジェクトの「型」を支配する
現場で開発をしていると、たまに遭遇する「型が見つからない」「なぜか関係のないライブラリの型定義まで引っ張ってきて補完が汚れる」という問題。これ、`tsconfig.json`の`typeRoots`と`types`を正しく制御できていないのが原因のほとんどです。
公式ドキュメントにはさらっとしか書かれていませんが、ここを理解しているかどうかで、チームのDX（開発体験）は劇的に変わります。今日は、型定義の「読み込みの制御」という、少し地味だけど非常に強力な武器について深掘りしていきましょう。
—
1. なぜ「型定義の読み込み」を制御する必要があるのか？
TypeScriptはデフォルトで `node_modules/@types` を再帰的に探しに行きます。これは非常に便利ですが、大規模なプロジェクトや、特殊なディレクトリ構成（例えば、共通の型定義を別リポジトリから持ってきている場合など）では、「余計なものまで拾ってきて名前が衝突する」という事故が多発します。
特に、`window` オブジェクトの拡張や、独自に定義したグローバル型が、意図しないライブラリの型定義と混ざり合うと、デバッグは地獄絵図になります。これを防ぎ、コンパイルの速度と型安全性を担保するために、明示的な設定が必要になるわけです。
—
2. `typeRoots`：コンパイラの視線を強制する
`typeRoots` は、「TypeScriptが型定義を探しに行く『場所』」を限定する設定です。
デフォルトでは `[“./node_modules/@types”]` です。ここを書き換えるということは、「TypeScriptの標準的な検索ルールを無視して、俺たちが指定した場所だけを見ろ」と命令するのと同じです。
実践的な設定例
{
“compilerOptions”: {
// デフォルトのnode_modules/@typesを消すと、他の全ライブラリの型が消えるので注意！
// 複数の場所を指定する場合は、明示的に含める必要がある
“typeRoots”: [
“./node_modules/@types”, // これを忘れると外部ライブラリが全滅する
“./src/@types” // プロジェクト固有の型定義ディレクトリ
]
}
}
ここが泥臭いポイント：
`typeRoots` を設定する際、多くの人が `node_modules/@types` を書き忘れて「突然すべてのライブラリが `any` になった！」と青ざめます。`typeRoots` は上書きされる設定なので、基本的には「標準パス ＋ 独自パス」をセットで記述するのが鉄則です。
—
3. `types`：必要な型だけを厳選する
`types` は、`typeRoots` で指定した場所の中で、「具体的にどのパッケージの型定義を読み込むか」を絞り込むためのホワイトリストです。
これがなぜ強力かというと、例えば「プロジェクト内で `jest` は使っているが、`node` の型定義はあえて読み込ませたくない（グローバル汚染を防ぐため）」といった細かいチューニングが可能になるからです。
現場で役立つ設定例
{
“compilerOptions”: {
// “types”を指定すると、指定したもの以外は一切グローバルに読み込まれない
“types”: [
“jest”,
“node”,
“my-custom-definitions” // src/@types配下にある型定義ファイル群
]
}
}
シニアからのアドバイス：
`types` を明示的に設定すると、コンパイラは `node_modules/@types` の中身を全走査しなくなるため、大規模プロジェクトではビルド時間の短縮にも寄与します。 「名前が被るから型を絞りたい」という消極的な理由だけでなく、パフォーマンス最適化の一環として導入する意識を持つと、一歩上のエンジニアになれます。
—
4. そもそも「ブラウザ」はどう処理しているのか？
ここで少し視点を変えてみましょう。ブラウザはTypeScriptの `typeRoots` なんて知りません。ブラウザが理解するのは、最終的に生成されたJavaScriptだけです。
TypeScriptの型定義（`.d.ts`）は、「人間（とエディタ）のための地図」です。ブラウザは、その地図を頼りにビルドされた実行コードを読み込みます。
もし、`types` の設定をミスして、型定義が読み込まれずに `any` が放置されたままビルドすると、ブラウザ上では「プロパティが存在しない」という実行時エラー（`undefined`のアクセス）で画面が真っ白になります。
つまり、`typeRoots` と `types` の設定を厳格にすることは、「ビルド時（コンパイル時）に、ブラウザが爆発する未来を未然に防ぐ」ための防波堤なのです。
—
まとめ：明日から使えるアクションプラン
1. まずは現状を確認： `tsconfig.json` を開き、現在 `typeRoots` や `types` が未設定なら、あえて設定する必要があるか一度チームで議論してください。
2. 汚染を断つ： 特定のグローバル型（`window`の独自拡張など）が原因で型定義の衝突が起きているなら、`types` で読み込むパッケージを制限し、本当に必要なものだけを明示してください。
3. 整理整頓： プロジェクト固有の型定義は `src/@types` にまとめ、`typeRoots` でそこを確実に参照させる。
これだけで、エディタの補完候補がノイズだらけになるストレスから解放され、チーム全体の開発生産性が一段階上がります。
設定は「書いたもん勝ち」の世界です。ぜひ、今日の設定ファイルから整理を始めてみてください。応援しています。
コメント