Nosy Pinocchio Manners


    0.6.0 • Public • Published

    npm version

    dts-gen: A TypeScript Definition File Generator

    dts-gen is a tool that generates TypeScript definition files (.d.ts) from any JavaScript object.

    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 yargs.d.ts. Here's what it looks like

    export = yargs;
    declare function yargs(processArgs: any, cwd: any): any;
    declare namespace yargs {
        const $0: string;
        const argv: {
            $0: string;
    // ... more

    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.

    Command-line options

    Here's the commandline help you'll see when running dts-gen:

    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
      -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

    Input Options

    Only one of the following inputs may be specified.

    --module (-m)

    Example: --module express

    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.

    --identifier (-i)

    Example: --identifier Math

    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 (-e)

    Example: --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 dts_gen_expr.d.ts. You can use the -name parameter to change this.


    Example: --expression-file "expressions.js"

    var fs = require('fs');

    A file containing arbitrary expression to generate a file for. The file will be named ${basename}.d.ts, i.e. expressions.d.ts. The contents of the file will be eval'd, and the last statement in the file will be the value used.

    --name (-n)

    Example: --name MyVar

    When using --expression, the --name parameter changes the global name given to the inferred result.

    Output Options

    At most one output option may be specified. If no output option is given, the default is --file.

    --file (-f)

    Example: --file my.d.ts

    Sets the filename to write to. If no filename is specified, the name will be inferred from the module or identifier name.

    --stdout (-s)

    Writes the output to stdout

    --dt (-d)

    Example: --dt or --dt myFolder

    Creates a folder suitable for submitting to DefinitelyTyped. Before submitting, you'll need to write some tests and fill in the header comments in index.d.ts. You may change the name of the folder by specifing an argument, otherwise the folder name will be inferred.

    1. Clone DefinitelyTyped.
    2. cd DefinitelyTyped/types
    3. Run dts-gen; eg dts-gen --dt --name yargs

    --overwrite (-o)

    By default, dts-gen will not overwrite existing files on disk. Specify -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 script tag.

    Run this in your browser's developer console:

    var s = document.createElement('script'); s.src = ''; document.body.appendChild(s);

    If this script is blocked by the same-origin content policy of the page, go to 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".

    TODO: Screenshot

    You can then copy and paste the contents of the textarea into a definition file.



    npm i dts-gen

    DownloadsWeekly Downloads






    Unpacked Size

    44.7 kB

    Total Files


    Last publish


    • ryancavanaugh
    • types