cbuild
    TypeScript icon, indicating that this package has built-in type declarations

    0.1.8 • Public • Published

    cbuild

    build status dependency status npm version

    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

    Keywords

    none

    Install

    npm i cbuild

    DownloadsWeekly Downloads

    8

    Version

    0.1.8

    License

    MIT

    Last publish

    Collaborators

    • jjrv