1 | SystemJS Build Tool [![Build Status][travis-image]][travis-url] [![Support](https://supporterhq.com/api/b/33df4abbec4d39260f49015d2457eafe/SystemJS)](https://supporterhq.com/support/33df4abbec4d39260f49015d2457eafe/SystemJS)
|
2 | ===
|
3 |
|
4 | _[SystemJS Builder 0.15 release notes](https://github.com/systemjs/builder/releases/tag/0.15.0)_
|
5 |
|
6 | _As of SystemJS Builder 0.14, `builder.build` and `builder.buildTree` are both `builder.bundle`, while `builder.buildSFX` is now `builder.buildStatic`.
|
7 | The previous APIs will continue to work, but display deprecation warnings._
|
8 |
|
9 | _Note SystemJS Builder 0.11-0.14 correspond to the SystemJS 0.17+ releases which include the breaking change making module names URLs.
|
10 | Read the [SystemJS 0.17 release notes](https://github.com/systemjs/systemjs/releases/tag/0.17.0) for more information on this change._
|
11 |
|
12 | Provides a single-file build for SystemJS of mixed-dependency module trees.
|
13 |
|
14 | Builds ES6 into ES5, CommonJS, AMD and globals into a single file in a way that supports the CSP SystemJS loader
|
15 | as well as circular references.
|
16 |
|
17 | Example
|
18 | ---
|
19 |
|
20 | app.js
|
21 | ```javascript
|
22 | import $ from "./jquery.js";
|
23 | export var hello = 'es6';
|
24 | ```
|
25 |
|
26 | jquery.js
|
27 | ```javascript
|
28 | define(function() {
|
29 | return 'this is jquery';
|
30 | });
|
31 | ```
|
32 |
|
33 | Will build the module `app` into a bundle containing both `app` and `jquery` defined through `System.register` calls.
|
34 |
|
35 | Circular references and bindings in ES6, CommonJS and AMD all behave exactly as they should, including maintaining execution order.
|
36 |
|
37 | Documentation
|
38 | ---
|
39 | [API Reference] (docs/api.md)
|
40 |
|
41 | Usage
|
42 | ---
|
43 |
|
44 | ### Install
|
45 |
|
46 | ```javascript
|
47 | npm install systemjs-builder
|
48 | ```
|
49 |
|
50 | ### Basic Use
|
51 |
|
52 | Ensure that the transpiler is installed separately (`npm install babel-core` here).
|
53 |
|
54 | ```javascript
|
55 | var path = require("path");
|
56 | var Builder = require('systemjs-builder');
|
57 |
|
58 | // optional constructor options
|
59 | // sets the baseURL and loads the configuration file
|
60 | var builder = new Builder('path/to/baseURL', 'path/to/system/config-file.js');
|
61 |
|
62 | builder
|
63 | .bundle('local/module.js', 'outfile.js')
|
64 | .then(function() {
|
65 | console.log('Build complete');
|
66 | })
|
67 | .catch(function(err) {
|
68 | console.log('Build error');
|
69 | console.log(err);
|
70 | });
|
71 | ```
|
72 |
|
73 | ### Setting Configuration
|
74 |
|
75 | Configuration can be injected via `builder.config`:
|
76 |
|
77 | ```javascript
|
78 | builder.config({
|
79 | map: {
|
80 | 'a': 'b.js'
|
81 | }
|
82 | });
|
83 | builder.build('a');
|
84 | ```
|
85 |
|
86 | To load custom configuration files use `builder.loadConfig`:
|
87 |
|
88 | ```javascript
|
89 | // `builder.loadConfig` will load config from a file containing `System.config({...})`
|
90 | builder.loadConfig('./cfg.js')
|
91 | .then(function() {
|
92 | // ready to build
|
93 | });
|
94 | ```
|
95 |
|
96 | Multiple config calls can be run, which will combine into the loader configuration.
|
97 |
|
98 | #### Resetting Configuration
|
99 |
|
100 | To reset the loader state and configuration use `builder.reset()`.
|
101 |
|
102 | When config was passed into the `new Builder(baseURL, configFile)` constructor, the config will be reset to this exact `configFile` state.
|
103 |
|
104 | ### Self-Executing (SFX) Bundles
|
105 |
|
106 | To make a bundle that is independent of the SystemJS loader entirely, we can make SFX bundles:
|
107 |
|
108 | ```javascript
|
109 | builder.buildStatic('myModule.js', 'outfile.js', options);
|
110 | ```
|
111 |
|
112 | This bundle file can then be included with a `<script>` tag, and no other dependencies would need to be included in the page. You'll likely want your module
|
113 | to export a global variable when loaded from a script tag, and this can be configured via `globalName`. For example
|
114 |
|
115 | ```javascript
|
116 | builder.buildStatic('src/NavBar.js', 'dist/NavBarStaticBuild.js', {
|
117 | globalName: 'NavBar'
|
118 | });
|
119 | ```
|
120 |
|
121 | will cause the output of your module to be assigned to a global variable named `NavBar`. If you're making a static bundle, while excluding certain dependencies, those dependencies
|
122 | will of course need to have already been loaded on your page, with their own global variables exported. You can match these global variables up with your needed dependencies
|
123 | with `globalDeps`. For example
|
124 |
|
125 | ```javascript
|
126 | builder.buildStatic('src/NavBar.js - react', 'dist/NavBarStaticBuild.js', {
|
127 | globalName: 'NavBar',
|
128 | globalDeps: {
|
129 | 'react': 'React'
|
130 | }
|
131 | });
|
132 | ```
|
133 |
|
134 | will create a static build of NavBar—without React—which, when loaded via a script tag, exports an eponymous global variable, and assumes the existence of a React global variable, which will be used for the `react` dependency.
|
135 |
|
136 | This would support users with a setup of
|
137 |
|
138 | ```javascript
|
139 | <script src='path/to/react.min.js'></script>
|
140 | <script src='path/to/NavBarStaticBuild.js'></script>
|
141 | ```
|
142 |
|
143 | Note that another way of excluding `react` would be with `externals`.
|
144 |
|
145 | ```javascript
|
146 | builder.buildStatic('src/NavBar.js', 'dist/NavBarStaticBuild.js', {
|
147 | externals: ['react'],
|
148 | globalName: 'NavBar',
|
149 | globalDeps: {
|
150 | 'react': 'React'
|
151 | }
|
152 | });
|
153 | ```
|
154 |
|
155 | This would also exclude react but, if react defined any dependencies which NavBar *also* defined, those dependencies would be *included* in the build.
|
156 |
|
157 | Of course the above explanations involving `globalDeps` and `globalName` only apply to when your end user loads the static file from a script tag. Since the output is (by default, see below) UMD, a
|
158 | script loader like SystemJS or requireJS would process it as configured, or via AMD respectively.
|
159 |
|
160 | By default, the 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:
|
161 |
|
162 | ```javascript
|
163 | builder.buildStatic('myModule.js', 'outfile.js', { runtime: false });
|
164 | ```
|
165 |
|
166 | #### SFX Format
|
167 |
|
168 | SFX bundles can also be output as a custom module format - `amd`, `cjs` or `es6` for consumption in different environments.
|
169 |
|
170 | This is handled via the `format` (previously `sfxFormat`) option:
|
171 |
|
172 | ```javascript
|
173 | builder.buildStatic('myModule.js', 'outfile.js', { format: 'cjs' });
|
174 | ```
|
175 |
|
176 | 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
|
177 | when run in a CommonJS environment.
|
178 |
|
179 | #### Adapter Modules
|
180 |
|
181 | To have globals like `jQuery` not included, and included in a separate script tag, set up an adapter module something like:
|
182 |
|
183 | jquery.js
|
184 | ```javascript
|
185 | module.exports = window.jQuery;
|
186 | ```
|
187 |
|
188 | ### Minification & Source Maps
|
189 |
|
190 | As well as an `options.config` parameter, it is also possible to specify minification and source maps options:
|
191 |
|
192 | ```javascript
|
193 | builder.bundle('myModule.js', 'outfile.js', { minify: true, sourceMaps: true, config: cfg });
|
194 | ```
|
195 |
|
196 | Compile time with source maps can also be improved with the `lowResSourceMaps` option, where the mapping granularity is per-line instead of per-character:
|
197 |
|
198 | ```javascript
|
199 | builder.bundle('myModule.js', 'outfile.js', { sourceMaps: true, lowResSourceMaps: true });
|
200 | ```
|
201 |
|
202 | #### Minification Options
|
203 |
|
204 | * `mangle`, defaults to true.
|
205 | * `globalDefs`, object allowing for global definition assignments for dead code removal.
|
206 |
|
207 | ```javascript
|
208 | builder.bundle('myModule.js', 'outfile.js', { minify: true, mangle: false, globalDefs: { DEBUG: false } });
|
209 | ```
|
210 |
|
211 | #### SourceMap Options
|
212 |
|
213 | * `sourceMaps`, Either boolean value (enable/disable) or string value `'inline'` which will inline the SourceMap data as Base64 data URI right in the generated output file (never use in production). *(Default is `false`)*
|
214 | * `sourceMapContents`, Boolean value that determines if original sources shall be directly included in the SourceMap. Using inline source contents generates truely self contained SourceMaps which will not need to load the external original source files during debugging. *(Default is `false`; when using `sourceMaps='inline'` it defaults `true`)*
|
215 |
|
216 |
|
217 | ### In-Memory Builds
|
218 |
|
219 | Leave out the `outFile` option to run an in-memory build:
|
220 |
|
221 | ```javascript
|
222 | builder.bundle('myModule.js', { minify: true }).then(function(output) {
|
223 | output.source; // generated bundle source
|
224 | output.sourceMap; // generated bundle source map
|
225 | output.modules; // array of module names defined in the bundle
|
226 | });
|
227 | ```
|
228 |
|
229 | The `output` object above is provided for all builds, including when `outFile` is set.
|
230 |
|
231 | `output.modules` can be used to directly populate SystemJS bundles configuration.
|
232 |
|
233 | ### Ignore Resources
|
234 |
|
235 | If loading resources that shouldn't even be traced as part of the build (say an external import), these
|
236 | can be configured with:
|
237 |
|
238 | ```javascript
|
239 | builder.config({
|
240 | meta: {
|
241 | 'resource/to/ignore.js': {
|
242 | build: false
|
243 | }
|
244 | }
|
245 | });
|
246 | ```
|
247 |
|
248 | ### Overriding Fetch
|
249 |
|
250 | The framework fetch function can be overridden in order to provide the source for a file manually. This is useful if you want to pre-process the source of a file before using the builder.
|
251 |
|
252 | ```javascript
|
253 | var mySource = 'import * from foo; var foo = "bar";'; // get source as a string
|
254 | builder.bundle('foo.js', {
|
255 | fetch: function (load, fetch) {
|
256 | if (load.name.indexOf('foo.js') !== -1) {
|
257 | return mySource;
|
258 | } else {
|
259 | // fall back to the normal fetch method
|
260 | return fetch(load);
|
261 | }
|
262 | }
|
263 | });
|
264 | ```
|
265 |
|
266 | The `load` variable describes the file that is trying to be loaded. This is called once for every file that is trying to be fetched, including dependencies.
|
267 |
|
268 | The `fetch` function should return a string.
|
269 |
|
270 | ### Bundle Arithmetic
|
271 |
|
272 | Both `builder.build` and `builder.buildStatic` support bundle arithmetic expressions. This allows for the easy construction of custom bundles.
|
273 |
|
274 | There is also a `builder.trace` for building direct trace tree objects, which can be directly passed into `builder.bundle` or `builder.buildStatic`.
|
275 |
|
276 | #### Example - Arithmetic Expressions
|
277 |
|
278 | In this example we build all our application code in `app/` excluding the tree `app/corelibs`:
|
279 |
|
280 | ```javascript
|
281 | var Builder = require('systemjs-builder');
|
282 |
|
283 | var builder = new Builder({
|
284 | baseURL: '...',
|
285 | map: {
|
286 | } // etc. config
|
287 | });
|
288 |
|
289 | builder.bundle('app/* - app/corelibs.js', 'output-file.js', { minify: true, sourceMaps: true });
|
290 | ```
|
291 |
|
292 | #### Example - Common Bundles
|
293 |
|
294 | To build the dependencies in common between two modules, use the `&` operator:
|
295 |
|
296 | ```javascript
|
297 | builder.bundle('app/page1.js & app/page2.js', 'common.js');
|
298 | ```
|
299 |
|
300 | We can then exclude this common bundle in future builds:
|
301 |
|
302 | ```javascript
|
303 | builder.bundle('app/componentA.js - common.js', { minify: true, sourceMaps: true });
|
304 | ```
|
305 |
|
306 | #### Example - Third-Party Dependency Bundles
|
307 |
|
308 | Build a bundle of all dependencies of the `app/` package excluding anything from `app/` itself.
|
309 |
|
310 | For this we can use the `[module]` syntax which represents a single module instead of all its dependencies as well:
|
311 |
|
312 | ```javascript
|
313 | builder.bundle('app/**/* - [app/**/*]', 'dependencies.js', { minify: true, sourceMaps: true });
|
314 | ```
|
315 |
|
316 | 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.
|
317 |
|
318 | #### Example - Multiple Common Bundles
|
319 |
|
320 | Parentheses are supported, so the following would bundle everything in common with `page1` and `page2`, and also everything in common between `page3` and `page4`:
|
321 |
|
322 | ```javascript
|
323 | builder.bundle('(app/page1.js & app/page2.js) + (app/page3.js & app/page4.js)', 'common.js');
|
324 | ```
|
325 |
|
326 | #### Example - Direct Trace API
|
327 |
|
328 | Instead of using the arithmetic syntax, we can construct the trace ourselves.
|
329 |
|
330 | In this example we build `app/first` and `app/second` into two separate bundles, while creating a separate shared bundle:
|
331 |
|
332 | ```javascript
|
333 | var Builder = require('systemjs-builder');
|
334 |
|
335 | var builder = new Builder({
|
336 | // ...
|
337 | });
|
338 |
|
339 | Promise.all([builder.trace('app/first.js'), builder.trace('app/second.js')])
|
340 | .then(function(trees) {
|
341 | var commonTree = builder.intersectTrees(trees[0], trees[1]);
|
342 | return Promise.all([
|
343 | builder.bundle(commonTree, 'shared-bundle.js'),
|
344 | builder.bundle(builder.subtractTrees(trees[0], commonTree), 'first-bundle.js'),
|
345 | builder.bundle(builder.subtractTrees(trees[1], commonTree), 'second-bundle.js')
|
346 | ]);
|
347 | });
|
348 | ```
|
349 |
|
350 | License
|
351 | ---
|
352 |
|
353 | MIT
|
354 |
|
355 | [travis-url]: https://travis-ci.org/systemjs/builder
|
356 | [travis-image]: https://travis-ci.org/systemjs/builder.svg?branch=master
|