TypeScript-DOM-lib-generator, the tool that decides what TypeScript thinks a browser has

What the tool generates and why the browser rule matters

This tool is used to generate the web-based lib.dom.d.ts file which is included with TypeScript releases, and as the @types/web package. So the file most TypeScript projects never look at directly is the output of this repository, and the tool is where the decision about what counts as a web platform API is actually made.

The README's section on why a fancy API is still not available is the part worth reading, because it explains the most common source of confusion for TypeScript users. A feature needs to be supported by two or more major browser engines to be included, to make sure there is a good consensus among vendors: Gecko for Firefox, Blink for Chrome and Edge, and WebKit for Safari.

That is a deliberately conservative bar. It means a brand new API, even one shipped in Chrome and on the way to Safari, will not be in your types until a second engine has it. From the perspective of a developer working on a new platform feature, that is the reason a perfectly real API is missing from IntelliSense, and the README's answer is to file an issue, after checking the contribution guidelines.

The engine naming also resolves a subtlety that catches people out. Chromium-based browsers use the same browser engine, so support from them counts as a single support, not two. Chrome plus Edge is one engine, not two.

There is a related exclusion list. The README explains that the automated algorithm may decide a type is not well supported and remove it, and that inputfiles/removedTypes.jsonc holds types that are removed for that reason. If you want to add a type back, the procedure is to find the item in that file and remove it, then run npm run generate.

And when the exclusion is because the browser compatibility data is wrong, the README says to file an issue with the MDN browser-compat-data project, and notes that the type will be automatically added in a few weeks once the data is corrected. That is a good piece of design: the upstream truth lives in the compatibility data, and the generator follows it.

The build, the tests and the baseline comparison

Setting the project up is one install:

npm install

and generating the declaration files is one script:

npm run build

with a separate test command:

npm run test

The test mechanism is worth understanding because it explains how the project stays consistent with TypeScript itself. The files in the baselines/ directory from the TypeScript repo are used as baselines. For each pull request the script runs and compares the generated files with the baseline files.

So the generated output is not merely checked for compiling. It is diffed against the version that ships in TypeScript, and a pull request that changes the output is expected to change the baseline as well, which the README states plainly: in order to make the tests pass, update the baseline as well in any pull request.

That is a demanding review process and it is the right one. A generator that quietly drops a hundred declarations would be a problem, and the baseline diff makes that change visible in the review rather than in a release note.

The project is Apache-2.0 licensed, written in TypeScript, on the main branch, and the release history shows the output rather than the tool. The packages being published are @types/web and @types/webworker, with @types/web at 0.0.359 on 2026-10-15, @types/webworker at 0.0.82 on 2026-10-06, and @types/web at 0.0.358 two days before that. The version numbers are the 0.0.x scheme used for all the web platform type packages, and the two packages moving independently is expected, because the web worker definitions and the DOM definitions change on different schedules.

The last push was on 2026-10-20, the same day as a 0.0.359 release of @types/web, so the loop between a browser shipping an API, the compatibility data updating, and a new types package is running continuously.

Version compatibility and the ES6 target requirement

The README includes a long table mapping @types/web versions to TypeScript versions and the minimum TypeScript support, and the pattern in it is worth reading rather than skipping.

The earliest entries show @types/web 0.0.1 against TypeScript about 4.3 with minimum support 4.4, then 0.0.2 against 4.4 beta, and 0.0.25 against 4.4 proper. The table then moves through 4.5 beta, 4.5 release candidate and 4.5 final, with the same @types/web version sometimes serving two or three TypeScript releases. From 0.0.50 onwards the pattern is 4.6 beta, 4.6 release candidate and 4.6 final, and it continues through 4.7 and 4.8, each with a beta, a release candidate and a final, and finally 0.0.76 against 4.9 with no beta or candidate row.

The key observation is that the minimum TypeScript support stays at 4.4 for the entire table. That means a very large range of TypeScript versions can consume a current @types/web, and the pinning is on the TypeScript side rather than the types side. It also means the minimum is old enough that the types package cannot use newer TypeScript syntax, which is a real constraint on what the generator can emit.

The second compatibility note is about the target. The libraries available on @types, such as @types/web, require a target of ES6 or above, because iterator APIs are included. That is a practical thing to hit: a project still compiling to ES5 will find that the modern DOM typings do not work, because the iterable definitions they rely on are not available in that mode.

The documented path for adding a missing type is precise. Check whether there is an MDN document about the interface, look at the browser compatibility section, and check whether it is supported by two or more browser engines, remembering that Chromium browsers count once. If the conditions are met but the type is missing, the automated algorithm probably removed it through inputfiles/removedTypes.jsonc, and you remove the entry and run npm run generate. If the conditions are not met but MDN is wrong, the fix belongs in the MDN browser-compat-data project, and the type arrives automatically within a few weeks.

How this fits against the alternatives

The first alternative is to write your own declaration files or to use a community maintained web types package. The problem with both is the same: they drift from what browsers actually implement, and the drift is silent. A type that says a method exists when it does not produces a runtime failure that the compiler promised would not happen, which is the specific failure mode types are supposed to prevent.

The second alternative is to use the TypeScript types that ship inside the compiler distribution. That is what most projects do, and it is fine, but it means you get the DOM types from your TypeScript version, so a new API needs a TypeScript upgrade. The @types/web package exists precisely to break that coupling, and the release cadence in this repository is what makes it possible: the types move on the browser's schedule rather than the compiler's.

The third alternative is to not have DOM types at all and use any for the browser, which is a real strategy for code that runs in Node or in a worker and never touches a DOM. It also means no IntelliSense for browser APIs, which is a large loss for front-end work.

What this tool contributes is the policy, not just the output. The two-engine rule is a contested design decision, and having it implemented in one place and documented in the README is what makes it possible to argue about. The alternative would be every types package deciding on its own, and then the ecosystem would have three different answers to whether a given API is supported.

The cost of the conservative rule is real and the README states it: a newly shipped API is missing from your types for a while, and the fix path goes through an issue and possibly through the compatibility data project. For a library author targeting a new platform feature, that is a delay in typing support, and the workaround is to declare the API yourself until the generated file catches up.

The design of the extension process is worth noting too. A pull request that adds a type has to update the baseline as well, which means the reviewer sees the generated diff and the type addition together. That is a much better review than a diff in a hand-maintained file, and it is the reason the generated approach scales at all.

Editorial conclusion

Adopt this tool if you maintain TypeScript's DOM typings or want to see how the browser compatibility filter works, since it is the reference implementation of a rule that affects every TypeScript project. Skip it if you are looking for up to date DOM types in your own project, because the published @types/web package already contains them. Verify first by running npm install, npm run build and npm run test, and by checking a recently shipped browser API against the generated file to see whether the two-engine rule excluded it.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. microsoft/TypeScript-DOM-lib-generator on GitHub
4. README
5. Releases