"lib"

Selects the built-in environment types: the JavaScript version, browser APIs, and individual new language features.

On this page

Example

#
JSON
{
  "compilerOptions": {
    "target": "ES2022",
    "lib": ["ES2023", "DOM", "DOM.Iterable"]
  }
}

Definition and usage

#

The lib option specifies which sets of built-in type declarations the compiler knows: JavaScript objects (Array, Map, Promise) in a given language version, browser APIs (document, fetch), or selected new features. It adds no code to your program, it only describes what exists in the environment.

Without lib, the compiler picks a set based on the target option and adds the browser types. When you provide lib yourself, you replace that default set, so in a browser project you have to add DOM and usually DOM.Iterable. In a Node.js project, the environment types come from the @types/node package, and it’s better to leave DOM out.

lib doesn’t add polyfills. If you add ES2023, the compiler will let you use toReversed(), but in a browser without that method the program will still throw an error. Choose values that match the environment where the code actually runs.

Syntax

#
Syntax
"lib": ["ES2022", "DOM", "DOM.Iterable"]

Most common values

#
  • ES2022, ES2023, …

    Language types from a given version, e.g. Array.prototype.at() in ES2022 and toSorted() in ES2023. Each version also includes all the earlier ones.
  • ESNext

    The newest features, including those not yet part of an official language version, e.g. the types for the using declaration.
  • DOM

    Browser APIs: window, document, HTML elements, events, and fetch.
  • DOM.Iterable

    Iteration over DOM collections, e.g. a for...of loop over the result of querySelectorAll().
  • WebWorker

    Web Worker environment types, used instead of DOM in worker files.
  • esnext.disposable

    An example of a single piece: the Symbol.dispose and Disposable types for using. Values like this add one new feature without raising the whole version.

More examples

#
Types outside the selected libraries
TypeScript
// "lib": ["ES2022"]
const scores = [72, 95, 88]
const reversed = scores.toReversed()
// Error: Property 'toReversed' does not exist on type 'number[]'. Do you need to change your target library? Try changing the 'lib' compiler option to 'es2023' or later.

const title = document.querySelector('h1')
// Error: Cannot find name 'document'. Do you need to change your target library? Try changing the 'lib' compiler option to include 'dom'.
Missing DOM.Iterable
TypeScript
// "lib": ["ES2023", "DOM"]
const items = document.querySelectorAll('li')
for (const item of items) item.classList.add('done')
// Error: Type 'NodeListOf<HTMLLIElement>' must have a '[Symbol.iterator]()' method that returns an iterator.

Good practices

#
  • Unless you have a specific reason, don’t set lib at all. The default set for the chosen target already includes the browser types.
  • The message “Do you need to change your target library?” means the code uses an API outside the selected libraries. Add the suggested value only if the environment really supports it.
  • You can enable individual new features without raising the whole version, e.g. "esnext.disposable" for the using declaration.

Related entries

#

Spotted a mistake or missing an example? Write to us.