As of SystemJS Builder 0.14, builder.build
and builder.buildTree
are both builder.bundle
, while builder.buildSFX
is now builder.buildStatic
.
The previous APIs will continue to work, but display deprecation warnings.
Note SystemJS Builder 0.11-0.14 correspond to the SystemJS 0.17+ releases which include the breaking change making module names URLs. Read the SystemJS 0.17 release notes for more information on this change.
Provides a single-file build for SystemJS of mixed-dependency module trees.
Builds ES6 into ES5, CommonJS, AMD and globals into a single file in a way that supports the CSP SystemJS loader as well as circular references.
app.js
import $ from "./jquery.js";
export var hello = 'es6';
jquery.js
define(function() {
return 'this is jquery';
});
Will build the module app
into a bundle containing both app
and jquery
defined through System.register
calls.
Circular references and bindings in ES6, CommonJS and AMD all behave exactly as they should, including maintaining execution order.
npm install systemjs-builder
Ensure that the transpiler is installed separately (npm install babel-core
here).
var path = require("path");
var Builder = require('systemjs-builder');
// optional constructor options
// sets the baseURL and loads the configuration file
var builder = new Builder('path/to/baseURL', 'path/to/system/config-file.js');
builder
.bundle('local/module.js', 'outfile.js')
.then(function() {
console.log('Build complete');
})
.catch(function(err) {
console.log('Build error');
console.log(err);
});
Configuration can be injected via builder.config
:
builder.config({
map: {
'a': 'b.js'
}
});
builder.build('a');
To load custom configuration files use builder.loadConfig
:
// `builder.loadConfig` will load config from a file containing `System.config({...})`
builder.loadConfig('./cfg.js')
.then(function() {
// ready to build
});
Multiple config calls can be run, which will combine into the loader configuration.
To reset the loader state and configuration use builder.reset()
.
When config was passed into the new Builder(baseURL, configFile)
constructor, the config will be reset to this exact configFile
state.
To make a bundle that is independent of the SystemJS loader entirely, we can make SFX bundles:
builder.buildStatic('myModule.js', 'outfile.js', options);
This bundle file can then be included with a <script>
tag, and no other dependencies would need to be included in the page.
By default, Traceur or Babel runtime are automatically included in the SFX bundle if needed. To exclude the Babel or Traceur runtime set the runtime
build option to false:
builder.buildStatic('myModule.js', 'outfile.js', { runtime: false });
SFX bundles can also be output as a custom module format - amd
, cjs
or es6
for consumption in different environments.
This is handled via the sfxFormat
option:
builder.buildStatic('myModule.js', 'outfile.js', { sfxFormat: 'cjs' });
The first module used as input (myModule.js
here) will then have its exports output as the CommonJS exports of the whole SFX bundle itself
when run in a CommonJS environment.
To have globals like jQuery
not included, and included in a separate script tag, set up an adapter module something like:
jquery.js
module.exports = window.jQuery;
As well as an options.config
parameter, it is also possible to specify minification and source maps options:
builder.bundle('myModule.js', 'outfile.js', { minify: true, sourceMaps: true, config: cfg });
Compile time with source maps can also be improved with the lowResSourceMaps
option:
builder.bundle('myModule.js', 'outfile.js', { sourceMaps: true, lowResSourceMaps: true });
mangle
, defaults to true.globalDefs
, object allowing for global definition assignments for dead code removal.
builder.bundle('myModule.js', 'outfile.js', { minify: true, mangle: false, globalDefs: { DEBUG: false } });
Leave out the outFile
option to run an in-memory build:
builder.bundle('myModule.js', { minify: true }).then(function(output) {
output.source; // generated bundle source
output.sourceMap; // generated bundle source map
output.modules; // array of module names defined in the bundle
});
The output
object above is provided for all builds, including when outFile
is set.
output.modules
can be used to directly populate SystemJS bundles configuration.
If loading resources that shouldn't even be traced as part of the build (say an external import), these can be configured with:
builder.config({
meta: {
'resource/to/ignore.js': {
build: false
}
}
});
Both builder.build
and builder.buildStatic
support bundle arithmetic expressions. This allows for the easy construction of custom bundles.
NOTE: SFX Bundles can only use addition and wildcard arithmetic.
There is also a builder.trace
for building direct trace tree objects, which can be directly passed into builder.bundle
or builder.buildStatic
.
In this example we build all our application code in app/
excluding the tree app/corelibs
:
var Builder = require('systemjs-builder');
var builder = new Builder({
baseURL: '...',
map: {
} // etc. config
});
builder.bundle('app/* - app/corelibs.js', 'output-file.js', { minify: true, sourceMaps: true });
To build the dependencies in common between two modules, use the &
operator:
builder.bundle('app/page1.js & app/page2.js', 'common.js');
We can then exclude this common bundle in future builds:
builder.bundle('app/componentA.js - common.js', { minify: true, sourceMaps: true });
Build a bundle of all dependencies of the app/
package excluding anything from app/
itself.
For this we can use the [module]
syntax which represents a single module instead of all its dependencies as well:
builder.bundle('app/**/* - [app/**/*]', 'dependencies.js', { minify: true, sourceMaps: true });
The above means take the tree of app and all its dependencies, and subtract just the modules in app, thus leaving us with just the tree of dependencies of the app package.
Instead of using the arithmetic syntax, we can construct the trace ourselves.
In this example we build app/first
and app/second
into two separate bundles, while creating a separate shared bundle:
var Builder = require('systemjs-builder');
var builder = new Builder({
// ...
});
Promise.all([builder.trace('app/first.js'), builder.trace('app/second.js')])
.then(function(trees) {
var commonTree = builder.intersectTrees(trees[0], trees[1]);
return Promise.all([
builder.bundle(commonTree, 'shared-bundle.js')
builder.bundle(builder.subtractTrees(trees[0], commonTree), 'first-bundle.js'),
builder.bundle(builder.subtractTrees(trees[1], commonTree), 'second-bundle.js')
]);
});
MIT