Bundle

Bundle a list of packages into a single file.

Usage

var bundle = require( '@stdlib/_tools/bundle/pkg-list' );

bundle( pkgs, [options,] clbk )

Bundles a list of packages into a single file.

var pkgs = [
    '@stdlib/math/base/special/erf',
    '@stdlib/math/base/special/gamma'
];

bundle( pkgs, clbk );

function clbk( error, bundle ) {
    if ( error ) {
        throw error;
    }
    console.log( bundle.toString() );
}

The function accepts the following options:

  • namespace: namespace format. Must be one of tree, flat, or none. Setting the option equal to tree indicates that the bundle should use a nested object namespace. A flat namespace uses the global project namespace, where each project package has a unique alias. A value of none indicates to forgo a namespace and require that each package be loaded independently. Default: tree.
  • bundler: bundler. Default: browserify.

The function accepts the following options which are specific to browserify:

  • standalone: standalone browserify export name. Setting this option instructs the function to generate a UMD bundle with the supplied export name. The generated bundle will work with other module systems. If no module system is found, the export name is attached to the window global.
  • exportName: bundle export target. The target is the name used to load the bundle from the external environment. In contrast to a standalone UMD bundle, a require function is exposed as a global variable. Default: @stdlib/stdlib.
  • requireName: name of function exposed to support external loading of modules from a browserify bundle. Default: require.
  • transforms: an array of browserify transform modules and functions (including corresponding options) to be applied during bundling.
  • plugins: an array of browserify plugins (including corresponding options) to be applied during bundling.
  • external: an array of modules to omit when generating a bundle. Omitted modules are assumed to be present in a separate external bundle.

Notes

  • Unless a package namespace has an alias in the global alias namespace (e.g., @stdlib/datasets => datasets), namespaces are not included in either flat or tree namespace bundles. If namespace packages were allowed in flat namespace bundles, flat namespace bundles would have mixed namespaces, which is not desired (e.g., possibility of having multiple ways to access the same bundle value). If namespace packages were allowed in tree namespace bundles, tree namespace bundles may attempt to override namespace properties which are read-only. If you want a namespace, provide a namespace only, no namespace children, and generate a tree namespace bundle. And if you only want certain children, then provide the children, but not the namespace. Providing both signals confusion.

Examples

var pkgNames = require( '@stdlib/_tools/pkgs/names' );
var bundle = require( '@stdlib/_tools/bundle/pkg-list' );

var fopts = {
    'pattern': '**/assert/**/package.json',
    'ignore': [
        '**/_**/**' // ignore "private" packages
    ]
};
var bopts = {
    'namespace': 'tree',
    'exportName': '@stdlib'
};

pkgNames( fopts, onNames );

function onNames( error, names ) {
    if ( error ) {
        throw error;
    }
    bundle( names, bopts, onBundle );
}

function onBundle( error, bundle ) {
    if ( error ) {
        throw error;
    }
    console.log( bundle.toString() );
}

CLI

Usage

Usage: bundle-pkg-list [options] [<pkg> <pkg> <pkg> ...]

Options:

  -h,    --help                Print this message.
  -V,    --version             Print the package version.
         --split sep           Separator for stdin data. Default: '/\r?\n/'.
         --namespace type      Type of namespace. Default: 'tree'.
         --bundler bundler     Bundler. Default: 'browserify'.

Browserify Options:

         --standalone name     Generate a UMD bundle with the supplied export
                               name. The generated bundle will work with other
                               module systems. If no module system is found, the
                               export name is attached to the `window` global.

         --export-name name    Bundle export target. The target is the name used
                               to load the bundle from the external environment.
                               In contrast to a standalone UMD bundle, a require
                               function is exposed as a global variable.
                               Default: '@stdlib/stdlib'.

         --require-name name   External `require` name to support requiring
                               packages within a browserify bundle from the
                               external environment. Default: 'require'.

  -t,    --transform module    Apply a transform when bundling. To apply
                               multiple transforms, set a --transform flag
                               for each transform.

  -p,    --plugin module       Register a plugin. To register multiple plugins,
                               set a --plugin flag for each plugin.

  -u,    --external module     Omit a module from an output bundle. Omitted
                               modules are assumed to be present in a separate
                               external bundle. To omit multiple modules, set an
                               --external flag for each module to omit.

Notes

  • If the split separator is a regular expression, ensure that the split option is properly escaped.

    # Not escaped...
    $ echo -n $'tape\nvirtual-dom\n' | bundle-pkg-list --split /\r?\n/
    
    # Escaped...
    $ echo -n $'tape\nvirtual-dom\n' | bundle-pkg-list --split /\\r?\\n/
    
  • A bundle is output bundle is not minified or compressed.

Examples

$ bundle-pkg-list '@stdlib/math/base/special/erf' '@stdlib/math/base/special/gamma' > ./bundle.js
$ echo -n $'@stdlib/math/base/special/erf\n@stdlib/math/base/special/gamma\n' | bundle-pkg-list --split /\\r?\\n/ > ./bundle.js

For compression/minification, pipe to a downstream utility.

$ bundle-pkg-list '@stdlib/math/base/special/erf' '@stdlib/math/base/special/gamma' | uglifyjs