Fork me on GitHub

DefinitelyTyped

The repository for high quality TypeScript type definitions

Contribution guide

This guide covers contributing definitions. For information on contributing to the website go the website update guide.

Quality Criteria

To ensure the quality of DefinitelyTyped repository, the typings must meet the following criteria:

Naming the file

Try to use a simple lowercase identifier as name of the definition file, like library.d.ts or node-hoge.d.ts. To keep naming conflicts to a minimum please use the package name as used in the npm package registry. The only exception here should be NuGet / Windows oriented code as they use a camel-case convention.

If the library is published to multiple package managers (npm, bower, yam, NuGet, component etc) but under different names then also use the npm name.

If the library is not published on npm use a new identifier, as long as it doesn't shadow an existing npm name.

Version

In case there are multiple versions supported, the latest one will be without a version number in the file name. Older versions will be in the form of library-1.2.0.d.ts where the postfix should resemble a valid semantic version number (semver).

Location

The typing must be placed in a folder. The folder name must be similar to library name.

Example: qunit.d.ts in in a folder named qunit

In general the definition should be a single .d.ts file, but exceptions can be made for large libraries (~ >1000 LOC).

Content

The typing must have a header with the following format:

// Type definitions for [LIBRARY NAME]
// Project: [LIBRARY URL]
// Definitions by: [AUTHOR NAME] <[AUTHOR URL]>
// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped

If the version of the library is known then add it as a semver to the label.

// Type definitions for Backbone v0.9.10
// Project: http://backbonejs.org/
// Definitions by: Boris Yankov <https://github.com/borisyankov/>
// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped

Namespacing

Be careful to use a module to avoid conflicts to your internal interfaces and the interfaces from another typings. See best practices and the TypeScript wiki for some tips.

The jQuery.bbq typing has the interfaces in a module named JQueryBbq

Example:

module JQueryBbq {
    interface JQuery {
        //...
    }
    //...
}
interface JQueryStatic {
    bbq: JQueryBbq.JQuery;
    //...
}

See the best practices for more info on how to structure a definition file.

Documentation

Take advantage of TypeScript JSDoc support.

Tests

The typing must have tests in a files called library-tests.ts. The tests are not runnable in the TDD way but contain code that should compile with no errors, usually taken from the documentation samples of the library.

Example: backbone.d.ts has a test file named backbone-tests.ts, with this example of a real test file.

There are a few ways to test changes:

Simply compile the test file:
tsc --noImplicitAny your/code-tests.ts
tsc --noImplicitAny --module commonjs your/code-tests.ts
Run npm test before sending your pull request.
If you created new files add them to git so the tester picks them as changes.
Tests must be run from the DefinitelyTyped project's root directory.
You'll need to run npm update once to download the packages required by the test suite.
Enable Travis on your DT fork and test online.
See note below on how to enable this.
This takes a few steps to do but is faster for big cascading changes (like changing JQuery)
Depend on the automated test on Travis that runs after you send a PR.
If you need many attempts to fix errors then please flatten the history and clean the commit message.

You can use a tscparams file to specify custom compiler arguments e.g. atom/atom-tests.ts.tscparams

Note: By default npm test only runs tests for the changed / new definition files. To run all tests just execute npm run all.

Code style

At this point we do not enforce a specific general code style, but we do like idiomatic code in each individual file.
When creating a new definition file the author is free to choose either tabs or 4-space indentation (discussion on github).
Choice between Unix or Windows linebreaks is not enforced, as node.js doesn't care for it either way. Try to keep it idiomatic per file.
When editing an existing file please maintain the existing style as much as possible, this includes indenting, separator whitespace, bracing etc..
Do not use fancy code alignments or smart-tabs; instead keep things plain and simple.
It is discouraged to reformat existing code (as it breaks git attribution).
When preparing a Pull Request please check git diff (locally or on github) for unnecessary changes.
Regard the typing folder in your project as external resource and exclude it from your linter/formatter workflow, just like any library file.

Private APIs

We do not support exposing undocumented internal implementation details of libraries in .d.ts files. We follow this more strictly for popular libraries with good documentation e.g. jquery, angular, node etc.

CONTRIBUTORS.md will update automatically.

Note

Keep in mind the repos is a community project with a wide range on quality in contributions and moderation; so there may be the occasional rule violation or historical artifact.

Contribute to the site via the contribution guide.