The repository for high quality TypeScript type definitions.
Also see the definitelytyped.org website, although information in this README is more up-to-date.
You can also read this README in Spanish and Korean!
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/node
The 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.
- Typings
NuGet(use preferred alternatives, nuget DT type publishing has been turned off)- Manually download from the
master
branch of this repository
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
then follow the instructions to edit an existing package or
create a new package.
Once you've tested your package, you can share it on DefinitelyTyped.
First, fork this repository, install node, and run npm install
.
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.
- You may also want to add yourself to "Definitions by" section of the package header.
- This will cause you to be notified (via your GitHub username) whenever someone makes a pull request or issue about the package.
- Do this by adding your name to the end of the line, as in
// Definitions by: Alice <https://github.com/alice>, Bob <https://github.com/bob>
. - Or if there are more people, it can be multiline
// Definitions by: Alice <https://github.com/alice> // Bob <https://github.com/bob> // Steve <https://github.com/steve> // John <https://github.com/john>
- If there is a
tslint.json
, runnpm run lint package-name
. Otherwise, runtsc
in the package directory.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 and your package is written in TypeScript, bundle the autogenerated declaration files in your package 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 thefoo
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
npx dts-gen --dt --name my-package-name --template module
if you have npm โฅ 5.2.0,npm install -g dts-gen
anddts-gen --dt --name my-package-name --template module
otherwise. See all options at dts-gen.You may edit the
tsconfig.json
to add new files, to add"target": "es6"
(needed for async functions), to add to"lib"
, 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.
function sum(nums: number[]): number
: UseReadonlyArray
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 wantdeclare class Foo { constructor(); }
.const Class: { new(): IClass; }
: Prefer to use a class declarationclass Class { constructor(); }
instead of a new-able constant.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.- Using the types
Function
andObject
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,any
is the right choice, notObject
. If the only known fact about the type is that it's some object, use the typeobject
, notObject
or{ [key: string]: any }
. var foo: string | any
: Whenany
is used in a union type, the resulting type is stillany
. So while thestring
portion of this type annotation may look useful, it in fact offers no additional typechecking over simply usingany
. Depending on the intention, acceptable alternatives could beany
,string
, orstring | object
.
When a package bundles its own types, types should be removed from DefinitelyTyped to avoid confusion.
You can remove it by running
npm run not-needed -- typingsPackageName asOfVersion sourceRepoURL [libraryName]
.typingsPackageName
: This is the name of the directory to delete.asOfVersion
: A stub will be published to@types/foo
with this version. Should be higher than any currently published version.sourceRepoURL
: This should point to the repository that contains the typings.libraryName
: Descriptive name of the library, e.g. "Angular 2" instead of "angular2". (If ommitted, will be identical to "typingsPackageName".)
Any other packages in DefinitelyTyped that referenced the deleted package should be updated to reference the bundled types. To do this, add a
package.json
with"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": "dtslint/dt.json" }
. All new packages must be linted. If atslint.json
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
$ExpectType
. To assert that an expression causes a compile error, use$ExpectError
.// $ExpectType void f(1); // $ExpectError f("one");
For more details, see dtslint readme.
Test by running
npm run lint package-name
wherepackage-name
is the name of your package. This script uses dtslint.The
master
branch is automatically published to the@types
scope on NPM thanks to types-publisher.It depends, but most pull requests will be merged within a week. 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 DefinitelyTyped team member before being merged, so please be patient as human factors may cause delays. Check the PR Burndown Board to see progress as maintainers work through the open PRs.
NPM packages should update within a few hours. If it's been more than 24 hours, ping @RyanCavanaugh and @andy-ms on the PR to investigate.
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 (usesdeclare module
, or just declares globals), use<reference types="" />
.Usually you won't need this. When publishing a package we will normally automatically create a
package.json
for it. Apackage.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.Some packages have no
tslint.json
, and sometsconfig.json
are missing"noImplicitAny": true
,"noImplicitThis": true
, or"strictNullChecks": true
.Then they are wrong. You can help by submitting a pull request to fix them.
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
.A package uses
export =
, but I prefer to use default imports. Can I changeexport =
toexport default
?If you are using TypeScript 2.7 or later, use
--esModuleInterop
in your project. Otherwise, if default imports work in your environment (e.g. Webpack, SystemJS, esm), consider turning on the--allowSyntheticDefaultImports
compiler option. Do not change the type definition if it is accurate. For an NPM package,export =
is accurate ifnode -p 'require("foo")'
is the export, andexport default
is accurate ifnode -p 'require("foo").default'
is the export.Then you will have to add a comment to the last line of your definition header (after
// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
):// TypeScript Version: 2.1
.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
dom-
and include a link to the standard as the "Project" link in the header. When it graduates draft mode, we may remove it from DefinitelyTyped and deprecate the associated@types
package.If you intend to continue updating the older version of the package, you may create a new subfolder with the current version e.g.
v2
, and copy existing files to it. If so, you will need to:- Update the relative paths in
tsconfig.json
as well astslint.json
. - Add path mapping rules to ensure that tests are running against the intended version.
For example history v2
tsconfig.json
looks like:{ "compilerOptions": { "baseUrl": "../../", "typeRoots": ["../../"], "paths": { "history": [ "history/v2" ] }, }, "files": [ "index.d.ts", "history-tests.ts" ] }
If there are other packages on DefinitelyTyped 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 for packages depending on packages depending on the old version.
For example,
react-router
depends onhistory@2
, so react-routertsconfig.json
has a path mapping to"history": [ "history/v2" ]
; transitivelyreact-router-bootstrap
(which depends onreact-router
) also adds a path mapping in its tsconfig.json.Also,
/// <reference types=".." />
will not work with path mapping, so dependencies must useimport
.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
test
folder, and place two test files in there. Name oneYourLibraryName-global.test.ts
and the otherYourLibraryName-module.test.ts
. 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 theimport
statement(s)). If you specify afiles
property in yourtsconfig.json
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.
Types for a scoped package
@foo/bar
should go intypes/foo__bar
. Note the double underscore.When
dts-gen
is used to scaffold a scoped package, thepaths
property has to be manually adapted in the generatedtsconfig.json
to correctly reference the scoped package:{ "paths":{ "@foo/bar": ["foo__bar"] } }
GitHub doesn't support file history for renamed files. Use
git log --follow
instead.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, or to use a default import likeimport foo from "foo";
if using the--allowSyntheticDefaultImports
flag if your module runtime supports an interop scheme for non-ECMAScript modules as such.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.
definitelytyped's People
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. ๐๐๐
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google โค๏ธ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
Jobs
Jooble