@quip/dts-bundle-generator

Quip instructions

We keep the master branch in sync with the original timocov project (with the exception of the commit that modified this README) then use branches named after each released version alongside tags.

Here are instructions for how to checkout, modify, and publish the code:

# If you haven't added the original project as a remote already.
> git remote add timocov https://github.com/timocov/dts-bundle-generator

# If you haven't logged into npm already.
> npm login
username: ospreyquip
password: p4ssw0rd # get the real password from LastPass :-)
email: [e-mail]

# 1. Fetch the newest version.
> git fetch -a

# 2. Fast-forward our master.
> git checkout master
> git rebase timocov/master
> git push -f

# 3. Create a new branch based on the most recent quip branch.
# If the minor version on master has incremented then use that
# as the new version (A), otherwise bump the patch version (B).
> git tag | grep quip- | tail -n1
quip-v6.1.0
> git tag | grep -v quip- | tail -n1
# A:
v6.2.0
> git checkout --track origin/quip-v6.1.0 -b quip-v6.2.0
# B:
v6.1.0
> git checkout --track origin/quip-v6.1.0 -b quip-v6.1.1

# 4. Rebase onto master to get the most recent version of the code.
# There will probably be some package.json conflicts, but we're
# about to resolve that.
> git rebase master

# 5. Set the version of the package to correspond to the version
# that you used in step 4.
> vim package.json

# 6. Make your changes, commit, then tag with our new version.
> git commit -am "Made changes XYZ"
> git tag quip-v6.2.0
> git push --tags

# 7. When you're ready to release, test your code, then publish.
> npm test
> npm run prepare-release
> npm publish

# 8. The prepare-release step above will have modified package.json,
# so restore it back again.
> git checkout HEAD package.json

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.js [options] <file(s)>

Options:
  --help                         Show help                                                 [boolean]
  --out-file, -o                 File name of generated d.ts                                [string]
  --verbose                      Enable verbose logging                   [boolean] [default: false]
  --silent                       Disable any logging except errors        [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 package names from node_modules to inline typings from.
                                 Used types will be inlined into the output file             [array]
  --external-imports             Array of package names from node_modules to import typings from.
                                 Used types will be imported using "import { First, Second } from
                                 'library-name';".
                                 By default all libraries will be imported (except inlined libraries
                                 and libraries from @types)                                  [array]
  --external-types               Array of package names from @types to import typings from via the
                                 triple-slash reference directive.
                                 By default all packages are allowed and will be used according to
                                 their usages                                                [array]
  --umd-module-name              Name of the UMD module. If specified then `export as namespace
                                 ModuleName;` will be emitted                               [string]
  --project                      Path to the tsconfig.json file that will be used for the
                                 compilation                                                [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]
  --inline-declare-externals     Enables inlining of `declare module` statements of the global
                                 modules (e.g. `declare module 'external-module' {}`, but NOT
                                 `declare module './internal-module' {}`) contained in files which
                                 should be inlined (all local files and packages from inlined
                                 libraries)                               [boolean] [default: false]
  --disable-symlinks-following   (EXPERIMENTAL) Disables resolving of symlinks to the original path.
                                 See https://github.com/timocov/dts-bundle-generator/issues/39 for
                                 more information                         [boolean] [default: false]
  --respect-preserve-const-enum  Enables stripping the `const` keyword from every direct-exported
                                 (or re-exported) from entry file `const enum`. See
                                 https://github.com/timocov/dts-bundle-generator/issues/110 for more
                                 information                              [boolean] [default: false]
  --export-referenced-types      By default all interfaces, types and const enums are marked as
                                 exported even if they aren't exported directly. This option allows
                                 you to disable this behavior so a node will be exported if it is
                                 exported from root source file only.      [boolean] [default: true]
  --config                       File path to the generator config file                     [string]
  --no-banner                    Allows remove "Generated by dts-bundle-generator" comment from the
                                 output                                   [boolean] [default: false]
  --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 path/to/your/entry-file.ts path/to/your/entry-file-2.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

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:

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. A is not used at all and most probably you do not want to export it.
2. 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.

Contributors

Code Contributors

This project exists thanks to all the people who contribute.

Financial Contributors

Become a financial contributor and help us sustain our community. [Contribute]

Individuals

Organizations

Support this project with your organization. Your logo will show up here with a link to your website. [Contribute]