Library Definition Changes

Relevant source files

• .devcontainer/devcontainer.json
• .github/ISSUE_TEMPLATE/bug_report.yml
• .github/ISSUE_TEMPLATE/config.yml
• .github/ISSUE_TEMPLATE/feature_request.yml
• .github/ISSUE_TEMPLATE/lib_change.yml
• .github/ISSUE_TEMPLATE/module_resolution.yml
• .github/ISSUE_TEMPLATE/other.yml
• .github/ISSUE_TEMPLATE/types-not-correct-in-with-callback.md
• .github/dependabot.yml
• .github/pull_request_template.md
• .github/workflows/close-issues.yml
• .github/workflows/pr-modified-files.yml
• CONTRIBUTING.md
• README.md
• scripts/hooks/post-checkout
• scripts/hooks/pre-commit
• scripts/link-hooks.mjs
• src/lib/README.md
• src/lib/dom.generated.d.ts
• src/lib/dom.iterable.generated.d.ts
• src/lib/webworker.generated.d.ts
• src/lib/webworker.iterable.generated.d.ts
• tests/baselines/reference/baseCheck.errors.txt
• tests/baselines/reference/expressionTypeNodeShouldError.types
• tests/baselines/reference/extendArray.errors.txt
• 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/mappedTypeRecursiveInference.errors.txt
• tests/baselines/reference/mappedTypeRecursiveInference.types
• tests/baselines/reference/modularizeLibrary_Dom.iterable.symbols
• tests/baselines/reference/modularizeLibrary_Dom.iterable.types
• tests/baselines/reference/multiExtendsSplitInterfaces1.symbols
• tests/baselines/reference/parserOverloadOnConstants1.types

This page covers the process for requesting or contributing changes to TypeScript's built-in type declaration files (the lib files). These include ECMAScript standard library types, DOM API types, Web Worker API types, and Intl API types. For an overview of how these files are organized and selected at compile time, see Standard Library and ECMAScript Standard Libraries and DOM and Web Worker APIs.

---

Overview of the Lib File System

The standard library declarations live in three filesystem locations, each serving a distinct purpose:

Location	Purpose
src/lib/	Authoritative source files — all edits happen here
built/local/	Build output — copied from src/lib/ by the build task
lib/	Last Known Good (LKG) — used to bootstrap compilation; updated only on release

Do not edit lib/ directly. The files there are updated by the release process. Build output in built/local/ is regenerated automatically by running hereby CONTRIBUTING.md163-165

Sources: CONTRIBUTING.md154-170 src/lib/README.md1-27

---

File Categories

The src/lib/ directory contains two categories of files:

Hand-Edited Files

These cover ECMAScript language features and Intl APIs. They can be changed directly by editing the files under src/lib/. Examples:

• src/lib/es5.d.ts
• src/lib/es2022.array.d.ts
• src/lib/esnext.intl.d.ts

Generated Files

These cover the DOM and Web Worker APIs. They must not be edited by hand. They are auto-generated from an external tool.

File	Content
src/lib/dom.generated.d.ts	Window/DOM APIs src/lib/dom.generated.d.ts1-10
src/lib/webworker.generated.d.ts	Worker APIs src/lib/webworker.generated.d.ts1-10
src/lib/dom.iterable.generated.d.ts	Deprecated stub (contents merged into main file) src/lib/dom.iterable.generated.d.ts1-3
src/lib/webworker.iterable.generated.d.ts	Deprecated stub (contents merged into main file) src/lib/webworker.iterable.generated.d.ts1-3

Sources: CONTRIBUTING.md154-178 src/lib/README.md22-27

---

Source of Truth for Each Domain

Diagram: Lib File Ownership by Domain

Sources: src/lib/README.md5-26 CONTRIBUTING.md173-175

---

Criteria for Adding New Definitions

Inclusion criteria differ by domain.

Domain	Inclusion Criterion
ECMAScript / Intl	TC39 proposal at stage 3 or later
DOM / Web Worker APIs	API available un-prefixed and unflagged in at least 2 browser engines (not just 2 Chromium-based browsers)

These thresholds are documented in src/lib/README.md src/lib/README.md11-21

Useful references for determining readiness:

• ECMAScript finished proposals: tc39/proposals → finished-proposals.md
• Intl finished proposals: tc39/proposals → ecma402/finished-proposals.md
• DOM availability: MDN compatibility tables

---

Changing ECMAScript or Intl Library Files

For hand-edited files, the contribution process follows the standard pull request workflow described in Pull Request Process.

Steps:

1. Edit the relevant file in src/lib/.
2. Run hereby to propagate the change to built/local/.
3. Add or update compiler baseline tests if the change affects type-checking output.
4. Submit a pull request against the main branch.

The files in lib/ (LKG) should not be updated. They are only changed as part of the publishing process CONTRIBUTING.md169-171

Diagram: Hand-Edited Lib Change Flow

Sources: CONTRIBUTING.md154-170

---

Changing DOM or Web Worker API Files

The src/lib/dom.generated.d.ts and src/lib/webworker.generated.d.ts files are auto-generated and must not be edited directly in this repository. All changes must go through the TypeScript-DOM-lib-generator repository.

Steps:

1. File an issue or pull request at microsoft/TypeScript-DOM-lib-generator.
2. Once merged there, the generator produces updated *.generated.d.ts files.
3. Those files are then imported into this repository.

Diagram: DOM Change Flow

Sources: CONTRIBUTING.md172-175 src/lib/README.md22-27

Automated PR Rejection for Generated Files

A GitHub Actions workflow (pr-modified-files.yml) detects when a pull request directly modifies the generated files and automatically closes it with an explanatory message. This applies to:

• src/lib/dom.generated.d.ts
• src/lib/dom.iterable.generated.d.ts
• src/lib/webworker.generated.d.ts
• src/lib/webworker.iterable.generated.d.ts

The workflow is defined in .github/workflows/pr-modified-files.yml92-107 It uses the GitHub API to enumerate changed files in the PR and calls gh pr close with a comment directing the contributor to the generator repository.

---

Filing a Library Change Issue

The GitHub issue template for library changes is defined in .github/ISSUE_TEMPLATE/lib_change.yml .github/ISSUE_TEMPLATE/lib_change.yml1-57 It collects the following fields:

Field	Purpose
Compilation target	e.g., ES2020
Library	Which lib file is affected
Missing / Incorrect Definition	The specific API, property, or method
Sample Code	TypeScript code that should work but doesn't
Documentation Link	MDN, W3C, or ECMAScript spec reference

Note: The issue template explicitly mentions that the DOM lib (lib.dom.d.ts) is maintained at microsoft/TypeScript-DOM-lib-generator, and reporters can save a step by filing there directly.

Commonly requested but intentionally excluded items include:

• Browser-specific (prefixed) extensions
• Early experimental/stage 1–2 features
• APIs not available in at least 2 browser engines

Sources: .github/ISSUE_TEMPLATE/lib_change.yml1-57 src/lib/README.md11-21

---

Summary: Where to Contribute

Sources: CONTRIBUTING.md154-178 src/lib/README.md1-27 .github/ISSUE_TEMPLATE/lib_change.yml1-57 .github/workflows/pr-modified-files.yml92-107