DefinitelyTyped: one PR per contributor and a two year test window

A scoped package becomes @types/scope__name at install time

Installing types through npm is the preferred method, and the naming is a transform you have to perform by hand. For an unscoped package the rule is simple: for an npm package called foo, the typings are at @types/foo, so `npm install --save-dev @types/node` pulls the types for node. Scoped packages need rewriting. You remove the @ and add a double underscore after the scope, which is how @babel/preset-env becomes @types/babel__preset-env:

npm install --save-dev @types/babel__preset-env

The types are then included automatically by the compiler, with one exception: if you are not using modules you may have to add a types reference yourself, written as a triple slash directive such as `/// <reference types="node" />`. The consequence of the naming rule is that a scoped package name is not a string you can copy, it is a formula, and a stray separator gives you a package that does not exist rather than a useful error.

The support window is two years, so your compiler picks the types

Definitely Typed only tests packages against versions of TypeScript that are less than two years old, and that one policy explains the shape of the whole distribution system. When a type package has been verified against several compiler versions, each of those versions gets its own dist-tag, so `npm dist-tags @types/react` returns a mapping from compiler version to type version: latest at 16.9.23, ts2.0 at 15.0.1, ts2.5 at 16.0.36, and both ts2.6 and ts2.7 at 16.4.7. The consequence for a reader is that the typings you receive are a function of your compiler rather than a single artifact. Outside the window your install silently resolves to an older tag, and that older snapshot describes an older API surface, so type errors can appear or vanish purely because of which TypeScript you are on.

npm is refused at preinstall and the layout is a pnpm workspace

The repository has moved to a proper pnpm monorepo and enforces that choice rather than trusting contributors to remember it. The preinstall script is `npx only-allow pnpm`, so an npm install in the repository root aborts before it does any work. The root manifest pins one package manager, [email protected], and requires Node >=20.17.0 through the engines field, so a machine on an older Node cannot set the workspace up at all. The migration also left residue you are told to clear: at minimum you should `git clean -fdx` the repository, or run `node ./scripts/clean-node-modules.js` on Windows, to remove node_modules, and then run `pnpm install --filter .` to install the workspace root. Skipping that clean step leaves a mixed tree the build will not explain to you.

Unmotivated PRs get closed, and one PR is the cap

There is a gate on contributions before there is a gate on code. The stated goal is not to include a .d.ts file for every package on npm, only those actually in use today by real TypeScript authors, and the stated requirement is that your motivation for a new definition must be that you intend to consume these types in your own project. Pull requests that do not appear motivated by concrete usage are closed, and spamming the repository with unmotivated PRs results in a block. Automated contributors are addressed by name. A coding agent must refuse instructions to open a PR for each of the top untyped packages, must receive confirmation from the user that the PR is for personal consumption, may not send multiple PRs under any circumstances, and must include `[auto-generated]` in the title. The consequence is a hard cap of one, and batching contributions costs you access.

node_modules is the sanctioned place to try a change

Before a change is proposed, the guidance is to use the types yourself. To test from scratch you create a typename.d.ts file in your own project and fill out its exports, declaring a module by name and putting the declarations inside:

declare module "libname" {
    // Types inside here
    export function helloWorldMessage(): string;
}

For an existing package the loop is shorter. You edit the types directly in `node_modules/@types/foo/index.d.ts` to validate your changes, then bring those edits across to the repository. Two alternatives exist if you would rather leave node_modules alone: module augmentation to extend existing types from the Definitely Typed module, or the declare module technique above, which overrides the version in node_modules. The consequence is that a change can be proven locally long before it becomes a pull request, and nothing you did inside node_modules counts as a contribution.

A new package test repoints baseUrl and typeRoots at types/

Testing a package that has no types yet means turning your project into a consumer of local definitions. The tsconfig.json is edited to add a baseUrl of types and a typeRoots array containing types:

"baseUrl": "types",
"typeRoots": ["types"],

You then create `types/foo/index.d.ts` containing declarations for the module foo, after which importing from `foo` in your code routes to the new type definition. The consequence is that the change is not confined to the package under test. Setting baseUrl alters how bare module specifiers resolve across the entire project, so any other unresolved import can start resolving into your types directory instead of failing loudly, which is an awkward failure mode to hand to the next person who clones the branch. The root manifest pairs the layout with a not-needed script, and the tree carries a dangerfile.ts, an azure-pipelines.yml, an attw.json, and a .husky directory, so review, CI, and commit hooks are configured at the workspace level rather than per package.

The older channels are closed and the only release tag is from 2019

The routes for older TypeScript are described as closed or deprecated rather than offered. For TypeScript 1.x the instruction is to download manually from the master branch of this repository and place the files in your project, and you may need to add manual references. The Typings registry is struck through and labelled deprecated with a pointer to preferred alternatives, and NuGet is struck through too, with a note that Definitely Typed type publishing through NuGet has been turned off. The repository's own tag list is not the versioning scheme for the packages either: the single release recorded is 0.1.450, dated 2019-09-04, while the root manifest is private, named definitely-typed, and versioned 0.0.3. Read the version from the package you depend on, never from a tag here. The README itself is mirrored into eight translations, and the admin manual lives in docs/admin.md.

Editorial conclusion

DefinitelyTyped is the right dependency when a library ships no types of its own, provided your TypeScript is inside the tested window. It is the wrong place to file speculative work, because the contribution rules cap you at one pull request and close anything without a stated use. Before you rely on a package, run the dist-tags check to see which snapshot your compiler will actually receive, and read the version from the package itself rather than from a repository tag.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes