Github url


by DefinitelyTyped

DefinitelyTyped /DefinitelyTyped

The repository for high quality TypeScript type definitions.

28.9K Stars 22.0K Forks Last release: 10 months ago (0.1.450) Other 70.1K Commits 1 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

Definitely Typed

The repository for high quality TypeScript type definitions.

You can also read this README in Spanish, Korean, Russian, Chinese and Portuguese!

Link to Admin manual

Table of Contents

Current status

This section tracks the health of the repository and publishing process. It may be helpful for contributors experiencing any issues with their PRs and packages.

If anything here seems wrong, or any of the above are failing, please raise an issue in the Definitely Typed Gitter channel.

Join the chat at

What are declaration files?

See the TypeScript handbook.

How do I get them?


This is the preferred method. For example:

npm install --save-dev @types/node

The types should then be automatically included by the compiler. You may need to add a


reference if you're not using modules:

/// <reference types="node"></reference>

See more in the handbook.

For an NPM package "foo", typings for it will be at "@types/foo". If you can't find your package, look for it on TypeSearch.

If you still can't find it, check if it bundles its own typings. This is usually provided in a




field in the


, or just look for any ".d.ts" files in the package and manually include them with a

/// <reference path=""></reference>


Older versions of TypeScript (2.9 and earlier)

Definitely Typed only tests packages on versions of TypeScript that are less than 2 years old. Currently versions 3.0 and above are tested. If you're using TypeScript 2.0 to 2.9, you can still try installing


packages — the majority of packages don't use fancy new TypeScript features. But there's no guarantee that they'll work. Here is the support window:

Version | Released | End of Support -- | -- | -- 2.8 | March 2018 | March 2020 2.9 | May 2018 | May 2020 3.0 | July 2018 | July 2020 3.1 | September 2018 | September 2020 3.2 | November 2018 | November 2020 3.3 | January 2019 | January 2021 3.4 | March 2019 | March 2021 3.5 | May 2019 | May 2021 3.6 | August 2019 | August 2021 3.7 | November 2019 | November 2021 3.8 | February 2020 | February 2022 3.9 | May 2020 | May 2022


packages have tags for versions of TypeScript that they explicitly support, so you can usually get older versions of packages that predate the 2-year window. For example, if you run

npm dist-tags @types/react

, you'll see that TypeScript 2.5 can use types for [email protected], whereas TypeScript 2.6 and 2.7 can use types for [email protected]:

|Tag | Version| |----|---------| |latest| 16.9.23| |ts2.0| 15.0.1| | ... | ... | |ts2.5| 16.0.36| |ts2.6| 16.4.7| |ts2.7| 16.4.7| | ... | ... |

TypeScript 1.*

  • Manually download from the
    branch of this repository and place them in your project
  • Typings (use preferred alternatives, typings is deprecated)
  • NuGet (use preferred alternatives, nuget DT type publishing has been turned off)

You may need to add manual references.

How can I contribute?

Definitely Typed only works because of contributions by users like you!


Before you share your improvement with the world, use it yourself.

Test editing an existing package

To test local to your app, you can use module augmentation to extend existing types from the DT module you want to work on. Alternatively, you can also edit the types directly in


to validate your changes, then bring the changes to this repo with the steps below.

Adding tests to a new package

Add to your



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



containing declarations for the module "foo". You should now be able to import from


in your code and it will route to the new type definition. Then build and run the code to make sure your type definition actually corresponds to what happens at runtime.

If you're wondering where to start with test code, the examples in the README of the module are a great place to start.

Once you've tested your definitions with real code, make a PRthen follow the instructions to edit an existing package orcreate a new package.

Make a pull request

Once you've tested your package, you can share it on Definitely Typed.

First, fork this repository, install node, and run

npm install


Edit an existing package

  • cd types/my-package-to-edit
  • Make changes. Remember to edit tests. If you make breaking changes, do not forget to update a major version.

If there is a


, run

npm run lint package-name

. Otherwise, run


in the package directory.

When you make a PR to edit an existing package,


should @-mention previous authors. If it doesn't, you can do so yourself in the comment associated with the PR.

Editing tests on an existing package

There should be a


file, which is considered your test file, along with any


files it imports. If you don't see any test files in the module's folder, create a


. These files are used to validate the API exported from the


files which are shipped as



Changes to the


files should include a corresponding


file change which shows the API being used, so that someone doesn't accidentally break code you depend on. If you don't see any test files in the module's folder, create a


For example, this change to a function in a


file adding an a new param to a function:



- export function twoslash(body: string): string + export function twoslash(body: string, config?: { version: string }): string

: ```diff import {twoslash} from "./"

// $ExpectType string const result = twoslash("//")

  • // Handle options param
  • const resultWithOptions = twoslash("//", { version: "3.7" })
  • // When the param is incorrect
  • // $ExpectError
  • const resultWithOptions = twoslash("//", { }) ```

You can validate your changes with

npm test

from the root of this repo, which takes changed files into account.

Create a new package

If you are the library author and your package is written in TypeScript, bundle the autogenerated declaration files in your package instead of publishing to Definitely Typed.

If you are adding typings for an NPM package, create a directory with the same name. If the package you are adding typings for is not on NPM, make sure the name you choose for it does not conflict with the name of a package on NPM. (You can use

npm info foo

to check for the existence of the



Your package should have this structure:

| File | Purpose | | --- | --- | | index.d.ts | This contains the typings for the package. | | foo-tests.ts | This contains sample code which tests the typings. This code does not run, but it is type-checked. | | tsconfig.json | This allows you to run


within the package. | | tslint.json | Enables linting. |

Generate these by running

npx dts-gen --dt --name my-package-name --template module

if you have npm ≥ 5.2.0,

npm install -g dts-gen


dts-gen --dt --name my-package-name --template module

otherwise. See all options at dts-gen.

You may edit the


to add new test files, to add

"target": "es6"

(needed for async functions), to add to


, or to add the


compiler option. If you have


files besides


, make sure that they are referenced either in


or the tests.

If a file is neither tested nor referenced in


, add it to a file named


. This file is a list of other files that need to be included in the typings package, one file per line.

Definitely Typed members routinely monitor for new PRs, though keep in mind that the number of other PRs may slow things down.

For a good example package, see base64-js.

Definition Owners

DT has the concept of "Definition Owners" which are people who want to maintain the quality of a particular module's types

  • Adding yourself to the list will cause you to be notified (via your GitHub username) whenever someone makes a pull request or issue about the package.
  • Your PR reviews will have a higher precedence of importance to the bot which maintains this repo.
  • The DT maintainers are putting trust in the definition owners to ensure a stable eco-system, please don't add yourself lightly.

To Add yourself as a Definition Owner:

  • Adding your name to the end of the line, as in
    // Definitions by: Alice <https:>, Bob <https:></https:></https:>
  • Or if there are more people, it can be multiline
    typescript // Definitions by: Alice <https:>
    // Bob <https:>
    // Steve <https:>
    // John <https:>

Once a week the Definition Owners are synced to the file .github/CODEOWNERS which is our source of truth.

Common mistakes

  • First, follow advice from the handbook.
  • Formatting: Use 4 spaces. Prettier is set up on this repo, so you can run
    npm run prettier -- --write path/to/package/\*\*/\*.ts
    . When using assertions, add
    // prettier-ignore
    exclusion to mark line(s) of code as excluded from formatting:
    tsx // prettier-ignore const incompleteThemeColorModes: Theme = { colors: { modes: { papaya: { // $ExpectError
  • function sum(nums: number[]): number
    : Use
    if a function does not write to its parameters.
  • interface Foo { new(): Foo; }
    : This defines a type of objects that are new-able. You probably want
    declare class Foo { constructor(); }
  • const Class: { new(): IClass; }
    : Prefer to use a class declaration
    class Class { constructor(); }
    instead of a new-able constant.
  • getMeAT<t>(): T</t>
    : If a type parameter does not appear in the types of any parameters, you don't really have a generic function, you just have a disguised type assertion. Prefer to use a real type assertion, e.g.
    getMeAT() as number
    . Example where a type parameter is acceptable:
    function id<t>(value: T): T;</t>
    . Example where it is not acceptable:
    function parseJson<t>(json: string): T;</t>
    . Exception:
    new Map<string number>()</string>
    is OK.
  • Using the types
    is almost never a good idea. In 99% of cases it's possible to specify a more specific type. Examples are
    (x: number) =\> number
    for functions and
    { x: number, y: number }
    for objects. If there is no certainty at all about the type, [
    ]( is the right choice, not
    . If the only known fact about the type is that it's some object, use the type [
    ](, not
    { [key: string]: any }
  • var foo: string | any
    : When
    is used in a union type, the resulting type is still
    . So while the
    portion of this type annotation may look useful, it in fact offers no additional typechecking over simply using
    . Depending on the intention, acceptable alternatives could be
    , or
    string | object

Removing a package

When a package bundles its own types, types should be removed from Definitely Typed to avoid confusion.

You can remove it by running

npm run not-needed -- typingsPackageName asOfVersion sourceRepoURL [libraryName]

. -


: This is the name of the directory to delete. -


: A stub will be published to


with this version. Should be higher than any currently published version, and should be a version of


on npm. -


: This should point to the repository that contains the typings. -


: Name of npm package that replaces the Definitely Typed types. Usually this is identical to "typingsPackageName", in which case you can omit it.

Any other packages in Definitely Typed that referenced the deleted package should be updated to reference the bundled types. You can get this list by looking at the errors from

npm run test

. To fix the errors, add a



"dependencies": { "foo": "x.y.z" }

. For example:

{ "private": true, "dependencies": { "foo": "^2.6.0" } }

When you add a


to dependents of


, you will also need to open a PR to add


to dependenciesWhitelist.txt in types-publisher.

If a package was never on Definitely Typed, it does not need to be added to




All new packages must be linted. To lint a package, add a


to that package containing

js { "extends": "dtslint/dt.json" }

This should be the only content in a finished project's


file. If a


turns rules off, this is because that hasn't been fixed yet. For example:

{ "extends": "dtslint/dt.json", "rules": { // This package uses the Function type, and it will take effort to fix. "ban-types": false } }

(To indicate that a lint rule truly does not apply, use

// tslint:disable rule-name

or better,

//tslint:disable-next-line rule-name


To assert that an expression is of a given type, use


. To assert that an expression causes a compile error, use



// $ExpectType void f(1); // $ExpectError f("one");

For more details, see dtslint readme.


Test your changes by running

npm run lint package-name



is the name of your package.

This script uses dtslint to run the TypeScript compiler against your dts files.


What exactly is the relationship between this repository and the


packages on NPM?



branch is automatically published to the


scope on NPM thanks to types-publisher.

I've submitted a pull request. How long until it is merged?

It depends, but most pull requests will be merged within a week. Some PRs can be merged by the owners of a module, and they can be merged much faster. Roughly:

PRs which only change the types of a module, and have corresponding tests changes will be merged much faster

PRs that have been approved by an author listed in the definition's header are usually merged more quickly; PRs for new definitions will take more time as they require more review from maintainers. Each PR is reviewed by a TypeScript or Definitely Typed team member before being merged, so please be patient as human factors may cause delays. Check the New Pull Request Status Board to see progress as maintainers work through the open PRs.

My PR is merged; when will the


NPM package be updated?

NPM packages should update within a few minutes. If it's been more than an hour, mention the PR number on the Definitely Typed Gitter channel and the current maintainer will get the correct team member to investigate.

I'm writing a definition that depends on another definition. Should I use

<reference types=""></reference>

or an import?

If the module you're referencing is an external module (uses


), use an import. If the module you're referencing is an ambient module (uses

declare module

, or just declares globals), use

<reference types=""></reference>


I notice some packages having a



Usually you won't need this. DefinitelyTyped's package publisher creates a


for packages with no dependencies outside Definitely Typed. A


may be included to specify dependencies that are not other


packages.Pikaday is a good example.Even if you write your own


, you can only specify dependencies; other fields such as


are not allowed. You also need to add the dependency to the list of allowed packages. This list is updated by a human, which gives us the chance to make sure that


packages don't depend on malicious packages.

In the rare case that an


package is deleted and removed in favor of types shipped by the source package AND you need to depend on the old, removed


package, you can add a dependency on an


package. Be sure to explain this when adding to the list of allowed packages so that the human maintainer knows what is happening.

Some packages have no


, and some


are missing

"noImplicitAny": true


"noImplicitThis": true

, or

"strictNullChecks": true


Then they are wrong, and we've not noticed yet. You can help by submitting a pull request to fix them.

Can I request a definition?

Here are the currently requested definitions.

What about type definitions for the DOM?

If types are part of a web standard, they should be contributed to TSJS-lib-generator so that they can become part of the default



Should I add an empty namespace to a package that doesn't export a module to use ES6 style imports?

Some packages, like chai-http, export a function.

Importing this module with an ES6 style import in the form

import \* as foo from "foo";

leads to the error:

error TS2497: Module 'foo' resolves to a non-module entity and cannot be imported using this construct

This error can be suppressed by merging the function declaration with an empty namespace of the same name, but this practice is discouraged. This is a commonly cited Stack Overflow answer regarding this matter.

It is more appropriate to import the module using the

import foo = require("foo");

syntax. Nevertheless, if you want to use a default import like

import foo from "foo";

you have two options: - you can use the [


compiler option]( if your module runtime supports an interop scheme for non-ECMAScript modules, i.e. if default imports work in your environment (e.g. Webpack, SystemJS, esm). - you can use the [


compiler option]( if you want TypeScript to take care of non-ECMAScript interop (since TypeScript 2.7).

A package uses

export =

, but I prefer to use default imports. Can I change

export =


export default


Like in the previous question, refer to using either the [


]( [


]( options.

Do not change the type definition if it is accurate. For an NPM package,

export =

is accurate if

node -p 'require("foo")'

works to import a module, and

export default

is accurate if

node -p 'require("foo").default'

works to import a module.

I want to use features from TypeScript 3.1 or above.

Then you will have to add a comment to the last line of your definition header (after

// Definitions:


// TypeScript Version: 3.1


However, if your project needs to maintain types that are compatible with 3.1 and above at the same time as types that are compatible with 3.0 or below, you will need to use the


feature, which is available in TypeScript 3.1 and above. You can find a detailed explanation of this feature in the official TypeScript documentation.

Here's a short explanation to get you started:

  1. You'll have to add a
    file to your package definition, with the following contents:
{ "private": true, "types": "index", "typesVersions": { "\>=3.1.0-0": { "\*": ["ts3.1/\*"] } } }
  1. Create the sub-directory mentioned in the


field inside your types directory (


in this example) and add the types and tests specific for the new TypeScript version. You don't need the typical definition header in any of the files from the


directory. 2.

Set the




options in


to the correct paths, they should look something like this:

json { "compilerOptions": { "baseUrl": "../../", "typeRoots": ["../../"] } }

You can look here and here for examples.

I want to add a DOM API not present in TypeScript by default.

This may belong in TSJS-Lib-Generator. See the guidelines there. If the standard is still a draft, it belongs here. Use a name beginning with


and include a link to the standard as the "Project" link in the header. When it graduates draft mode, we may remove it from Definitely Typed and deprecate the associated



How do Definitely Typed package versions relate to versions of the corresponding library?

NOTE: The discussion in this section assumes familiarity with Semantic versioning

Each Definitely Typed package is versioned when published to NPM. The types-publisher (the tool that publishes


packages to npm) will set the declaration package's version by using the


version number listed in the first line of its


file. For example, here are the first few lines of Node's type declarations for version


at the time of writing:

// Type definitions for Node.js 10.12 // Project: // Definitions by: Microsoft TypeScript <https:>
// Definitely Typed <https:>
// Alberto Schiabel <https:>



is at the end of the first line, the npm version of the


package will also be


. Note that the first-line comment in the


file should only contain the


version (e.g.


) and should not contain a patch version (e.g.


). This is because only the major and minor release numbers are aligned between library packages and type declaration packages. The patch release number of the type declaration package (e.g.




) is initialized to zero by Definitely Typed and is incremented each time a new


package is published to NPM for the same major/minor version of the corresponding library.

Sometimes type declaration package versions and library package versions can get out of sync. Below are a few common reasons why, in order of how much they inconvenience users of a library. Only the last case is typically problematic.

  • As noted above, the patch version of the type declaration package is unrelated to the library patch version. This allows Definitely Typed to safely update type declarations for the same major/minor version of a library.
  • If updating a package for new functionality, don't forget to update the version number to line up with that version of the library. If users make sure versions correspond between JavaScript packages and their respective
    packages, then
    npm update
    should typically just work.
  • It's common for type declaration package updates to lag behind library updates because it's often library users, not maintainers, who update Definitely Typed when new library features are released. So there may be a lag of days, weeks, or even months before a helpful community member sends a PR to update the type declaration package for a new library release. If you're impacted by this, you can be the change you want to see in the world and you can be that helpful community member!

:exclamation: If you're updating type declarations for a library, always set the


version in the first line of


to match the library version that you're documenting! :exclamation:

If a library is updated to a new major version with breaking changes, how should I update its type declaration package?

Semantic versioning requires that versions with breaking changes must increment the major version number. For example, a library that removes a publicly exported function after its


release must bump its version to


in its next release. Furthermore, when the library's


release is out, its Definitely Typed type declaration package should also be updated to


, including any breaking changes to the library's API.

Many libraries have a large installed base of developers (including maintainers of other packages using that library as a dependency) who won't move right away to a new version that has breaking changes, because it might be months until a maintainer has time to rewrite code to adapt to the new version. In the meantime, users of old library versions still may want to update type declarations for older versions.

If you intend to continue updating the older version of a library's type declarations, you may create a new subfolder (e.g.


) named for the current (soon to be "old") version, and copy existing files from the current version to it.

Because the root folder should always contain the type declarations for the latest ("new") version, you'll need to make a few changes to the files in your old-version subdirectory to ensure that relative path references point to the subdirectory, not the root.

  1. Update the relative paths in
    as well as
  2. Add path mapping rules to ensure that tests are running against the intended version.

For example, the [


]( library introduced breaking changes between version




. Because many users still consumed the older


version, a maintainer who wanted to update the type declarations for this library to


added a


folder inside the history repository that contains type declarations for the older version. At the time of writing, the [history v2


]( looks roughly like:

{ "compilerOptions": { "baseUrl": "../../", "typeRoots": ["../../"], "paths": { "history": ["history/v2"] }, }, "files": ["index.d.ts", "history-tests.ts"] }

If there are other packages in Definitely Typed that are incompatible with the new version, you will need to add path mappings to the old version. You will also need to do this recursively for packages depending on packages depending on the old version.

For example,


depends on

[email protected]

, so [react-router


]( has a path mapping to

"history": ["history/v2"]

. Transitively,


(which depends on


) also needed to add the same path mapping (

"history": ["history/v2"]

) in its


until its


dependency was updated to the latest version.


/// <reference types=".."></reference>

will not work with path mapping, so dependencies must use



How do I write definitions for packages that can be used globally and as a module?

The TypeScript handbook contains excellent general information about writing definitions, and also this example definition file which shows how to create a definition using ES6-style module syntax, while also specifying objects made available to the global scope. This technique is demonstrated practically in the definition for big.js, which is a library that can be loaded globally via script tag on a web page, or imported via require or ES6-style imports.

To test how your definition can be used both when referenced globally or as an imported module, create a


folder, and place two test files in there. Name one


and the other


. The global test file should exercise the definition according to how it would be used in a script loaded on a web page where the library is available on the global scope - in this scenario you should not specify an import statement. The module test file should exercise the definition according to how it would be used when imported (including the


statement(s)). If you specify a


property in your


file, be sure to include both test files. A practical example of this is also available on the big.js definition.

Please note that it is not required to fully exercise the definition in each test file - it is sufficient to test only the globally-accessible elements on the global test file and fully exercise the definition in the module test file, or vice versa.

What about scoped packages?

Types for a scoped package


should go in


. Note the double underscore.



is used to scaffold a scoped package, the


property has to be manually adapted in the generated


to correctly reference the scoped package:

{ "paths":{ "@foo/bar": ["foo\_\_bar"] } }

The file history in GitHub looks incomplete.

GitHub doesn't support file history for renamed files. Use [

git log --follow

]( instead.


This project is licensed under the MIT license.

Copyrights on the definition files are respective of each contributor listed at the beginning of each definition file.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.