Generates a definition library file from generated .d.ts sources

Usage no npm install needed!

<script type="module">
  import dtsBuilder from 'https://cdn.skypack.dev/dts-builder';



Modern NodeJS TypeScript Modern JavaScript MIT License

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 :)


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


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, '../..');

    name: 'myLib',
    sourceDir: `${projectRoot}/ts-built/`,
    destDir: `${projectRoot}/dist`,
    externals: [

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.


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.


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;


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


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


MIT © Boris Aranovič