Build tool for the JS.Package dependency system
Build tool for the JS.Packages module system. Consumes manifests and uses the dependency data to build bundles for deployment.
$ npm install -g jsbuild
A common setup when using JS.Packages for web development is to include the
package loader and your package manifest using
script tags, then using
JS.require() to load components as you need them.
In this case
manifest.js might contain:
jsbuild is a command-line program that takes your package manifest and a list
those modules and all their dependencies. The modules can come from your local
file system or from the web.
jsbuild as follows:
$ jsbuild --manifest MANIFEST --root ROOT [OPTIONS] module1 [module2 ...]
The options available are:
--manifest: the path to your package manifest. If you have several manifests, use
--external: unless this option is passed, the build will skip files that come from the web rather than the local filesystem.
--no-packages: if this is set, the
JS.Packagescode will not be included in the build. Including it means your
JS.require()calls will carry on working.
--bundles: optional path to bundle definition file (see Organising bundles).
--output: the type of output required, either
jsbuildoutput the combined source code, and
pathsmakes it output the paths to the bundled files.
--directory: a directory to trim from paths output when using
-o paths. For example passing
-d public/jswill make
For example to build a bundle to support our application, we can run this
command to produce a single script containing
Application depends on
$ jsbuild --manifest public/js/manifest.js \--root public/js/ \--external \Application
The resulting script is printed to stdout. Note that
jsbuild does not do any
minification of the files your provide, it simply locates the required modules
and concatenates them. You should deal with minifying the resulting file
As a project grows, it often becomes likely that you don't want all your
modules and their dependencies in one file. Although this minimizes HTTP
round-trips, it means the entire bundle must be re-downloaded when any part of
it changes. For this reason many people keep stable libraries in one bundle and
their more volatile application code in another.
jsbuild lets you create such
bundles using a simple JSON file.
The file lists a number of bundles, each of which has an
include field and an
exclude field, both of which can be a list or a single item. The
include field specifies which objects from the manifest should go into that
exclude specifies which dependencies should be skipped, usually
because they are provided by another bundle you will load separately. Items
exlude can be object names from the manifest, or other bundle names
to exclude everything provided by that bundle and any bundle it depends on.
For example, let's split our files into stable libraries and our application code:
// bundles.json"libs":"include": "jQuery""app":"exclude": "libs""include": "Application"
We can then pass bundle names instead of object names to
jsbuild to create
the bundled files. Remember to pass
-b bundle.json to tell it where your
bundles are stored.
$ jsbuild -m public/js/manifest.js -b bundles.json -r public/js -o paths libs$ jsbuild -m public/js/manifest.js -b bundles.json -r public/js -o paths apppublic/js/app.js
If we removed the line
"exclude": "libs" from the
app bundle, we would
instead get this output, where jQuery has been included before our own files:
$ jsbuild -m public/js/manifest.js -b bundles.json -r public/js -o paths apppublic/js/app.js
(The MIT License)
Copyright (c) 2007-2013 James Coglan
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.