cbuild

cbuild allows publishing leaner SystemJS-based apps and packages running without build tools. npm itself can pull all required frontend and backend dependencies.

Normally you would use jspm which also users of your package must install. It's very powerful but has some drawbacks if plain npm is enough for your use case:

• jspm pulls another over 90 packages and 15 megabytes of code with it.
• ... downloads another separate copy of all required Node.js modules into a different directory structure.
• ... involves a large config.js, parts of which are manually edited (so belong to version control) and other parts autogenerated from package.json fields (so preferably omitted from version control).

cbuild instead uses Node.js module resolution to find packages installed using npm without additional configuration. Only the manually edited parts are needed in config.js.

How does it work?

cbuild simply passes your SystemJS config.js to systemjs-builder, which bundles your main JavaScript file with its dependencies. cbuild adds a hook to look up any missing files using browser-resolve.

That means you can still use jspm as before but you don't have to reinstall all your npm packages with it, because cbuild also automatically looks inside node_modules. Simple package deduplication is natively handled by npm@3 or the dedupe command in npm@2.

For more complicated scenarios, the full power of SystemJS is still available for loading and bundling.

cbuild supports the browser field in package.json. It can also generate a minimal config.js for SystemJS to load packages without having to bundle them.

Usage

Add in the scripts section of your package.json:

  "scripts": {
    "cbuild": "cbuild"
  }

Then run the commands:

npm install --save-dev cbuild
npm run cbuild -- -o bundle.js

This generates a new file bundle.js with all code required to load the file defined in the browser (or main if browser is missing) field of package.json. You can also set the file on the command line with the --source option.

Run npm run cbuild -- --help to see the command line options:

  Usage: cbuild [options]

  SystemJS node module bundling tool

  Options:

    -V, --version                output the version number
    -b, --builder-config <file>  specify SystemJS builder configuration file
    -d, --debug [flag]           use development environment
    -m, --map <package>          add package to mappings
    -s, --source <file>          main JavaScript source to bundle
    -p, --package <path>         directory with package.json and config.js
    -o, --out <file>             write output bundle to file
    -C, --out-config <file>      write path mappings to new config file
    -I, --include-config <file>  merge another file into new config file
    -q, --quiet [flag]           suppress terminal output
    -v, --verbose [flag]         print dependency tree of bundled files
    -x, --static [flag]          create static (sfx) bundle
    -h, --help                   output usage information

The --builder-config option accepts a JSON file containing SystemJS builder bundle options and SystemJS configuration options structured like:

{
    // Bundle options, for example:
    "minify": true,
 
    "config": {
        // Configuration options, for example:
        "buildCSS": false
    }
}

API

Docs generated using docts

Interface Branch

Dependency tree branch, used for makeTree() output.
Source code: <>

Properties:

.0_? ^string
 File name.

Interface BuildItem

systemjs-builder diagnostics for a single input file.
Source code: <>

Properties:

.name ^string
.path ^string
.metadata ^{{ [key: string]: any; }}
.deps ^string[]
 List of imports.
.depMap ^{{ [name: string]: string; }}
 Table mapping imports to their paths inside the bundle.
.source ^string
.fresh ^boolean
.timestamp ^number
.configHash ^string
.runtimePlugin ^boolean
.pluginConfig ^any
.packageConfig ^any
.isPackageConfig ^any
.deferredImports ^any

Interface BuildOptions

Options object for the build function.
Source code: <>

Properties:

.debug_? ^boolean
 If true, set NODE_ENV to development.
.sfx_? ^boolean
 If true, create static (sfx) bundle.
.bundlePath_? ^string
 Bundled file to output.
.sourcePath_? ^string
 Main source file to bundle.
.outConfigPath_? ^string
 Output config mapping other package names to their main source files.
.mapPackages_? ^string[]
 Map additional packages in output config.

Interface BuildResult

systemjs-builder diagnostics for the entire bundle.
Source code: <>

Properties:

.source ^string
 Bundled output file contents.
.sourceMap ^string
.modules ^string[]
 List of bundled files.
.entryPoints ^string[]
 List of files intended to be imported from the bundle(?).
.tree ^{{ [path: string]: BuildItem; }}
.assetList ^any
 Other non-JavaScript files included in the bundle.
.bundleName ^string

Function build

Bundle files from package in basePath according to options.
Source code: <>

build( ) ^{⇒ Bluebird<BuildResult>} <>
 ▪ basePath ^string
 ▫ options_? ^BuildOptions

Function makeTree

Extract a dependency tree from the build function result object.
Returns a nameless root item.
Each item is a list of a file name and its child items.
Uses Breadth-First Search to print shortest import chain to each file.
Source code: <>

makeTree( ) ^{⇒ Branch} <>
 ▪ result ^BuildResult

License

The MIT License

Copyright (c) 2016-2018 BusFaster Ltd