skymakerolof / dts-builder

Builds a single d.ts file library from generated d.ts sources

DTS-Builder

Project status

Note: This project is in mainteinance mode.

This tool was created to help with a TS library that I was writing. However, I am no longer part of this project and also it seems that there are actively maintained tools out there that do the job in a smarter way than concanetation + regexp replacements.

If you are using dts-builder and find bugs, I'd be happy to fix them. If you want to improve, please create pull requests or fork and hack away :)

Rollup

If you are using Rollup to bundle your code, consider using https://github.com/Swatinem/rollup-plugin-dts plugin, it looks quite promising.

Synopsis

Assembles a singe library definition file by concatenating and cleaning up generated .d.ts files.

Returns a promise with the names of bundles that have been exported.

Code Example

const path = require('path');
const dtsBuilder = require('dts-builder');

const projectRoot = path.resolve(__dirname, '../..');

dtsBuilder.generateBundles([
  {
    name: 'myLib',
    sourceDir: `${projectRoot}/ts-built/`,
    destDir: `${projectRoot}/dist`,
    externals: [
      `${projectRoot}/src/ext/external-lib.d.ts`,
      `${projectRoot}/src/lib/types.d.ts`
    ]
  }
]);

Running this script will read all TS declaration files from sourceDir (${sourceDir}/**/*.d.ts), concatenate them and clean up the result. It will then be wrapped with a name module declaration (declare module ${name} { ... }). The result will be saved as ${name}.d.ts in destDir.

Additionally, if externals array is provided, all the files that are referenced by it will be prepended to the top of the resulting library file as /// <reference path="${basename(externals[i])}" /> and these files will be copied to destDir alongside the library file.

Motivation

A project that I am involved in has a large library that is being build using concatenation of ES5 files into a single .js package. The team moved to ES6 with modules, and I wanted to take it one notch further, and convert the 12k lines of code to TypeScript, for all the benefits.

However, I didn't find a good way to generate a single definition file that will act as a library. I started by playing with the generated d.ts files for each transpiled file to see how this can be achieved, and I created this simple script to remove and modify the result so it will be parsed well by tsc and will allow importing of the namespace.

Installation

npm install --save-dev dts-builder

API Reference

module dtsBuilder {
    function generateBundles(bundles: Array<Bundle>): Promise<Array<string>>;

    interface Bundle {
        /**
          * Bundle name. Used for d.ts filename and the wrapping namespace.
          * @type {string}
          */
        name: string;

        /**
          * Location in which to search for *.d.ts files
          * @type {string}
          */
        sourceDir: string;

        /**
          * Location in which to save the output, under the name: `${name}.d.ts`
          * @type {string}
          */
        destDir: string;

        /**
          * List of external d.ts files that will be copied to the destination
          * directory, and will be referenced from withing the main d.ts file
          * @type {Array<string>}
          */
        externals?: Array<string>;

        /**
          * Wrap resulting definitions in a namespace. Set to false if files are already wrapped
          * by namespaces.
          * Default: true
          * @type {boolean}
          */
        wrap?: boolean;

        /**
          * If specified, library will exported as the given value, as an alias together
          * with the original name.
          * @type {string}
          */
        alias?: string;
    }
}

Tests

Currently test is basic, checking for required module and builds the generate-self package under two names.

Contributors

Feel free to fork, improve and send PRs if it's generic in nature.

License

MIT © Boris Aranovič