TypeScript Reference ยท Modules and Declaration Files
The TypeScript lib option and built-in types
Reference for the TypeScript lib compiler option: which built-in typings (ES versions, DOM, WebWorker) are loaded and how target picks the default set.
TypeScript knows what Array, Promise, Map or document are because it ships a set of declaration files called the lib files. The lib compiler option chooses which of them are loaded. If you do not set it, the default comes from target: an ES2024 target loads the ES2024 library plus the DOM and related browser libraries.
The option controls types only. It does not add polyfills and does not change the emitted code. Setting lib to include ES2025 while running on an old engine compiles happily and fails at runtime; setting it too low makes valid modern code a type error.
{ "compilerOptions": { "target": "ES2024", "lib": ["ES2024", "DOM", "DOM.Iterable"] } }
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.
The second example stops with error TS2584 on document, because the default library list of this runner has no DOM. The first one compiles because the ES2024 library declares Object.groupBy and toSorted.
Syntax
{ "compilerOptions": { "lib": ["ES2024", "ESNext.Disposable", "DOM"] } }
tsc --lib es2024,dom main.ts tsc --noLib # load no lib files at all (you provide Array, Object, ...)
| Value (case-insensitive) | Contents |
|---|---|
ES5, ES2015 ... ES2024, ESNext |
The cumulative standard library for that edition. ES2015 is the same as ES6. |
ES2023.Array, ES2022.Object, ... |
A single feature file from an edition. |
ESNext.Disposable and similar |
Proposals or features not yet in a numbered edition. |
DOM, DOM.Iterable, DOM.AsyncIterable |
Browser APIs: document, fetch, HTMLElement, iterable DOM collections. |
WebWorker, ScriptHost |
Worker globals and old Windows scripting host types. |
Edge cases: when lib is set it replaces the default, it does not add to it. If you set "lib": ["ES2024"] you lose the DOM, so document becomes error TS2584 ("Cannot find name 'document'. Do you need to change your target library? Try changing the 'lib' compiler option to include 'dom'."). The reverse also happens: a Node project that never needs the DOM should omit it so that window and friends are not silently accepted.
Usage notes
- Match the runtime, not just the compiler. Choose the highest edition your target runtimes implement. For Node 24 that is ES2024 plus the pieces of ESNext you know are present.
targetimplieslibonly whenlibis absent. A common surprise is loweringtargetto ES5 and suddenly losingPromiseandMaptypes.- Server projects usually list only an ES edition and rely on
@types/nodefor the Node globals (see @types packages). - Browser projects need
DOM; addDOM.Iterableto iterate aNodeListwithfor...of. - Typing is not a polyfill.
Object.groupBycompiles withES2024but throws on an engine without it. - Skipping libs:
skipLibCheckskips checking.d.tsfiles, including the libs, for speed; it does not remove them. - Version notes: new ECMAScript editions appear as new lib values with each TypeScript release; edit
librather than waiting fortargetdefaults.