DTS Bundle Generator

Small tool to generate a dts bundle from your ts code.

For example:

// a.ts
export class A {}

// b.ts
export class B {}

// entry.ts
import { A } from './a';
import { B } from './b';

declare function makeA(): A;
export function makeB(): B {
    makeA();
    return new B();
}

When you run dts-bundle-generator -o my.d.ts entry.ts in my.d.ts you will get the following:

declare class B {
}
export declare function makeB(): B;

Installation

1. Install the package from npm:

   npm install --save-dev dts-bundle-generator

   or

   npm install -g dts-bundle-generator

2. Enable declaration compiler option in tsconfig.json

Usage

Usage: dts-bundle-generator [options] <file>

Options:
  --help              Show help                                        [boolean]
  --out-file, -o      File name of generated d.ts                       [string]
  --verbose           Enable verbose logging          [boolean] [default: false]
  --no-check          Skip validation of generated d.ts file
                                                      [boolean] [default: false]
  --fail-on-class     Fail if generated dts contains class declaration
                                                      [boolean] [default: false]
  --external-inlines  Array of the package names from node_modules to inline
                      typings from it.
                      Used types will just be inlined into output file   [array]
  --external-imports  Array of the package names from node_modules to import
                      typings from it.
                      Used types will be imported by "import { First, Second }
                      from 'library-name';".
                      By default all libraries will be imported (except inlined)
                                                                         [array]
  --external-types    Array of the package names from @types to import typings
                      from it via triple-slash reference directive.
                      By default all packages are allowed and will be used
                      according their usages                             [array]
  --umd-module-name   The name of UMD module. If specified `export as namespace
                      ModuleName;` will be emitted                      [string]
  --project           The path to a tsconfig.json file that will be used to
                      compile files                                     [string]
  --sort              Sort output nodes               [boolean] [default: false]
  --config            File path to generator config file
  --version           Show version number                              [boolean]

Examples:

./node_modules/.bin/dts-bundle-generator -o my.d.ts path/to/your/entry-file.ts

./node_modules/.bin/dts-bundle-generator --external-inlines=@mycompany/internal-project --external-imports=@angular/core,rxjs path/to/your/entry-file.ts

./node_modules/.bin/dts-bundle-generator --external-types=jquery path/to/your/entry-file.ts

Why

If you have modules you can create definitions by default via tsc, but tsc generates them for each module separately. Yeah, you can use outFile (for amd and system) but generated code looks like this:

declare module "a" {
    export class A {
    }
}
declare module "b" {
    export class B {
    }
}
declare module "entry" {
    import { B } from "b";
    export function makeB(): B;
}

but:

1. There is not a single usage of A (maybe you do not want to export it?)

2. If you bundle your code this way all the modules are merged (like when using Webpack or Rollup) and there are no such modules as a or b (actually entry too).

Known limitations

1. Do not rename types when import. If you use something like this:

   import { A as B } from './b';
   export C extends B {}

   you will get an error because this tool does not follow your renaming (and actually cannot).

2. Do not use types from * as name-imports:

   import * as someName from './some';
   export class A extends someName.SomeClass {}

   This case is very similar to the previous one.

   NOTE: some libraries with typings in @types (for example react or react-dom) has named exported namespace. As soon typings for this libraries will be imported via triple-slash directive you should import this libraries with renaming. For example for source

   import * as ReactDOM from 'react-dom';
   export interface MyRenderer extends ReactDOM.Renderer {}

   generated dts will be

   /// <reference types="react" />
   /// <reference types="react-dom" />
   
   export interface MyRenderer extends ReactDOM.Renderer {
   }

   So please make sure that your * as name-import has right name.

3. All your types should have different names inside a bundle. If you have 2 interface Options {} they will be merged by TypeScript and you will get wrong definitions.