Now that you have authored a declaration file following the steps of this guide, it is time to publish it to npm.\nThere are two main ways you can publish your declaration files to npm:
\nIf your types are generated by your source code, publish the types with your source code. Both TypeScript and JavaScript projects can generate types via --declaration.
Otherwise, we recommend submitting the types to DefinitelyTyped, which will publish them to the @types organization on npm.
If your package has a main .js file, you will need to indicate the main declaration file in your package.json file as well.\nSet the types property to point to your bundled declaration file.\nFor example:
\njson{\n \"name\": \"awesome\",\n \"author\": \"Vandelay Industries\",\n \"version\": \"1.0.0\",\n \"main\": \"./lib/main.js\",\n \"types\": \"./lib/main.d.ts\"\n}
Note that the \"typings\" field is synonymous with \"types\", and could be used as well.
Also note that if your main declaration file is named index.d.ts and lives at the root of the package (next to index.js) you do not need to mark the \"types\" property, though it is advisable to do so.
All dependencies are managed by npm.\nMake sure all the declaration packages you depend on are marked appropriately in the \"dependencies\" section in your package.json.\nFor example, imagine we authored a package that used Browserify and TypeScript.
\njson{\n \"name\": \"browserify-typescript-extension\",\n \"author\": \"Vandelay Industries\",\n \"version\": \"1.0.0\",\n \"main\": \"./lib/main.js\",\n \"types\": \"./lib/main.d.ts\",\n \"dependencies\": {\n \"browserify\": \"latest\",\n \"@types/browserify\": \"latest\",\n \"typescript\": \"next\"\n }\n}
Here, our package depends on the browserify and typescript packages.\nbrowserify does not bundle its declaration files with its npm packages, so we needed to depend on @types/browserify for its declarations.\ntypescript, on the other hand, packages its declaration files, so there was no need for any additional dependencies.
Our package exposes declarations from each of those, so any user of our browserify-typescript-extension package needs to have these dependencies as well.\nFor that reason, we used \"dependencies\" and not \"devDependencies\", because otherwise our consumers would have needed to manually install those packages.\nIf we had just written a command line application and not expected our package to be used as a library, we might have used devDependencies.
/// <reference path=\"...\" />Don’t use /// <reference path=\"...\" /> in your declaration files.
\nts/// <reference path=\"../typescript/lib/typescriptServices.d.ts\" />\n....
Do use /// <reference types=\"...\" /> instead.
\nts/// <reference types=\"typescript\" />\n....
Make sure to revisit the Consuming dependencies section for more information.
\nIf your type definitions depend on another package:
\ntypesVersionsWhen TypeScript opens a package.json file to figure out which files it needs to read, it first looks at a new field called typesVersions.
A package.json with a typesVersions field might look like this:
\njson{\n \"name\": \"package-name\",\n \"version\": \"1.0\",\n \"types\": \"./index.d.ts\",\n \"typesVersions\": {\n \">=3.1\": { \"*\": [\"ts3.1/*\"] }\n }\n}
This package.json tells TypeScript to check whether the current version of TypeScript is running.\nIf it’s 3.1 or later, it figures out the path you’ve imported relative to the package, and reads from the package’s ts3.1 folder.\nThat’s what that { \"*\": [\"ts3.1/*\"] } means - if you’re familiar with path mapping today, it works exactly like that.
In the above example, if we’re importing from \"package-name\", TypeScript will try to resolve from [...]/node_modules/package-name/ts3.1/index.d.ts (and other relevant paths) when running in TypeScript 3.1.\nIf we import from package-name/foo, we’ll try to look for [...]/node_modules/package-name/ts3.1/foo.d.ts and [...]/node_modules/package-name/ts3.1/foo/index.d.ts.
What if we’re not running in TypeScript 3.1 in this example?\nWell, if none of the fields in typesVersions get matched, TypeScript falls back to the types field, so here TypeScript 3.0 and earlier will be redirected to [...]/node_modules/package-name/index.d.ts.
The way that TypeScript decides on whether a version of the compiler & language matches is by using Node’s semver ranges.
\ntypesVersions can support multiple fields where each field name is specified by the range to match on.
\njson{\n \"name\": \"package-name\",\n \"version\": \"1.0\",\n \"types\": \"./index.d.ts\",\n \"typesVersions\": {\n \">=3.2\": { \"*\": [\"ts3.2/*\"] },\n \">=3.1\": { \"*\": [\"ts3.1/*\"] }\n }\n}
Since ranges have the potential to overlap, determining which redirect applies is order-specific.\nThat means in the above example, even though both the >=3.2 and the >=3.1 matchers support TypeScript 3.2 and above, reversing the order could have different behavior, so the above sample would not be equivalent to the following.
\njson{\n name: \"package-name\",\n version: \"1.0\",\n types: \"./index.d.ts\",\n typesVersions: {\n // NOTE: this doesn't work!\n \">=3.1\": { \"*\": [\"ts3.1/*\"] },\n \">=3.2\": { \"*\": [\"ts3.2/*\"] },\n },\n}
Packages under the @types organization are published automatically from DefinitelyTyped using the types-publisher tool.\nTo get your declarations published as an @types package, please submit a pull request to DefinitelyTyped.\nYou can find more details in the contribution guidelines page.
","headings":[{"value":"Including declarations in your npm package","depth":2},{"value":"Dependencies","depth":2},{"value":"Red flags","depth":2},{"value":"///