The repository for high quality TypeScript type definitions.
Also see the definitelytyped.org website, although information in this README is more up-to-date.
See the TypeScript handbook.
This is the preferred method. This is only available for TypeScript 2.0+ users. For example:
npm install --save-dev @types/nodeThe types should then be automatically included by the compiler. 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 "types" or "typings" field in the package.json,
or just look for any ".d.ts" files in the package and manually include them with a /// <reference path="" />.
These can be used by TypeScript 1.0.
You may need to add manual references.
DefinitelyTyped only works because of contributions by users like you!
Before you share your improvement with the world, use it yourself.
To add new features you can use module augmentation.
You can also directly edit the types in node_modules/@types/foo/index.d.ts, or copy them from there and follow the steps below.
Add to your tsconfig.json:
"baseUrl": "types",
"typeRoots": ["types"],(You can also use src/types.)
Create types/foo/index.d.ts containing declarations for the module "foo".
You should now be able import from "foo" 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.
Once you've tested your definitions with real code, make a PR contributing the definition by copying types/foo to DefinitelyTyped/foo and adding a tsconfig.json and foo-tests.ts.
Once you've tested your package, you can share it on DefinitelyTyped.
First, fork this repository. Then inside your repository:
git checkout types-2.0
New work should generally be done on the types-2.0 branch.
If you want your changes to be available to typings users, then you may edit master instead.
cd my-package-to-edit- Make changes. Remember to edit tests.
- You may also want to add yourself to "Definitions by" section of the package header.
npm install -g [email protected]and runtsc.
When you make a PR to edit an existing package, dt-bot should @-mention previous authors.
If it doesn't, you can do so yourself in the comment associated with the PR.
If you are the library author, or can make a pull request to the library, bundle types instead of publishing to DefinitelyTyped.
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 foo package.)
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 tsc within the package. |
| tslint.json | Enables linting. |
Generate these by running npm run new-package -- new-package-name.
You may edit the tsconfig.json to add new files or to add the "jsx" compiler option.
DefinitelyTyped 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.
- First, follow advice from the handbook.
- Formatting: Either use all tabs, or always use 4 spaces. Also, always use semicolons, and use egyptian braces.
interface X {}: An empty interface is essentially the{}type: it places no constraints on an object.interface IFoo {}: Don't addIto the front of an interface name.interface Foo { new(): Foo; }: This defines a type of objects that are new-able. You probably wantdeclare class Foo { constructor(); }.const Class: { new(): IClass; }: Prefer to use a class declarationclass Class { constructor(); }instead of a new-able constant.namespace foo {}: Do not add a namespace just so that theimport * as foosyntax will work. If it is commonJs module with a single export, you should use theimport foo = require("foo")syntax. See more explanation here.getMeAT<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;. Example where it is not acceptable:function parseJson<T>(json: string): T;. Exception:new Map<string, number>()is OK.
When a package bundles its own types, types should be removed from DefinitelyTyped to avoid confusion. Make a PR doing the following:
- Delete the directory.
- Add a new entry to
notNeededPackages.json.libraryName: Descriptive name of the library, e.g. "Angular 2" instead of "angular2". (May be identical to "typingsPackageName".)typingsPackageName: This is the name of the directory you just deleted.sourceRepoURL: This should point to the repository that contains the typings.asOfVersion: A stub will be published to@types/foowith this version. Should be higher than any currently published version.
- Any other packages in DefinitelyTyped that referenced the deleted package should be updated to reference the bundled types.
To do this, add a
package.jsonwith"dependencies": { "foo": "x.y.z" }.
If a package was never on DefinitelyTyped, it does not need to be added to notNeededPackages.json.
To lint a package, just add a tslint.json to that package containing { "extends": "../tslint.json" }. All new packages must be linted.
If a tslint.json turns rules off, this is because that hasn't been fixed yet. For example:
{
"extends": "../tslint.json",
"rules": {
// This package uses the Function type, and it will take effort to fix.
"forbidden-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.)
Only .d.ts files are linted.
Test the linter by running npm run lint -- package-name. Do not use a globally installed tslint.
The types-2.0 branch is automatically published to the @types scope on NPM thanks to types-publisher.
This usually happens within an hour of changes being merged.
Changes to the master branch are also manually merged into the types-2.0 branch, but this takes longer.
I'm writing a definition that depends on another definition. Should I use <reference types="" /> or an import?
If the module you're referencing is an external module (uses export), use an import.
If the module you're referencing is an ambient module (uses declare module, or just declares globals), use <reference types="" />.
Currently we don't support this, though it is planned.
If you're adding a new major version of a library, you can copy index.d.ts to foo-v2.3.d.ts and edit index.d.ts to be the new version.
Usually you won't need this. When publishing a package we will normally automatically create a package.json for it.
A package.json may be included for the sake of specifying dependencies. Here's an example.
We do not allow other fields, such as "description", to be defined manually.
Also, if you need to reference an older version of typings, you must do that by adding "dependencies": { "@types/foo": "x.y.z" } to the package.json.
Then they are wrong. You can help by submitting a pull request to fix them.
If you're targeting types-2.0, write it like the types-2.0 definitions. If you're targeting master, we may change it to the new style when merging from master to types-2.0.
Here are the currently requested definitions.
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 lib.dom.d.ts.
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.