DefinitelyTyped Explained for TypeScript

DefinitelyTyped is the community repository that sits behind every @types package you install. It is a massive GitHub project -- one of the largest on the platform -- where volunteers write and maintain TypeScript definitions for JavaScript libraries that do not ship their own types.

When you run npm install --save-dev @types/lodash, you are downloading files that were authored, reviewed, and published through that pipeline.

How DefinitelyTyped Works

The system has three main parts:

A contributor writes a declaration file for a library that lacks types and submits a pull request to the DefinitelyTyped repository. Community maintainers review the PR for correctness and completeness.

Once approved and merged, an automated tool called types-publisher picks up the change and publishes it to the @types scope on npm. End users install it with a standard npm install command.

The Repository Structure

The repository organizes types by package name, with one folder per package under a shared types/ directory.

text

DefinitelyTyped/
  types/
    lodash/
      index.d.ts
      lodash-tests.ts
      tsconfig.json
      package.json

Each package folder contains:

• index.d.ts: The main type definition file.
• package-tests.ts: A test file that imports and uses the types. This file is not executed -- it is compiled to verify the types are correct.
• tsconfig.json: A minimal TypeScript config for testing that specific package.
• package.json: Metadata including the package version and author.

The test file is the validation mechanism. It exercises the types by writing real usage code. If the test file compiles without errors, the types are considered correct.

Finding Types on DefinitelyTyped

Before writing your own types for a package, search to see if definitions already exist:

• Use npm and search for @types/your-package.
• Use the TypeSearch tool on the TypeScript website.
• Browse the DefinitelyTyped GitHub repository.

If the package is popular, chances are good that types already exist. For installing and using them, see install and use @types packages.

Type Definition Quality

Submitted types go through review by experienced maintainers. The review checks for:

• Correct use of TypeScript syntax, such as declare module, export, and namespace.
• Matching the library's actual API (parameters, return types, property names).
• Following the declaration file do's and don'ts.
• Including a test file that exercises the exported API.

Not all types are perfect. Some may lag behind the library's latest version, and some may have small inaccuracies. But the review process and community maintenance keep quality high for the most widely used packages.

The Role of types-publisher

The types-publisher is an automated bot that runs on a schedule. It scans the repository for merged changes and publishes updated packages to npm. Contributors do not publish manually -- the bot handles versioning, tagging, and publishing.

This automation ensures that the npm packages are always in sync with the repository and that version numbers follow a consistent scheme. The @types package version typically mirrors the library version it describes.

How DefinitelyTyped Differs from Bundled Types

Some libraries ship their own types directly in their npm package. Others rely on the community repository instead. Here is how to tell the difference:

The ecosystem is moving toward bundled types. New libraries are increasingly written in TypeScript directly or include hand-written declaration files. The community repository primarily serves the long tail of existing JavaScript libraries.

For libraries that have neither bundled types nor @types, see type untyped packages in TypeScript.

Contributing to DefinitelyTyped

If you have written types for a library that lacks them, you can contribute back.

The contribution guide has detailed instructions and templates. Maintainers review the PR, suggest changes if needed, and merge it once it passes checks. The types-publisher then releases the types to npm.

For publishing types with your own package, see publish type declarations for a package.

The Scale of DefinitelyTyped

DefinitelyTyped is one of the largest repositories on GitHub, with over 8,000 packages typed by thousands of contributors. It covers everything from tiny utility libraries to major frameworks.

The project demonstrates an important philosophy in the TypeScript ecosystem: types can be added after the fact. A JavaScript library does not need to be rewritten in TypeScript to benefit from type checking. The community can layer types on top, and everyone benefits.