hooked74 / definitelytyped

The repository for high quality TypeScript type definitions.

DefinitelyTyped

The repository for high quality TypeScript type definitions.

Table of Contents

• What are declaration files?
• How do I get them?
• Make a pull request
  • Edit an existing package
  • Create a new package
  • Package testing
  • Common mistakes
  • Removing a package

What are declaration files?

See the TypeScript handbook.

How do I get them?

This is the preferred method. This is only available for TypeScript 2.0+ users. For example:

npm install @h74-types/[package]

Next, you need to add a path to typeRoots in tsconfig.json

{
  ...
  "typeRoots": ["node_modules/@types", "./typings", "node_modules/@h74-types"]
  ...
}

If the types failed to connect, try the following syntax

/// <reference types="@h74-types/[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
• 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>

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 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.
package.json	This contains package description.
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.

You can use the npm run create command to generate a new package. Enter the name of the package and the author after which all the necessary files will be generated automatically. Adding/updating a new package occurs automatically, when adding/changing a package in types in the master branch.

For a good example package, see general.

Package testing

To test the package, after automatic generation, you can use the npm test command. Use this command from your package directory. If you decide to create the package manually then for testing you can use the command node ../../scripts/test.js from your package. Testing verifies linter operation and tsc compilation.

Common mistakes

• First, follow advice from the handbook.
• Formatting: Use 4 spaces. For new code, this is enforced by Prettier.
• function sum(nums: number[]): number: Use ReadonlyArray 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: 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 and Object 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, not Object. If the only known fact about the type is that it's some object, use the type object, not Object or { [key: string]: any }.
• var foo: string | any: When any is used in a union type, the resulting type is still any. So while the string portion of this type annotation may look useful, it in fact offers no additional typechecking over simply using any. Depending on the intention, acceptable alternatives could be any, string, or string | object.

Removing a package

Package can only be removed manually npm unpublish [package].