"lib"
Selects the built-in environment types: the JavaScript version, browser APIs, and individual new language features.
Example
#{
"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
#"lib": ["ES2022", "DOM", "DOM.Iterable"]Most common values
#ES2022, ES2023, …
Language types from a given version, e.g.Array.prototype.at()in ES2022 andtoSorted()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 theusingdeclaration.DOM
Browser APIs:window,document, HTML elements, events, andfetch.DOM.Iterable
Iteration over DOM collections, e.g. afor...ofloop over the result ofquerySelectorAll().WebWorker
Web Worker environment types, used instead ofDOMin worker files.esnext.disposable
An example of a single piece: theSymbol.disposeandDisposabletypes forusing. Values like this add one new feature without raising the whole version.
More examples
#// "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'.// "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
libat all. The default set for the chosentargetalready 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 theusingdeclaration.
Related entries
#- "target"The JavaScript version the compiler turns your code into.
- "module"The module format of the generated code and how imports are understood.
- "jsx"Specifies what the compiler does with JSX syntax in .tsx files.
- usingA declaration of a resource that is released automatically when the block exits, even after an error.
- "strict"Turns on a set of the most important, rigorous compiler checks.
Spotted a mistake or missing an example? Write to us.