35

Is there a way to add typescript definitions (.d.ts files) to a pure javascript project directly (e.g. in package.json). I can't find any documentation on that.

Michael_Scharf
  • 33,154
  • 22
  • 74
  • 95

2 Answers2

29

There is a page in the TypeScript Handbook on adding typings to an NPM Package. I'll copy and paste here:

Typings for NPM Packages

The TypeScript compiler resolves Node module names by following the Node.js module resolution algorithm. TypeScript can also load typings that are bundled with npm packages. The compiler will try to discover typings for module foo using the following set of rules:

Try to load the package.json file located in the appropriate package folder (node_modules/foo/). If present,read the path to the typings file described in the typings field. For example, in the following package.json, the compiler will resolve the typings at node_modules/foo/lib/foo.d.ts

   {
       "name": "foo",
       "author": "Vandelay Industries",
       "version": "1.0.0",
       "main": "./lib/foo.js",
       "typings": "./lib/foo.d.ts"
   }

Try to load a file named index.d.ts located in the package folder (node_modules/foo/) - this file should contain typings for the package.

The precise algorithm for module resolution can be found here.

Your definition files should

  • be .d.ts files
  • be written as external modules
  • not contain triple-slash references

The rationale is that typings should not bring new compilable items to the set of compiled files; otherwise actual implementation files in the package can be overwritten during compilation. Additionally, loading typings should not pollute global scope by bringing potentially conflicting entries from different version of the same library.

Lena Schimmel
  • 7,203
  • 5
  • 43
  • 58
rgvassar
  • 5,635
  • 1
  • 24
  • 31
  • 3
    Seems it should be `types` not `typings`. – Drew Noakes May 14 '17 at 19:22
  • 3
    It was `typings` when I answered the question. Here's the [archive](https://web.archive.org/web/20160412204540/https://www.typescriptlang.org/docs/handbook/typings-for-npm-packages.html). Also, from the current documentation: `Note that the "typings" field is synonymous with "types", and could be used as well.` – rgvassar May 18 '17 at 18:52
  • 4
    Thanks for the back story. All current examples online use `types`. If you haven't already, consider updating your answer. – Drew Noakes May 23 '17 at 14:10
  • Nice seinfeld Reference. – CoderDake Feb 26 '19 at 21:24
  • Thanks Ben. I updated the link to the corresponding page that contains the corresponding information. – rgvassar Sep 02 '20 at 20:43
  • 2
    I have not changed the field from "typings" to "types" because the current documentation says that they are synonymous. We have another answer that uses "types". I prefer to have two different answers that both work, rather than two answers that have been edited to be the same. – rgvassar Sep 02 '20 at 20:47
  • `Vandelay Industries` Isn't that owned by Art Vandelay? The importer exporter? – MonkeyDreamzzz Feb 10 '23 at 14:21
6

Visual Studio 2015 will not recognize the definition file unless you use the types property in package.json
https://www.typescriptlang.org/docs/handbook/declaration-files/publishing.html

{
   "name": "awesome",
   "author": "Vandelay Industries",
   "version": "1.0.0",
   "main": "./lib/main.js",
   "types": "./lib/main.d.ts"
}

*You will have to use the three slashes include reference path in your ts files.
/// <reference path="../node_modules/../lib/main.d.ts" />

For anyone else landing here & wanting to link types to their npm package, a handy tutorial that might help!

Niket Pathak
  • 6,323
  • 1
  • 39
  • 51
Sagi
  • 8,972
  • 3
  • 33
  • 41
  • From the link you have provided: `Note that the "typings" field is synonymous with "types", and could be used as well.` – Izhaki Mar 14 '17 at 17:30