dts-bundle-generator/README.md

[![npm version](https://badge.fury.io/js/dts-bundle-generator.svg)](https://badge.fury.io/js/dts-bundle-generator) [![Build Status](https://travis-ci.org/timocov/dts-bundle-generator.svg?branch=master)](https://travis-ci.org/timocov/dts-bundle-generator)

# DTS Bundle Generator

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

For example:

```ts
// a.ts
export class A {}
```

```ts
// b.ts
export class B {}
```

```ts
// 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:

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

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

```
Usage: dts-bundle-generator.js [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 and
                                libraries from @types)                                       [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]
  --inline-declare-global       Enables inlining of `declare global` statements contained in files
                                which should be inlined (all local files and packages from
                                `--external-inlines`)                     [boolean] [default: false]
  --disable-symlinks-following  (EXPERIMENTAL) Disables resolving symlinks to original path. See
                                https://github.com/timocov/dts-bundle-generator/issues/39 to more
                                information                               [boolean] [default: false]
  --config                      File path to generator config file
  --version                     Show version number                                        [boolean]
```

Examples:

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

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

```bash
./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:

```ts
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?)

1. 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:

    ```ts
    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).

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

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

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

    generated dts will be

    ```ts
    /// <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`.

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.