multi-bundle

Produces multiple browserify bundles and extracts common dependencies.

Git repository

Changelog

multi-bundle is a frontend for browserify that automatically factors out common dependencies based on an arbitrarily nested entry point configuration that you provide.

Install

$ npm install --save-dev multi-bundle

Usage

    var multi = require('multi-bundle');

    var entryConfig = {
        common: {
            start: './start.js',
            control: {
                stop: './stop.js',
                pause: ['./pause.js', './resume.js']
            }
        },
        oneoff: './oneoff.js'
    };

    multi(entryConfig).bundle();

The above will produce 6 bundle streams in total.

Entry points:

1. start
2. stop
3. pause
4. oneoff

Shared bundles:

1. common: contains all common dependencies between start, control, stop, and pause
2. control: contains common dependencies shared by stop and pause but not start

Note that in the above example, oneoff will contain all of its dependencies whether or not they are shared in the other modules.

The shared bundles use browserify.require for their included dependencies so that they are externally available to entry point bundles. Common module scripts must be included from outermost to innermost prior to including the entry point script.

<script src="out/common.js"></script>
<script src="out/control.js"></script>
<script src="out/stop.js"></script>

API

Assuming:

var multi = require('multi-bundle');

multi(entryConfig, [opts])

Takes entry point configuration + options and builds as many browserify instances as needed to factor dependencies into their appropriate bundles.

entryConfig

Type: string, Array, or object

Entry point configuration. String and array values will produce single bundles with the given entry point. Object values may produce multiple bundles, depending on the configuration provided. Each item in an entryConfig object may also be a string, an array, or another object.

Nested object values will generate a shared bundle at each level.

multi({
    'common': {
        'a': 'a.js',
        'b': 'b.js'
    }
})

The above will produce 3 bundles: common, a, and b.

opts

Type: object
Default: { threshold: 1, browserify: require('browserify') }

Options that customize the behaviour of both multi-bundle and browserify. All options defined here, except threshold and browserify, will be passed to the browserify constructor.

opts.threshold

Type: number
Default: 1

Controls how dependencies are factored into bundles.

If a dependency is shared by more than threshold entry points, it will get extracted into a shared bundle (if those entry points belong to a shared configuration object). This works at every configuration level.

opts.browserify

Type: function(opts) -> browserify instance
Default: require('browserify')

This is a function that takes a single parameter opts and produces a browserify instance.

By default, this will just use the browserify constructor. You may wish to override this if you want to perform some custom configuration to all browserify instances that can't be achieved through opts or if you want to provide an alternate browserify-compatible constructor (such as watchify).

The instance returned by opts.browserify must adhere to the following interface:

b.add(file);
b.require(file);
b.external(file);
b.bundle(opts);

Instance methods

An instance of multi() has 2 methods:

var m = multi(entryConfig, opts);
m.bundle(bopts);
m.stream();

bundle(bopts) -> stream

bundle returns a stream of all the output bundles produced with the given configuration.

bopts

Type: object
Default: No default

These are options that control the bundle output from the browserify instances. Any options defined here are passed to browserify bundle method.

bopts.pipeTo

Type: function(name, browserify) -> stream, Array<function(name, browserify) -> stream>
Default: No default

A function or an array of functions that return streams to which the output bundles will be piped. The functions accept the following parameters:

• name: name of the output bundle
• browserify: the browserify instance used to create the bundle

The returned streams should be Transform streams. If there is only a single pipeTo value, it may return a Writable stream.

The value returned from m.bundle() will be the end result of piping the original source bundles through all pipeTo values, if specified.

bopts.objectMode

Type: boolean
Default: false

Requests that the output bundles are streamed in object mode rather than as strings/buffers.

NOTE: This should only be used if a transform stream in pipeTo produces an object mode stream, as the streams generated by browserify are not in object mode. Setting objectMode=true for a string/buffer stream will cause exceptions.

stream() -> stream<{name, compiler}>

stream returns an object mode stream containing one value per output bundle. Each item has two properties: name and compiler.

name

Type: string

The entry point configuration key for which this compiler was generated.

compiler

Type: browserify instance

The browserify compiler for this module, pre-populated with any dependency information.

Example usage with gulp

var gulp = require('gulp');
var multi = require('multi-bundle');
var source = require('vinyl-source-stream');

var entryConfig = {
    common: {
        start: './app/start.js',
        control: {
            stop: './app/stop.js',
            pause: ['./app/pause.js', './app/resume.js']
        }
    },
    oneoff: './app/oneoff.js'
};

gulp.task('bundle', function() {
    return multi(entryConfig).bundle({
        objectMode: true,
        debug: true,
        pipeTo: function (name) { return source(name + '.js'); }
    }).pipe(gulp.dest('./build'));
});

The above uses vinyl-source-stream to transform the text-mode browserify bundle into a vinyl file object compatible with gulp.dest.

Contributing

1. Clone git repository

2. npm install (will install dev dependencies needed by the next step)

3. npm start (will start a file system watcher that will re-lint JavaScript and JSON files + re-run all tests when change is detected)

4. Make changes, don't forget to add tests, submit a pull request.

License

MIT © Pandell Technology