gulp-ts-package
v1.1.2
Published
Renames modules as a package in a compiled typescript bundle (system or amd).
Downloads
98
Maintainers
Readme
gulp-ts-package
Renames modules as a package in a compiled typescript bundle (system or amd).
Install
npm install --save-dev gulp-ts-package
Usage
gulpfile.js
let gulp = require("gulp");
let ts = require('gulp-typescript');
let tsPackage = require('gulp-ts-package').default;
gulp.task("build", function () {
let tsProject = ts.createProject({ module: "amd", outFile: "bundle.amd.js" });
return gulp.src("src/**/*.ts")
.pipe(tsProject())
// Assuming your main module is at: src/index.ts
.pipe(tsPackage({ name: "my-library", mainModule: "index" }))
.pipe(gulp.dest("lib/"));
]);
});
Minify module names
Enabling minify will change the name of non-root modules.
The new name will be numbered after the package name. Example: "myPackage/1".
gulpfile.js
let gulp = require("gulp");
let ts = require('gulp-typescript');
let tsPackage = require('gulp-ts-package').default;
gulp.task("build", function () {
let tsProject = ts.createProject({ module: "amd", outFile: "bundle.amd.js" });
return gulp.src("src/**/*.ts")
.pipe(tsProject())
// Assuming your main module is at: src/index.ts
.pipe(tsPackage({
name: "my-library",
mainModule: "index",
minify: {
enabled: true,
// Optional:
ignoredModules: ["ModuleC"]
}
}))
.pipe(gulp.dest("lib/"));
]);
});
How to bundle with typescript compiler?
Use the "outFile" parameter in the tsconfig.
https://www.typescriptlang.org/docs/handbook/compiler-options.html
Why bundle with typescript compiler?
If you are building a typescript library, you can:
- Avoid using bundling tools (webpack, rollup, systemjs builder, jspm, browserify).
- Avoid using transpilers (babel).
- Easily support all (or most) of the clients (node, browser, bundling tools, etc.).
- Works fast.
- Easier to maintain.
Why is the module rename needed?
The original bundle file registers the modules by relative names, For example: "index".
Problems:
- Those relative names can easily collide with other modules - from your app or other libraries.
- Absolute import (for example:
import * as myLib from "my-lib";
) will not work in the browser (out of the box).- For this to work, the main module in the bundle needs to be registered as the library name ("my-lib" in the example).
Notice that developers who uses bundling tools (like webpack), can avoid those issues by consuming and bundling the commonjs format of your library. The downside is performance.
I personally try to devide my application to libraries when possible.
That way I can enjoy smaller scope, faster builds and test runs, modularity, reusabilty, and more...
All while keeping the maintanence relatively low (for example, short gulpfile.js).
For this approach, this library is very helpful.
Output Examples
You can see the source code of the files used in this example. The files are in the repository.
System
Before
... // Some helper function might be here.
System.register("folder2/B", ["folder1/A"], function (exports_1, context_1) { ...
System.register("folder1/A", ["folder2/B"], function (exports_2, context_2) { ...
System.register("index", ["folder1/A", "folder2/B"], function (exports_3, context_3) { ...
After
... // Some helper function might be here.
System.register("my-library/folder2/B", ["my-library/folder1/A"], function (exports_1, context_1) { ...
System.register("my-library/folder1/A", ["my-library/folder2/B"], function (exports_2, context_2) { ...
System.register("my-library", ["my-library/folder1/A", "my-library/folder2/B"], function (exports_3, context_3) { ...
AMD
Before
... // Some helper function might be here.
define("folder2/B", ["require", "exports", "folder1/A"], function (require, exports, A_1) { ...
define("folder1/A", ["require", "exports", "folder2/B"], function (require, exports, B_1) { ...
define("index", ["require", "exports", "folder1/A", "folder2/B"], function (require, exports, A_2, B_2) { ...
After
... // Some helper function might be here.
define("my-library/folder2/B", ["require", "exports", "my-library/folder1/A"], function (require, exports, A_1) { ...
define("my-library/folder1/A", ["require", "exports", "my-library/folder2/B"], function (require, exports, B_1) { ...
define("my-library", ["require", "exports", "my-library/folder1/A", "my-library/folder2/B"], function (require, exports, A_2, B_2) { ...