With TypeScript 3.7, TypeScript added support for generating .d.ts files from JavaScript using JSDoc syntax.
This set up means you can own the editor experience of TypeScript-powered editors without porting your project to TypeScript, or having to maintain .d.ts files in your codebase. TypeScript supports most JSDoc tags, you can find the reference here.
Setting up your Project to emit .d.ts files
To add creation of .d.ts files in your project, you will need to do up-to four steps:
- Add TypeScript to your dev dependencies
- Add a
tsconfig.json
to configure TypeScript - Run the TypeScript compiler to generate the corresponding d.ts files for JS files
- (optional) Edit your package.json to reference the types
Adding TypeScript
You can learn how to do this in our installation page.
TSConfig
The TSConfig is a json5 file which configures both your compiler flags, and declare where to find files. In this case, you will want a file like the following:
json{ // Change this to match your project include: ["src/**/*"], compilerOptions: { // Tells TypeScript to read JS files, as // normally they are ignored as source files allowJs: true, // Generate d.ts files declaration: true, // This compiler run should // only output d.ts files emitDeclarationOnly: true, // Types should go into this directory. // Removing this would place the .d.ts files // next to the .js files outDir: "dist", }, }
You can learn more about the options in the tsconfig reference.
Run the compiler
You can learn how to do this in our installation page.
You want to make sure these files are included in your package if you have the files in your project’s .gitignore
.
Editing the package.json
TypeScript replicates the node resolution for modules in a package.json
, with an additional step for finding .d.ts files.
Roughly, the resolution will first check the optional "types"
field, then the "main"
field, and finally will try index.d.ts
in the root.
Package.json | Location of default .d.ts |
---|---|
No “types” field | checks “main”, then index.d.ts |
“types”: “main.d.ts” | main.d.ts |
“types”: “./dist/main.js” | ./main/main.d.ts |
If absent, then “main” is used
Package.json | Location of default .d.ts |
---|---|
No “main” field | index.d.ts |
“main”:“index.js” | index.d.ts |
“main”:“./dist/index.js” | ./dist/index.d.ts |
Tips
- If you’d like to write tests for your .d.ts files, try tsd