TypeScriptで開発を進める際、必ずと言っていいほど目にする設定ファイルがtsconfig.jsonです。

その中でも、プロジェクトの型定義の基盤を支える重要な項目が「lib」オプションです。

コードを書いている途中で「fetchが見つからない」「Array.prototype.includesにアクセスできない」といったエラーに遭遇したことはないでしょうか。

こうした現象の多くは、このlib設定を正しく理解し、適切に構成することで解決できます。

本記事では、TypeScriptのlibオプションが果たす役割から、実行環境に応じた最適な選び方、そして各ライブラリ群の具体的な内容までを詳しく解説します。

2026年現在のモダンな開発環境を見据え、プロジェクトの安定性を高めるための設定スキルを身につけていきましょう。

目次 [ close ]
  1. TypeScriptのlib設定とは何か
    1. libオプションを指定する重要性
  2. targetとlibの関係性
    1. デフォルト挙動の仕組み
    2. targetとlibの使い分け
  3. libオプションで指定できる主要なカテゴリー
    1. 1. ECMAScript（JavaScriptコア）系
    2. 2. ブラウザ環境（DOM）系
    3. 3. 特殊なランタイム環境系
  4. シチュエーション別の最適な選び方
    1. モダンなフロントエンド開発（React, Vue, Next.jsなど）
    2. Node.js環境での開発
    3. Web Workerを使用する場合
  5. lib設定における注意点とトラブルシューティング
    1. 1. libを指定したら「型が見つからない」と怒られる
    2. 2. ライブラリごとの詳細な指定
    3. 3. 2026年におけるESNextの扱い
  6. まとめ

TypeScriptのlib設定とは何か

TypeScriptにおけるlibオプションは、コンパイル時にどの組み込みAPIの型定義を読み込むかを指定するものです。

TypeScript自体はJavaScriptの構文を拡張するものですが、実行環境（ブラウザやNode.jsなど）が提供する標準的なオブジェクトやメソッドの存在を、コンパイラにあらかじめ教えてあげる必要があります。

例えば、ブラウザ環境であればwindowオブジェクトやdocumentオブジェクト、最新のJavaScript（ECMAScript）であればPromiseやMapといった機能がこれに該当します。

もしこれらがlibに設定されていない場合、TypeScriptはそれらの定義を知らないため、コード上で使用しようとすると「名前が見つかりません」というコンパイルエラーを発生させます。

libオプションを指定する重要性

なぜこの設定が重要なのかというと、「開発環境が想定しているランタイムの能力」を正確に型システムへ反映させるためです。

古いブラウザをターゲットにしているにもかかわらず最新のAPI定義を読み込んでしまうと、コンパイルは通るのに実行時にエラーになるというリスクが生じます。

逆に、最新の機能を使いたいのに型定義がないと、型安全性を維持した開発が困難になります。

targetとlibの関係性

tsconfig.jsonにはlibと似た役割を持つtargetという項目があります。

この2つの関係を整理しておくことが、正しい設定への第一歩です。

デフォルト挙動の仕組み

libオプションを明示的に指定しない場合、TypeScriptはtargetに指定された値に基づいて、デフォルトのライブラリセットを自動的に選択します。

targetの設定デフォルトで読み込まれるlib
ES5DOM, ES5, ScriptHost
ES6 (ES2015)DOM, ES6, DOM.Iterable, ScriptHost
ES2020以降DOM, ES2020 (またはそれ以降), DOM.Iterable, ScriptHost

このように、多くの場合でDOMが含まれるため、通常のフロントエンド開発では意識しなくても動作します。

しかし、一度でもlibを明示的に記述すると、これらのデフォルト設定はすべて無効化され、記述した内容のみが有効になるという点に注意が必要です。

targetとlibの使い分け

targetは「どのバージョンのJavaScriptに変換（トランスパイル）するか」を決めます。

対してlibは「どのAPIが実行環境に存在すると仮定するか」を決めます。

例えば、最新の構文で書きたいが、実行環境には古いブラウザも含まれるためポリフィル（Polyfill）を別途導入する場合などは、targetを低めに設定しつつ、libには最新のESバージョンを指定するといった使い分けが行われます。

libオプションで指定できる主要なカテゴリー

libに指定できる値は非常に多岐にわたります。

これらは大きく以下の4つのグループに分類できます。

1. ECMAScript（JavaScriptコア）系

JavaScriptの言語仕様そのものに関する定義です。

ES5, ES2015, ES2023, ESNextなど、バージョンごとに指定できます。

  • ESNext: 現在のTypeScriptがサポートしている最新のECMAScript提案を含みます。
  • ES2025 / ES2026: 2026年現在のモダンなプロジェクトでは、標準的な機能としてこれらを選択することが増えています。

2. ブラウザ環境（DOM）系

ブラウザ固有のAPIに関する定義です。

  • DOM: window, document, HTMLElementなどの基本的なブラウザAPI。
  • DOM.Iterable: NodeListなどをfor...ofでループさせるために必要な定義。
  • WebWorker: Web Workerコンテキストで使用可能なAPI。

3. 特殊なランタイム環境系

特定の環境下でのみ有効な定義です。

  • ScriptHost: Windows Script Hostなど、特定のホスト環境用。
  • Decorators: 実装中のデコレータ機能に関する定義。

シチュエーション別の最適な選び方

プロジェクトの目的によって、設定すべきlibの内容は異なります。

具体的な設定例を見ていきましょう。

モダンなフロントエンド開発（React, Vue, Next.jsなど）

最新のブラウザ機能をフル活用し、かつポリフィルを適切に管理しているプロジェクトでの推奨設定です。

JSON
{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "lib": [
      "ESNext",
      "DOM",
      "DOM.Iterable"
    ],
    "strict": true
  }
}

DOM.Iterableを含めることで、以下のようなコードがエラーなく記述できるようになります。

TypeScript
// DOM.Iterableがないと、querySelectorAllの戻り値を直接ループできない場合がある
const buttons = document.querySelectorAll('button');
buttons.forEach(button => {
  console.log(button.textContent);
});

Node.js環境での開発

Node.js環境では、ブラウザ固有のAPIであるDOMは不要です。

むしろ、間違ってdocumentなどと入力した際にエラーが出るよう、DOMを除外するのがベストプラクティスです。

JSON
{
  "compilerOptions": {
    "target": "ES2024",
    "module": "NodeNext",
    "lib": [
      "ES2024"
    ],
    "strict": true
  }
}

Node.jsでfetchなどのグローバルAPIを使用する場合、Node.jsのバージョンによっては標準搭載されているため、適切なESバージョンを選択するだけで型定義が有効になります。

ただし、より詳細なNode.js固有の型が必要な場合は、libではなく@types/nodeをインストールして対応します。

Web Workerを使用する場合

Web Worker内ではwindowやDOMにアクセスできません。

そのため、メインスレッドとは別のtsconfig.jsonを用意することが推奨されます。

JSON
{
  "compilerOptions": {
    "lib": [
      "ESNext",
      "WebWorker"
    ]
  }
}

lib設定における注意点とトラブルシューティング

設定を変更した際に発生しがちな問題とその解決策を解説します。

1. libを指定したら「型が見つからない」と怒られる

前述した通り、libを一行でも書くとデフォルト設定が消えます。

例えば以下のようなミスがよくあります。

JSON
// 失敗例
"lib": ["ESNext"]

この場合、DOMの定義が消えてしまうため、console.logやsetTimeoutさえもエラーになる可能性があります（これらはDOM、あるいは環境ごとの定義に含まれるため）。

必ず必要なセットをすべて記述するようにしましょう。

2. ライブラリごとの詳細な指定

ES2025全体ではなく、その中の特定の機能（例：Promiseの新しいメソッドのみ）だけを導入したい場合は、ES2025.Promiseのようにドット区切りで指定することも可能です。

しかし、依存関係が複雑になるため、通常は大枠のバージョンを指定するのが無難です。

3. 2026年におけるESNextの扱い

2026年現在、ESNextは非常に安定しており、新しいECMASCriptのプロポーザルが迅速に取り込まれています。

常に最新の言語機能の恩恵を受けたい場合はESNextを指定しますが、チーム開発で環境を固定したい場合はES2025やES2026といった具体的な年号指定を行うのが安定運用のコツです。

まとめ

TypeScriptのlib設定は、単なるエラー消しのためのオプションではありません。

「そのプログラムがどこで動き、何ができるのか」を定義する、プロジェクトの設計図の一部です。

  • ブラウザアプリなら、ESNext, DOM, DOM.Iterableを基本とする。
  • Node.jsアプリなら、DOMを外し、ランタイムのバージョンに合わせたES系のみを指定する。
  • targetとの違いを理解し、ランタイムのポリフィル状況に合わせて適切に構成する。

これらのポイントを意識することで、無駄なコンパイルエラーに悩まされることなく、TypeScriptの強力な型安全性を最大限に引き出すことができます。

自身のプロジェクトのtsconfig.jsonを一度見直し、現在の実行環境に対して最適な設定になっているか確認してみましょう。