TypeScript · Const

lib

The lib compiler option selects the JavaScript and environment API declarations available during type checking. Use it to align TypeScript's known APIs with the actual runtime, browser platform, and polyfills in a project.

How it works

The lib compiler option controls which declaration files describe available JavaScript and environment APIs. It can replace the defaults inferred from target, letting a project include only the platform and ECMAScript features its runtime supplies, such as ES libraries, DOM types, or selected higher-level APIs.

Syntax

{
  "compilerOptions": {
    "lib": ["ES2020", "DOM"]
  }
}

Parameters

Name	Type	Description
`compilerOptions.lib`	`string[]`	An array of library names, such as "ES2020" or "DOM", that selects the declaration files included in the program.

Returns

No runtime return value; this is a tsconfig compiler option.

Key points

The option governs ambient declarations for standard JavaScript APIs, including core objects such as Math.
Browser-specific globals are separate from core JavaScript declarations; DOM is the documented library for APIs such as document.
The inferred library set follows target defaults, so raising target can make newer standard API types available automatically.
Server-side projects can omit DOM to prevent browser globals from appearing as valid ambient names.
A project can select declarations according to APIs supplied by its actual runtime or polyfills, independently of syntax support.
Library selection can model partial API availability instead of adopting every declaration from a complete ECMAScript level.

Common mistakes

Enabling noLib disables automatic library inclusion and takes precedence over lib.

Example: Selecting runtime API definitions

{
  "compilerOptions": {
    "target": "ES2020",
    "lib": ["ES2020", "DOM"]
  }
}

// src/main.ts
const root = document.querySelector("main");
const values = new Map<string, number>();
values.set("answer", 42);
console.log(root, values.get("answer"));

This configuration supplies type definitions for ES2020 APIs and browser DOM globals, allowing the file to use Map and document with type checking.

When to use it

Exclude browser declarations

A Node or server project should not expose browser globals such as document and window to application code.

Describe browser APIs

A browser application needs DOM types alongside the ECMAScript APIs provided by its chosen runtime.

Model polyfilled APIs

A project uses polyfills or native runtime features that are newer than the syntax target.

Make environment assumptions explicit

A large codebase needs its declared platform surface to match a specific execution environment.

Interview questions

QWhat does TypeScript's lib option control?

The lib option selects declaration files for built-in JavaScript APIs and platform APIs. For example, ES2015 supplies APIs such as Promise, Map, Set, and Symbol, while DOM supplies browser globals such as window and document.

Follow-up: How would you type-check browser APIs while emitting for an older JavaScript runtime? Set lib to include DOM and the required ECMAScript API declarations, then choose an appropriate lower target for emitted syntax.

QWhen should a project specify lib explicitly?

TypeScript normally chooses a default library set based partly on target. Explicit lib entries let a project remove unsuitable environment declarations, such as DOM types in a non-browser program, or add declarations for APIs supplied by polyfills.

Follow-up: Why might lib include a newer ES library than target? Because a runtime or polyfill may provide those APIs even though the compiler still downlevels newer syntax.

QHow are library choices represented?

lib entries name library groups rather than individual declaration filenames. The page lists high-level libraries such as ES5, ES2015, ES2016, and DOM, with aliases such as ES6 for ES2015 and ES7 for ES2016.

Follow-up: What should you do if only part of a newer standard is available? Select the relevant granular library entries rather than claiming the entire higher-level standard library.

target
noLib
types
explainFiles
/// <reference lib="..." />

Source: TypeScript: TSConfig Option: lib. Checked 2026-10-15.

lib