Standard Library

Relevant source files

• src/compiler/tsconfig.json
• src/harness/tsconfig.json
• src/harness/vfsUtil.ts
• src/lib/dom.generated.d.ts
• src/lib/dom.iterable.generated.d.ts
• src/lib/es2015.collection.d.ts
• src/lib/es2015.core.d.ts
• src/lib/es2015.d.ts
• src/lib/es2015.iterable.d.ts
• src/lib/es2015.proxy.d.ts
• src/lib/es2015.reflect.d.ts
• src/lib/es2015.symbol.d.ts
• src/lib/es2015.symbol.wellknown.d.ts
• src/lib/es2016.d.ts
• src/lib/es2017.d.ts
• src/lib/es2018.d.ts
• src/lib/es2020.bigint.d.ts
• src/lib/es5.d.ts
• src/lib/webworker.generated.d.ts
• src/lib/webworker.iterable.generated.d.ts
• src/server/tsconfig.json
• src/services/tsconfig.json
• tests/baselines/reference/baseCheck.errors.txt
• tests/baselines/reference/completionsStringMethods.baseline
• tests/baselines/reference/dissallowSymbolAsWeakType.errors.txt
• tests/baselines/reference/dynamicNames.js
• tests/baselines/reference/dynamicNames.symbols
• tests/baselines/reference/dynamicNames.types
• tests/baselines/reference/dynamicNamesErrors.errors.txt
• tests/baselines/reference/dynamicNamesErrors.js
• tests/baselines/reference/expressionTypeNodeShouldError.types
• tests/baselines/reference/extendArray.errors.txt
• tests/baselines/reference/extendingCollectionsWithCheckJs.symbols
• tests/baselines/reference/extendingCollectionsWithCheckJs.types
• tests/baselines/reference/globalThisBlockscopedProperties.types
• tests/baselines/reference/intersectionsOfLargeUnions.types
• tests/baselines/reference/intersectionsOfLargeUnions2.errors.txt
• tests/baselines/reference/intersectionsOfLargeUnions2.types
• tests/baselines/reference/jsxFactoryIdentifierWithAbsentParameter.errors.txt
• tests/baselines/reference/jsxFactoryQualifiedNameResolutionError.errors.txt
• tests/baselines/reference/mapConstructorOnReadonlyTuple.js
• tests/baselines/reference/mapConstructorOnReadonlyTuple.symbols
• tests/baselines/reference/mapConstructorOnReadonlyTuple.types
• tests/baselines/reference/mappedTypeRecursiveInference.errors.txt
• tests/baselines/reference/mappedTypeRecursiveInference.types
• tests/baselines/reference/mappedTypeWithAsClauseAndLateBoundProperty.errors.txt
• tests/baselines/reference/mappedTypeWithAsClauseAndLateBoundProperty.js
• tests/baselines/reference/mappedTypeWithAsClauseAndLateBoundProperty.symbols
• tests/baselines/reference/mappedTypeWithAsClauseAndLateBoundProperty.types
• tests/baselines/reference/mappedTypeWithAsClauseAndLateBoundProperty2.js
• tests/baselines/reference/mappedTypeWithAsClauseAndLateBoundProperty2.symbols
• tests/baselines/reference/mappedTypeWithAsClauseAndLateBoundProperty2.types
• tests/baselines/reference/modularizeLibrary_Dom.iterable.symbols
• tests/baselines/reference/modularizeLibrary_Dom.iterable.types
• tests/baselines/reference/modularizeLibrary_UsingES5LibAndES6FeatureLibs.types
• tests/baselines/reference/multiExtendsSplitInterfaces1.symbols
• tests/baselines/reference/newMap.errors.txt
• tests/baselines/reference/newMap.js
• tests/baselines/reference/newMap.symbols
• tests/baselines/reference/newMap.types
• tests/baselines/reference/parserOverloadOnConstants1.types
• tests/baselines/reference/tsbuild/outFile/rebuilds-completely-when-command-line-incremental-flag-changes-between-non-dts-changes.js
• tests/baselines/reference/tsbuild/outFile/when-final-project-is-not-composite-but-uses-project-references.js
• tests/baselines/reference/uniqueSymbols.symbols
• tests/baselines/reference/uniqueSymbolsDeclarations.symbols
• tests/cases/compiler/dynamicNames.ts
• tests/cases/compiler/dynamicNamesErrors.ts
• tests/cases/compiler/extendingCollectionsWithCheckJs.ts
• tests/cases/compiler/mapConstructorOnReadonlyTuple.ts
• tests/cases/compiler/mappedTypeWithAsClauseAndLateBoundProperty.ts
• tests/cases/compiler/mappedTypeWithAsClauseAndLateBoundProperty2.ts
• tests/cases/compiler/newMap.ts
• tests/cases/compiler/typedArrayConstructorOverloads.ts
• tests/cases/conformance/es2017/assignSharedArrayBufferToArrayBuffer.ts

This page provides an overview of the TypeScript standard library declaration files in src/lib/, their organization by ECMAScript version and runtime environment, and how the lib compiler option selects which files are included in a compilation. For information on individual ECMAScript version declaration files, see ECMAScript Standard Libraries. For the generated DOM and Web Worker API files, see DOM and Web Worker APIs.

---

Purpose

The TypeScript standard library is a set of .d.ts declaration files that describe the built-in JavaScript APIs available in a given runtime environment. These files make it possible for the type checker to understand types like Array<T>, Promise<T>, HTMLElement, and Worker without any user-provided declarations.

The library files ship alongside the compiler and are embedded in the npm package. They are not compiled by users — they are loaded automatically into each compilation based on the lib and target compiler options.

---

Source Layout

All standard library source files live under src/lib/. After building, they are output as lib.*.d.ts files alongside the compiler.

src/lib/
├── es5.d.ts                       → lib.es5.d.ts
├── es2015.core.d.ts               → lib.es2015.core.d.ts
├── es2015.collection.d.ts         → lib.es2015.collection.d.ts
├── es2015.generator.d.ts          → lib.es2015.generator.d.ts
├── es2015.iterable.d.ts           → lib.es2015.iterable.d.ts
├── es2015.promise.d.ts            → lib.es2015.promise.d.ts
├── es2015.proxy.d.ts              → lib.es2015.proxy.d.ts
├── es2015.reflect.d.ts            → lib.es2015.reflect.d.ts
├── es2015.symbol.d.ts             → lib.es2015.symbol.d.ts
├── es2015.symbol.wellknown.d.ts   → lib.es2015.symbol.wellknown.d.ts
├── es2015.d.ts                    → lib.es2015.d.ts  (aggregator)
├── es2016.array.include.d.ts      → lib.es2016.array.include.d.ts
├── es2016.d.ts                    → lib.es2016.d.ts  (aggregator)
├── ...                            (es2017 through es2024, ESNext)
├── dom.generated.d.ts             → lib.dom.d.ts
├── dom.iterable.generated.d.ts    → lib.dom.iterable.d.ts  (backward compat stub)
├── webworker.generated.d.ts       → lib.webworker.d.ts
├── webworker.iterable.generated.d.ts → lib.webworker.iterable.d.ts  (backward compat stub)
├── decorators.d.ts                → lib.decorators.d.ts
├── decorators.legacy.d.ts         → lib.decorators.legacy.d.ts
└── scripthost.d.ts                → lib.scripthost.d.ts

Sources: src/lib/es5.d.ts1-10 src/lib/dom.generated.d.ts1-6 src/lib/webworker.generated.d.ts1-6 src/lib/dom.iterable.generated.d.ts1-3 src/lib/webworker.iterable.generated.d.ts1-3

---

File Categories

Library files fall into four categories:

Category	Examples	Description
ECMAScript feature	es5.d.ts, es2015.core.d.ts	ECMAScript built-in types and globals
ECMAScript aggregator	es2015.d.ts, es2022.d.ts	Bundles sub-files for a given ES version via triple-slash references
Environment	dom.generated.d.ts, webworker.generated.d.ts	Runtime-specific APIs (browser window, workers)
Special feature	decorators.d.ts, scripthost.d.ts	Cross-cutting or platform-specific capabilities

ECMAScript aggregator files (e.g., es2015.d.ts) do not contain declarations directly — they use /// <reference lib="..." /> directives to pull in all the sub-files for that ES version. "Full" aggregator files (e.g., lib.es2015.full.d.ts) extend this further by also including dom, dom.iterable, and scripthost.

Sources: src/lib/es5.d.ts1-2 src/lib/es2015.collection.d.ts1-5 src/lib/es2015.iterable.d.ts1-2

---

File Naming Convention

Source filenames use the pattern <feature>.d.ts or <feature>.generated.d.ts for machine-generated files. At build time, these become lib.<feature>.d.ts. The lib compiler option accepts names without the lib. prefix and .d.ts suffix, matched case-insensitively.

Diagram: Source → Output → lib option value

Sources: src/lib/es5.d.ts1-10 src/lib/dom.generated.d.ts1-6

---

The lib Compiler Option

The lib option in tsconfig.json accepts an array of library names. When lib is specified, it fully replaces the default set — no libraries are auto-included.

When lib is not specified, a default set is selected based on target:

target	Default libraries
ES3 / ES5	lib.d.ts (ES5 + DOM + ScriptHost)
ES2015	ES2015 + DOM + DOM.Iterable + ScriptHost
ES2016	ES2016 + DOM + DOM.Iterable + ScriptHost
ES2017	ES2017 + DOM + DOM.Iterable + ScriptHost
ES2018	ES2018 + DOM + DOM.Iterable + DOM.AsyncIterable + ScriptHost
ES2019–ES2024	Corresponding ES version + DOM + DOM iterables + ScriptHost
ESNext	ESNext + DOM + DOM iterables + ScriptHost

Setting lib explicitly is common in Node.js projects where DOM types are unwanted:

---

Triple-slash Reference Dependencies

Library files compose via /// <reference lib="..." /> directives. The compiler resolves these at load time without requiring explicit lib entries from the user.

Diagram: Key triple-slash reference relationships

Sources: src/lib/es5.d.ts1-2 src/lib/dom.generated.d.ts1-2 src/lib/webworker.generated.d.ts1-2 src/lib/es2015.iterable.d.ts1 src/lib/es2015.symbol.wellknown.d.ts1 src/lib/es2020.bigint.d.ts1

---

Contents by Category

ECMAScript Libraries

Starting from es5.d.ts, each version layer adds new global types and extends existing interfaces. The base es5.d.ts declares:

• Globals: NaN, Infinity, eval, parseInt, parseFloat, isNaN, isFinite, decodeURI, encodeURI, etc.
• Built-in interfaces: Object, Function, CallableFunction, NewableFunction, Array, String, Number, Boolean, Math, Date, RegExp, Error, JSON
• Utility interfaces: ImportMeta, ImportCallOptions, ImportAttributes, TemplateStringsArray

es2015.core.d.ts then augments Array, Math, Number, Object, String, and RegExp with ES2015 additions. es2015.collection.d.ts declares Map, WeakMap, Set, and WeakSet. es2015.iterable.d.ts defines the Iterator, Iterable, IterableIterator, and IteratorObject interfaces.

Each subsequent ES year adds a sub-file (e.g., es2020.bigint.d.ts for BigInt) plus an aggregator (e.g., es2020.d.ts).

See ECMAScript Standard Libraries for full detail on each version.

Sources: src/lib/es5.d.ts8-81 src/lib/es2015.core.d.ts1-47 src/lib/es2015.collection.d.ts1-134 src/lib/es2015.iterable.d.ts10-52 src/lib/es2020.bigint.d.ts89-125

Environment Libraries

dom.generated.d.ts and webworker.generated.d.ts are machine-generated from web standards using the external TypeScript-DOM-lib-generator tool. They should not be edited by hand in this repository.

• dom.generated.d.ts declares all browser Window-context APIs — DOM nodes, events, CSS types, fetch, WebRTC, WebGPU, WebAudio, IndexedDB, Canvas, WebCodecs, and more.
• webworker.generated.d.ts declares the subset of APIs available inside Worker and ServiceWorker contexts — similar but excludes Window-specific APIs such as document.

Both files reference es2015 and es2018.asynciterable via triple-slash directives.

The stub files dom.iterable.generated.d.ts and webworker.iterable.generated.d.ts are now empty; their contents were folded into the respective main generated files. They remain for backward compatibility.

See DOM and Web Worker APIs for details.

Sources: src/lib/dom.generated.d.ts1-6 src/lib/webworker.generated.d.ts1-6 src/lib/dom.iterable.generated.d.ts1-3 src/lib/webworker.iterable.generated.d.ts1-3

Special Libraries

File	lib name	Purpose
decorators.d.ts	decorators	TC39 stage-3 decorator types
decorators.legacy.d.ts	decorators.legacy	TypeScript experimentalDecorators types
scripthost.d.ts	scripthost	Windows Script Host (ActiveX/WScript) types

es5.d.ts automatically includes both decorators and decorators.legacy via triple-slash references, so these are always present when any ECMAScript library is loaded.

Sources: src/lib/es5.d.ts1-2

---

Diagram: lib Option to File Mapping

Diagram: How lib option values map to source files

Sources: src/lib/es5.d.ts1-2 src/lib/dom.generated.d.ts1-2 src/lib/webworker.generated.d.ts1-2

---

Relationship to the Compiler

The compiler's Program creation logic (see Program and Compilation) is responsible for resolving lib names to actual file paths. When createProgram is called with CompilerOptions, the compiler looks up each lib entry against the known mapping and adds the corresponding .d.ts file as a root source file. Because these lib files use triple-slash references, the compiler then follows those references transitively to pull in all required declarations.

The test harness mounts the built lib files at a virtual path so that compiler tests can reference them:

• builtFolder = "/.ts" — virtual path to TypeScript build outputs including all lib.*.d.ts files
• fourslashLibFolder = "/home/src/tslibs/TS/Lib" — alternate mount for fourslash server tests

Sources: src/harness/vfsUtil.ts10-16