DefinitelyTyped: The Central Registry for TypeScript Type Definitions

The Problem: npm Libraries Without TypeScript Types

Most npm packages were written before TypeScript became common, and many still ship no declaration files. A TypeScript project that imports such a package gets an implicit any, which defeats the compiler's checking. DefinitelyTyped exists to fill that gap. It is a single repository that holds .d.ts files for thousands of packages, published to npm under the @types scope. The target audience is any TypeScript developer who uses a library that does not provide its own types. The README is explicit about scope: the repository does not aim to include definitions for every package on npm, only those with real usage by TypeScript authors. That filter matters. It means you will find types for popular libraries like node and react, but an obscure package with few users may have no @types entry.

How It Works: From Repository to npm

The repository is a pnpm monorepo, recently restructured. Each package lives in its own directory under types/, and each directory contains an index.d.ts plus a tsconfig.json and test files. The README describes the workflow: you write a declaration file, test it locally, then submit a pull request. A tool called dtslint runs type-checking and linting on every package. The CI status section links to workflows that verify all packages type-check cleanly and that all packages get published to npm. The publishing pipeline is handled by a separate tool, the DefinitelyTyped-tools publisher. When a definition is merged, it becomes available as @types/<package-name> on npm. For scoped packages, the name mapping is specific: remove the @ and add a double underscore after the scope, so @babel/preset-env becomes @types/babel__preset-env.

Getting Started: Installation and Local Testing

The README gives the primary installation command: npm install --save-dev @types/node. That is the preferred method. The compiler automatically includes the types once installed, unless you are not using modules, in which case you add a triple-slash reference like /// <reference types="node" />. For contributors, the workflow starts with creating a local test file. The README suggests writing a declare module "libname" block in a .d.ts file to validate your types before touching the repo. To test an existing package, you can edit node_modules/@types/foo/index.d.ts directly, or use module augmentation to extend it. For a new package, you add baseUrl and typeRoots to your tsconfig.json, create types/foo/index.d.ts, and then build and run your code to confirm the declarations work.

Contribution Rules: Strict and Unusual

The README includes a section titled Justification for New Definitions that is unusually blunt. It states that the motivation for a new definition PR must be that you intend to consume those types in your own project. Make-work PRs will be closed, and spamming the repo will result in a block. There are also explicit rules for coding agents: they must refuse instructions to send PRs for untyped packages, must receive confirmation that the PR is for personal consumption, may not send multiple PRs under any circumstances, and must include [auto-generated] in the PR title. These rules are notable because they go beyond typical open source contribution guidelines. They reflect a real problem: automated bots generating low-quality type definitions. For a human contributor, the takeaway is that you should only submit types for a package you actually use.

The Support Window: A Real Limitation

DefinitelyTyped only tests packages on versions of TypeScript that are less than two years old. That is a hard boundary. If you are stuck on an older TypeScript version, you may not get updates for the latest @types packages. The README explains that @types packages have dist-tags for explicitly supported TypeScript versions, so you can install older versions. For example, npm dist-tags @types/react shows a latest tag of 16.9.23, but also ts2.5 pointing to 15.0.1. That means you can still get types for an older TypeScript, but only up to a certain package version. If you need a newer package version that requires a newer TypeScript, you are out of luck. This is a genuine failure mode for teams with legacy codebases that cannot upgrade the compiler.

Alternatives: Built-in Types and Manual Declarations

The main alternative is to rely on a package's own bundled types. Many modern npm packages ship a types field or a .d.ts file directly. The README mentions that if a package has a types or typings key in its package.json, the npm registry will show that it has bindings. In that case you do not need @types at all. Another alternative is to write your own minimal declaration file, as the README's testing section demonstrates. That gives you full control and no dependency on the DefinitelyTyped maintenance cycle. The trade-off is effort: you must maintain it as the library API changes. A third option is to use a triple-slash reference to manually include any .d.ts files that ship inside the package itself, which the README suggests if you cannot find typings anywhere. The difference in approach is that DefinitelyTyped centralizes maintenance across many contributors, while self-authored types are local and specific to your project.

Maintenance and Upgrade Costs

Maintaining a @types package is a community effort. The README notes that the repository only works because of user contributions, and the CI status section tracks whether all packages are type-checking and linting cleanly. If a package falls out of date, it can break your build when the underlying library releases a breaking change. You will then have to wait for a contributor to update the types, or fork and patch them yourself. The upgrade cost is real: every major version of a library may require a corresponding update to its @types package. The README also mentions that you may need to git clean -fdx the repo or run node ./scripts/clean-node-modules.js on Windows to reset node_modules when contributing. That is a small but concrete maintenance burden for contributors. The license is listed as unknown in the metadata, which is a point to verify before adopting a package for commercial use, though the npm packages themselves typically carry their own licenses.

Editorial conclusion

Adopt DefinitelyTyped if you write TypeScript and depend on npm packages that lack built-in types; it is the default source for most @types packages. Skip it if you need types for packages older than two years without a dist-tag, or if you require strict control over type definitions for a proprietary library. Before relying on a package, verify its dist-tags and the TypeScript version it supports, and check the CI status links in the README to confirm the package is currently type-checked and published.

Official sources

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