Write new README (#12070)

* Write new README * Add back line about "users like you" * Mention bundled types
2026-03-29 08:58:23 +08:00 · 2016-10-19 06:00:46 -07:00
parent 3ec1144313
commit da44ddef86
1 changed files with 199 additions and 14 deletions
--- a/README.md
+++ b/README.md
@@ -4,36 +4,221 @@

 > The repository for *high quality* TypeScript type definitions.

-For more information see the [definitelytyped.org](http://definitelytyped.org) website.
+Also see the [definitelytyped.org](http://definitelytyped.org) website, although information in this README is more up-to-date.

-## Usage

-Include a line like this:
+## What are declaration files?

-```typescript
-/// <reference path="jquery.d.ts" />
+See the [TypeScript handbook](http://www.typescriptlang.org/docs/handbook/declaration-files/introduction.html).
+
+
+## How do I get them?
+
+### npm
+
+This is the preferred method. This is only available for TypeScript 2.0+ users. For example:
+
+```sh
+npm install --save-dev @types/node
 ```

-## Contributions
+The types should then be automatically included by the compiler.
+See more in the [handbook](http://www.typescriptlang.org/docs/handbook/declaration-files/consumption.html).
+
+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](https://microsoft.github.io/TypeSearch/).
+
+If you still can't find it, check if it [bundles](http://www.typescriptlang.org/docs/handbook/declaration-files/publishing.html) 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="" />`.
+
+
+### Other methods
+
+These can be used by TypeScript 1.0.
+
+* [Typings](https://github.com/typings/typings)
+* [NuGet](http://nuget.org/Tpackages?q=DefinitelyTyped)
+* Manually download from the `master` branch of this repository
+
+You may need to add manual [references](http://www.typescriptlang.org/docs/handbook/triple-slash-directives.html).
+
+
+## How can I contribute?

 DefinitelyTyped only works because of contributions by users like you!

-Please see the [contribution guide](http://definitelytyped.org/guides/contributing.html) on how to contribute to DefinitelyTyped.
+### Test

-## How to get the definitions
+Before you share your improvement with the world, use it yourself.

-* Directly from the GitHub repos
-* [NuGet packages](http://nuget.org/packages?q=DefinitelyTyped)
-* [Typings - TypeScript Definition Manager](https://github.com/typings/typings)
+#### Test editing an exiting package

-## List of definitions
+To add new features you can use [module augmentation](http://www.typescriptlang.org/docs/handbook/declaration-merging.html).
+You can also directly edit the types in `node_modules/@types/foo/index.d.ts`,
+or copy them from there and paste inside of `declarations.d.ts` and follow the steps below.

-* See [CONTRIBUTORS.md](CONTRIBUTORS.md)

-## Requested definitions
+#### Test a new package
+
+* Add a new file `declarations.d.ts` to your project.
+* Add it to the compilation, through `"includes"` or `"files"` in your [tsconfig](http://www.typescriptlang.org/docs/handbook/tsconfig-json.html),
+or through a `/// <reference path="" />` declaration in your code.
+* Inside `declarations.d.ts`, write `declare module "foo" { }`, then write the module declaration inside.
+* Test that your code works.
+* *Then*, once you've tested your definitions, make a PR contributing the definition.
+
+
+### Make a pull request
+
+Once you've tested your package, you can share it on DefinitelyTyped.
+
+First, [fork](https://guides.github.com/activities/forking/) 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.
+
+
+#### Edit an existing package
+
+* `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 typescript@2.0` and run `tsc`.
+
+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.
+
+
+#### Create a new package
+
+If you are the library author, or can make a pull request to the library, [bundle](http://www.typescriptlang.org/docs/handbook/declaration-files/publishing.html) 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. |
+
+`index.d.ts` should start with a header looking like:
+
+```ts
+// Type definitions for foo 1.2
+// Project: https://github.com/baz/foo
+// Definitions by: My Self <https://github.com/me>
+// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
+```
+
+The `Project` link does not have to be to GitHub, but prefer linking to a source code repository rather than to a project website.
+
+`tsconfig.json` should look like this:
+
+```json
+{
+    "compilerOptions": {
+        "module": "commonjs",
+        "target": "es6",
+        "noImplicitAny": true,
+        "strictNullChecks": false,
+        "baseUrl": "../",
+        "typeRoots": [
+            "../"
+        ],
+        "types": [],
+        "noEmit": true,
+        "forceConsistentCasingInFileNames": true
+    },
+    "files": [
+        "index.d.ts",
+        "foo-tests.ts"
+    ]
+}
+```
+
+These should be identical accross projects except that `foo-tests` will be replaced with the name of your test file,
+and you may also add the `"jsx"` compiler option if your library needs it.
+
+DefinitelyTyped members routinely monitor for new PRs, though keep in mind that the number of other PRs may slow things down.
+
+
+#### Common mistakes
+
+* First, follow advice from the [handbook](http://www.typescriptlang.org/docs/handbook/declaration-files/do-s-and-don-ts.html).
+* 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 Foo { new(): Foo }`:
+    This defines a type of objects that are new-able. You probably want `declare class Foo { constructor(); }
+* `namespace foo {}`:
+    Do not add a namespace just so that the `import * as foo` syntax will work.
+    If it is commonJs module with a single export, you should use the `import foo = require("foo")` syntax.
+    See more explanation [here](https://stackoverflow.com/questions/39415661/why-cant-i-import-a-class-or-function-with-import-as-x-from-y).
+* `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.
+
+
+#### Removing a package
+
+When a package [bundles](http://www.typescriptlang.org/docs/handbook/declaration-files/publishing.html) 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/foo` with 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.json` with `"dependencies": { "foo": "x.y.z" }`.
+
+
+## FAQ
+
+#### What exactly is the relationship between this repository and the `@types` packages on NPM?
+
+The `types-2.0` branch is automatically published to the `@types` scope on NPM thanks to [types-publisher](https://github.com/Microsoft/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 written as an external module (uses `export`), use an import.
+If the module you're referenceing is an ambient module (uses `declare module`, or just declares globals), use `<reference types="" />`.
+
+#### What do I do about older versions of typings?
+
+Currently we don't support this, though it is [planned](https://github.com/Microsoft/types-publisher/issues/3).
+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.
+
+#### I notice some packages having a `package.json` here.
+
+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](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/types-2.0/pikaday/package.json).
+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.
+
+#### Definitions in types-2.0 seem written differently than in master.
+
+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.
+
+#### Can I request a definition?

 Here are the [currently requested definitions](https://github.com/DefinitelyTyped/DefinitelyTyped/labels/Definition%3ARequest).

+
 ## License

 This project is licensed under the MIT license.