https://github.com/charto/cbuild
Use SystemJS with npm instead of jspm
https://github.com/charto/cbuild
nodejs systemjs
Last synced: 3 months ago
JSON representation
Use SystemJS with npm instead of jspm
- Host: GitHub
- URL: https://github.com/charto/cbuild
- Owner: charto
- License: mit
- Created: 2016-04-07T15:01:47.000Z (about 10 years ago)
- Default Branch: master
- Last Pushed: 2018-01-28T17:16:10.000Z (over 8 years ago)
- Last Synced: 2025-09-13T21:53:21.314Z (9 months ago)
- Topics: nodejs, systemjs
- Language: TypeScript
- Size: 58.6 KB
- Stars: 25
- Watchers: 6
- Forks: 1
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](http://travis-ci.org/charto/cbuild)
[](https://david-dm.org/charto/cbuild)
[](https://www.npmjs.com/package/cbuild)
`cbuild` allows publishing leaner [SystemJS](https://github.com/systemjs/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`](https://github.com/systemjs/builder),
which bundles your main JavaScript file with its dependencies.
`cbuild` adds a hook to look up any missing files using [`browser-resolve`](https://github.com/defunctzombie/node-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`:
```json
"scripts": {
"cbuild": "cbuild"
}
```
Then run the commands:
```bash
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 specify SystemJS builder configuration file
-d, --debug [flag] use development environment
-m, --map add package to mappings
-s, --source main JavaScript source to bundle
-p, --package directory with package.json and config.js
-o, --out write output bundle to file
-C, --out-config write path mappings to new config file
-I, --include-config 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](https://github.com/systemjs/builder/blob/master/docs/api.md#bundle-options) and
[SystemJS configuration options](https://github.com/systemjs/systemjs/blob/master/docs/config-api.md#configuration-api)
structured like:
```JavaScript
{
// Bundle options, for example:
"minify": true,
"config": {
// Configuration options, for example:
"buildCSS": false
}
}
```
API
===
Docs generated using [`docts`](https://github.com/charto/docts)
>
>
> ### Interface [`Branch`](#api-Branch)
> Dependency tree branch, used for makeTree() output.
> Source code: [`<>`](http://github.com/charto/cbuild/blob/77b2a6f/src/cbuild.ts#L222-L225)
>
> Properties:
> > **.0**? string
> > File name.
>
>
> ### Interface [`BuildItem`](#api-BuildItem)
> systemjs-builder diagnostics for a single input file.
> Source code: [`<>`](http://github.com/charto/cbuild/blob/50a7bec/src/typings-custom.d.ts#L10-L27)
>
> 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`](#api-BuildOptions)
> Options object for the build function.
> Source code: [`<>`](http://github.com/charto/cbuild/blob/77b2a6f/src/cbuild.ts#L13-L31)
>
> 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`](#api-BuildResult)
> systemjs-builder diagnostics for the entire bundle.
> Source code: [`<>`](http://github.com/charto/cbuild/blob/50a7bec/src/typings-custom.d.ts#L31-L43)
>
> 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`](#api-build)
> Bundle files from package in basePath according to options.
> Source code: [`<>`](http://github.com/charto/cbuild/blob/77b2a6f/src/cbuild.ts#L98-L218)
> > **build( )** ⇒ Bluebird<[BuildResult](#api-BuildResult)> [`<>`](http://github.com/charto/cbuild/blob/77b2a6f/src/cbuild.ts#L98-L218)
> > ▪ basePath string
> > ▫ options? [BuildOptions](#api-BuildOptions)
>
>
> ### Function [`makeTree`](#api-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: [`<>`](http://github.com/charto/cbuild/blob/77b2a6f/src/cbuild.ts#L232-L279)
> > **makeTree( )** ⇒ [Branch](#api-Branch) [`<>`](http://github.com/charto/cbuild/blob/77b2a6f/src/cbuild.ts#L232-L279)
> > ▪ result [BuildResult](#api-BuildResult)
License
=======
[The MIT License](https://raw.githubusercontent.com/charto/cbuild/master/LICENSE)
Copyright (c) 2016-2018 BusFaster Ltd