DTS Bundle Generator

A tool to generate a single bundle of dts with types tree-shaking

Module - bundlerTypes
timocov/dts-bundle-generatordts-bundle-generator

README


DTS Bundle Generator


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

For example:

  1. ```ts
  2. // a.ts
  3. export class A {}
  4. ```

  1. ```ts
  2. // b.ts
  3. export class B {}
  4. ```

  1. ```ts
  2. // entry.ts
  3. import { A } from './a';
  4. import { B } from './b';

  6. declare function makeA(): A;
  7. export function makeB(): B {
  8.     makeA();
  9.     return new B();
  10. }
  11. ```

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

  1. ```ts
  2. declare class B {
  3. }
  4. export declare function makeB(): B;
  5. ```

Installation


1. Install the package from npm:

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

    or

    bash
    npm install -g dts-bundle-generator
    

1. Enable declaration compiler option in tsconfig.json

Usage


  1. ```
  2. Usage: dts-bundle-generator [options] <file(s)>

  4. Options:
  5.   --help                         Show help                                                 [boolean]
  6.   --out-file, -o                 File name of generated d.ts                                [string]
  7.   --verbose                      Enable verbose logging                   [boolean] [default: false]
  8.   --silent                       Disable any logging except errors        [boolean] [default: false]
  9.   --no-check                     Skip validation of generated d.ts file   [boolean] [default: false]
  10.   --fail-on-class                Fail if generated dts contains class declaration
  11.                                                                           [boolean] [default: false]
  12.   --external-inlines             Array of package names from node_modules to inline typings from.
  13.                                  Used types will be inlined into the output file             [array]
  14.   --external-imports             Array of package names from node_modules to import typings from.
  15.                                  Used types will be imported using "import { First, Second } from
  16.                                  'library-name';".
  17.                                  By default all libraries will be imported (except inlined libraries
  18.                                  and libraries from @types)                                  [array]
  19.   --external-types               Array of package names from @types to import typings from via the
  20.                                  triple-slash reference directive.
  21.                                  By default all packages are allowed and will be used according to
  22.                                  their usages                                                [array]
  23.   --umd-module-name              Name of the UMD module. If specified then `export as namespace
  24.                                  ModuleName;` will be emitted                               [string]
  25.   --project                      Path to the tsconfig.json file that will be used for the
  26.                                  compilation                                                [string]
  27.   --sort                         Sort output nodes                        [boolean] [default: false]
  28.   --inline-declare-global        Enables inlining of `declare global` statements contained in files
  29.                                  which should be inlined (all local files and packages from
  30.                                  `--external-inlines`)                    [boolean] [default: false]
  31.   --inline-declare-externals     Enables inlining of `declare module` statements of the global
  32.                                  modules (e.g. `declare module 'external-module' {}`, but NOT
  33.                                  `declare module './internal-module' {}`) contained in files which
  34.                                  should be inlined (all local files and packages from inlined
  35.                                  libraries)                               [boolean] [default: false]
  36.   --disable-symlinks-following   (EXPERIMENTAL) Disables resolving of symlinks to the original path.
  37.                                  See https://github.com/timocov/dts-bundle-generator/issues/39 for
  38.                                  more information                         [boolean] [default: false]
  39.   --respect-preserve-const-enum  Enables stripping the `const` keyword from every direct-exported
  40.                                  (or re-exported) from entry file `const enum`. See
  41.                                  https://github.com/timocov/dts-bundle-generator/issues/110 for more
  42.                                  information                              [boolean] [default: false]
  43.   --export-referenced-types      By default all interfaces, types and const enums are marked as
  44.                                  exported even if they aren't exported directly. This option allows
  45.                                  you to disable this behavior so a node will be exported if it is
  46.                                  exported from root source file only.      [boolean] [default: true]
  47.   --config                       File path to the generator config file                     [string]
  48.   --no-banner                    Allows remove "Generated by dts-bundle-generator" comment from the
  49.                                  output                                   [boolean] [default: false]
  50.   --version                      Show version number                                       [boolean]
  51. ```

Examples:

  1. ```bash
  2. ./node_modules/.bin/dts-bundle-generator -o my.d.ts path/to/your/entry-file.ts
  3. ```

  1. ```bash
  2. ./node_modules/.bin/dts-bundle-generator path/to/your/entry-file.ts path/to/your/entry-file-2.ts
  3. ```

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

  1. ```bash
  2. ./node_modules/.bin/dts-bundle-generator --external-types=jquery path/to/your/entry-file.ts
  3. ```

Config file


It is unnecessary, but you can use config file for the tool. See config documentation for more information.

Why


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

  1. ```ts
  2. declare module "a" {
  3.     export class A {
  4.     }
  5. }
  6. declare module "b" {
  7.     export class B {
  8.     }
  9. }
  10. declare module "entry" {
  11.     import { B } from "b";
  12.     export function makeB(): B;
  13. }
  14. ```

but:

1. A is not used at all and most probably you do not want to export it.
1. If you bundle your code in a way when all modules are merged (like when using Webpack or Rollup) then there should be no such modules as a or b (actually entry too) in the resulting file.

Known limitations


1. 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 (see https://github.com/timocov/dts-bundle-generator/issues/116 and https://github.com/timocov/dts-bundle-generator/issues/130)
1. Importing and exporting with renaming in modules outside of entry points is limited/not supported as yet (see https://github.com/timocov/dts-bundle-generator/issues/184)