dts-gen: A TypeScript Definition File Generator
dts-gen works differently from TypeScript, Flowtype, Tern, etc. because it simply examines the objects as they appear at runtime, rather than needing the source code that creates the object.
This means no matter how the object was written, anything, including native objects, can be given an inferred shape.
This trade-off comes with a price -- you'll see a lot of
anys in function parameters and return types.
You may also see properties that are not intended for public use.
dts-gen is meant to be a starting point for writing a high-quality definition file.
How do I use it?
dts-gen can operate on NPM modules, arbitrary identifiers, or arbitrary expressions.
If you are generating a .d.ts file for a node module, the best way is to use the
dts-gen commandline tool.
Some libraries only load in browsers; for this you can use the console-launched pop-up window.
Let's generate a .d.ts file for the
yargs NPM module.
This already has a handwritten definition file, but let's pretend that doesn't exist yet.
You'll need to first install
dts-gen if you haven't already, then globally install the module you're generating for.
> npm install -g dts-gen> npm install -g yargs> dts-gen -m yargs
This will generate a file
Here's what it looks like
As you can see,
dts-gen produced the correct module shape for the node module.
The function arguments got their correct names and arity, though it didn't detect that
cwd is optional.
The parameter types are
any, which is fine, and we can read the
yargs documentation to find out what types it actually accepts.
Here's the commandline help you'll see when running
Usage: dts-gen input [settings] [output] Input Options: -m[odule] fs The "fs" node module (must be installed) -i[dentifier] Math The global variable "Math" -e[xpression] "new C()" The expression "new C()" -t[emplate] module Name of a template. Templates are: global-modifying-module, global-plugin, global, module-class, module-function, module-plugin, module Settings: -n[ame] n The name to emit when generating for an expression Output Options: -f[ile] [filename.d.ts] Write to a file (default) -d[t] [dirName] Create a folder suitable for DefinitelyTyped -s[tdout] Write to stdout -o[verwrite] Allow overwriting files Example: dts-gen -m fs
Only one of the following inputs may be specified.
The name of the node module to generate a file for.
This string will be
require'd at runtime, so the normal nodejs rules about the module needing to be installed still apply.
A bare identifier to generate a file for.
Certain dotted names will work here.
This string will be
eval'd to get the value.
--expression "new Date()"
An arbitrary expression to generate a file for.
By default, this will be assigned to the name
dts_gen_expr and generated as
You can use the
-name parameter to change this.
var fs = ;fs;
A file containing arbitrary expression to generate a file for.
The file will be named
The contents of the file will be
eval'd, and the last statement in the file will be the value used.
--name parameter changes the global name given to the inferred result.
At most one output option may be specified.
If no output option is given, the default is
Sets the filename to write to. If no filename is specified, the name will be inferred from the module or identifier name.
Writes the output to
Creates a folder suitable for submitting to DefinitelyTyped.
Before submitting, you'll need to write some tests and fill in the header comments in
You may change the name of the folder by specifing an argument, otherwise the folder name will be inferred.
- Clone DefinitelyTyped.
- Run dts-gen; eg
dts-gen --dt --name yargs
dts-gen will not overwrite existing files on disk.
-o to allow overwriting of files.
|📝 Note: Browser support in progress! This is not quite ready yet.|
To generate a definition file for a browser-only module, we'll use the in-browser popup window.
This works by injecting the
dts-gen script into the current page by adding it as a
Run this in your browser's developer console:
var s = document; ssrc = ''; documentbody;
If this script is blocked by the same-origin content policy of the page, go to https://microsoft.github.io/dts-gen/manual.html and copy the script text shown on the page. Paste this into the browser console.
When the window appears, enter an identifier or expression in the textbox and click "Generate".
You can then copy and paste the contents of the textarea into a definition file.