common-bundle

common-bundle

A browserify plugin for packing modules into common shared bundles.

Features:

• Group one or more entries (modules) together to create a bundle.
• Extract common modules from bundles to create additional shared bundles.
• b.bundle() generates a stream flowing vinyl file objects.
• Work together with watchify2 to re-bundle when entries are added and removed in the watching mode. See example.

Example

input:

One bundle for each page

var browserify = require('browserify')
var glob = require('glob')
 
var basedir = '/path/to/src'
var entries = glob.sync('page/**/index.js', { cwd: basedir })
var b = browserify(entries, { basedir: basedir })
 
b.plugin('common-bundle', {
  // Each index.js packed into a new bundle
  // with path page/**/index.js
  groups: 'page/**/index.js',
})
 
var vfs = require('vinyl-fs')
// Write all bundles to the build directory
b.bundle().pipe(vfs.dest('/path/to/build'))

output:

One additional bundle shared by all page-specific bundles

var browserify = require('browserify')
var glob = require('glob')
 
var basedir = '/path/to/src'
var entries = glob.sync('page/**/index.js', { cwd: basedir })
var b = browserify(entries, { basedir: basedir })
 
b.plugin('common-bundle', {
  // Each index.js packed into a new bundle with path page/**/index.js
  groups: 'page/**/index.js',

  common: {
    output: 'common.js',
    filter: '**/*.js',
  },
})
 
var vfs = require('vinyl-fs')
// Write all bundles to the build directory
b.bundle().pipe(vfs.dest('/path/to/build'))

output:

factor-bundle

The default output of factor-bundle would be:

NOTE: factor-bundle may pack modules, that are not needed by some pages, into the common bundle. common-bundle will try to make sure every page load only necessary modules.

Shared bundle for each group of page-specific bundles

var browserify = require('browserify')
var glob = require('glob')
 
var basedir = '/path/to/src'
var entries = glob.sync('page/**/index.js', { cwd: basedir })
var b = browserify(entries, { basedir: basedir })
 
b.plugin('common-bundle', {
  // Each index.js packed into a new bundle with path page/**/index.js
  groups: 'page/**/index.js',

  common: [
    {
      output: 'common-hello-and-hi.js',
      filter: ['page/hello/index.js', 'page/hi/index.js']
    },
    {
      output: 'common-red-and-green.js',
      filter: ['page/red/index.js', 'page/green/index.js']
    },
  ],
})
 
var vfs = require('vinyl-fs')
// Write all bundles to the build directory
b.bundle().pipe(vfs.dest('/path/to/build'))

output:

Usage

var browserify = require('browserify')

var b = browserify(entries, bopts)

b.plugin('common-bundle', options)

options

groups

This options is used to create original bundles, which will be used to generate additional shared bundles later according to the common option.

Specify which modules (and all of their dependencies) to be packed together into which bundle.

Type: Array

[
  {
    output: function (file) {
      if (/A/.test(file)) {
        return 'A.js'
      }
      if (/B/.test(file)) {
        return 'B.js'
      }
      if (/C/.test(file)) {
        return 'C.js'
      }
    },
  },
]

Or:

[
  {
    filter: 'A/index.js',
    output: 'A.js',
  },
  {
    filter: 'B/index.js',
    output: 'B.js',
  },
  {
    filter: 'C/index.js',
    output: 'C.js',
  },
]

output:

Type: Function

Receives the file path to a module, and should return the file path of the bundle which should contain that module.

If a falsy value returned, the module will appear either in all bundles or bundles containing its dependents.

Type: String

Specify the file path of the bundle to be created.

Type: Falsy

The file path to the new bundle is determined by the result of path.relative(basedir, file).

basedir can be specified by basedir.

filter:

Specify how to match modules that should be packed into the new bundle.

Type: Function

Receives the file path to a module.

If true returned, that module will be packed into this new bundle.

Type: String, Array

Passed to multimatch to test module files.

common

This options is used to create bundles for sharing among those created through the groups option.

Type: Array

NOTE: if there is only one single original bundle, this option is ignored.

Examples:

// Pack modules shared by all original bundles into `common.js`
b.plugin('common-bundle', {
  common: {
    output: 'common.js',
    filter: '**/*.js',
  },
})

b.plugin('common-bundle', {
  common: [
    {
      output: 'ab.js',
      filter: ['page/A/index.js', 'page/B/index.js'],
    },
    {
      output: 'bc.js',
      filter: ['page/C/index.js', 'page/B/index.js'],
    },
    {
      output: 'ac.js',
      filter: ['page/A/index.js', 'page/C/index.js'],
    },
  ],
})

output:

Type: String

File path to the new bundle for sharing.

filter:

Specify which bundles to share the new bundle.

Type: Function

Receives an array of bundle file paths (relative to basedir), and should return those to share the new bundle.

Type: String, Array

Passed to multimatch to determine bundles to share the new bundle.

basedir

Specify how to name the bundles created.

See the groups options for more information.

Type: String

Events

b.on('common.map', map => {})

map

You can use Object.keys(map) to get paths (file.relative) to all bundles.

In addition, map[bundle] is an object with the following fields:

• modules: Array. Paths to modules (relative to basedir) packed into bundle
• deps: Array. Paths to common bundles (file.relative) that bundle depends upon.

b.on('common.pipeline', (id, pipeline) => {})

Every time a bundle created, a common.pipeline event is emitted with its id and the packing pipeline.

A pipeline is a labeled-stream-splicer:

• 'pack' - browser-pack
• 'wrap' - apply final wrapping

You can call pipeline.get with a label name to get a handle on a stream pipeline that you can push(), unshift(), or splice() to insert your own transform streams.

Event handlers must be attached before calling b.plugin.

Work with watchify and gulp

var through = require('through2')

var b = browserify(entries, opts)
  .plugin('common-bundle', bundleOpts)

function bundle() {
  return b.bundle()

    .pipe(through.obj(function (file, _, next) {
      // Log bundles created
      b.emit('log', file.relative)
      next(null, file)
    }))

    // maybe `vinyl-buffer` is needed to apply
    // more gulp plugins here

    .pipe(gulp.dest('build'))
}

gulp.task('build', bundle)

gulp.task('watch', function () {
  b.plugin('watchify')
  b.on('update', bundle)
  bundle()
})