declaration-bundler-webpack-plugin

Description

This library takes separate declaration asset files generated by the webpack build process and bundles them into one single declaration file. However it does so by recomposing the separate declarations as if all the classes and interfaces were defined as an internal module. Therefor, using this plugin only makes sense if you expose the classes and interfaces to the global module space yourself.

Warning

This is an expirimental setup, you probably want to use either internal modules or external modules only, and then this library will be of no use, besides perhaps as inspiration to make another Plugin that combines declaration files.

When to use this

This plugin, with a setup as below, lets an external module mimic an internal module. The usecase this was created for is to load modules in separate files while also being able to map prefixed URI's (like foaf:Image) back to a module path (my.modules.rdfs.Image). Only in the rare case you want to do something similar, this may be helpful.

Options:

• out: the path where the combined declaration file should be saved.
• moduleName: the name of the internal module to generate
• excludedReferences: an array with which references you want to exclude from the final declaration file.

Requirements:

This plugin was developed as an extention to the ts-loader which - when declaration is set to true in tsconfig.json - generates separate declaration files for each source file. In theory though, it should work with any loader which generates declaration files as output.

Here is an example setup:

//init.ts
import Foo = require('./foo');
import Foo2 = require('./foo2');
var register:Function = (function()
{
    some.path['moduleName'] = {
        "Foo": Foo,
        "Foo2" : Foo2,
    }
    return function(){};
})();
export = register;

//foo.ts
export class Foo {
    bar():boolean { return true; }
}

//foo2.ts
import Foo = require('./foo');
export class Foo2 extends Foo {
    bar():boolean { return true; }
}

Which generates (when using the declaration=true flag for the typescript compiler)

//init.d.ts
var register: Function;
export = register;

//foo.d.ts
declare class Foo {
    bar():boolean;
}
export = Foo;

//foo2.d.ts
import Foo = require('./foo');
declare class Foo2 extends Foo{
    bar():boolean;
}
export = Foo2;

Which with the following webpack.config.js

var DeclarationBundlerPlugin = require('declaration-bundler-webpack-plugin');
module.exports = {
    entry: './src/init.ts',
    output: {
        filename: './builds/bundle.js'
    },
    resolve: {
        extensions: ['', '.ts', '.tsx','.webpack.js', '.web.js', '.js']
    },
    module: {
        loaders: [
            { test: /\.ts(x?)$/, loader: 'ts-loader' }
        ]
    },
    watch:true,
    plugins: [
        new DeclarationBundlerPlugin({
            moduleName:'some.path.moduleName',
            out:'./builds/bundle.d.ts',
        })
    ]
}

Will be turned into:

//bundle.d.ts
declare module some.path.moduleName {

    var register: Function;

    class Foo {
        bar():boolean;
    }

    class Foo2 extends Foo {
        bar():boolean;
    }
}

With this setup and generated declaration file, other modules that want to use this module can add a reference to the generated bundle.d.ts. Then they can access all classes of the module as if they are defined in the global path like with internal typescript modules:

///<reference path="path/to/bundle.d.ts" />
var foo:some.path.moduleName.Foo = new some.path.moduleName.Foo();

When you finally load bundle.js in the browser, the register function is called automatically, which will make the classes available in the global module path so that other modules can access the classes as they expected from the declaration file.