gulp-bundle-assets

Create static asset bundles from a config file: a common interface to combining, minifying, revisioning and more. Stack agnostic. Production ready.

By default uses the following gulp modules under the covers when creating bundles:

1. gulp-concat
2. gulp-sourcemaps
3. gulp-uglify
4. gulp-clean-css
5. gulp-rev
6. gulp-order

This project's stream architecture also allows you to plugin any gulp transform you wish.

Install

$ npm install gulp-bundle-assets --save-dev

Basic Usage

Create the following files:

// gulpfile.js
var gulp = require('gulp'),
  bundle = require('gulp-bundle-assets');

gulp.task('bundle', function() {
  return gulp.src('./bundle.config.js')
    .pipe(bundle())
    .pipe(gulp.dest('./public'));
});

// bundle.config.js
module.exports = {
  bundle: {
    main: {
      scripts: [
        './content/js/foo.js',
        './content/js/baz.js'
      ],
      styles: './content/**/*.css'
    },
    vendor: {
      scripts: './bower_components/angular/angular.js'
    }
  },
  copy: './content/**/*.{png,svg}'
};

Then, calling

$ gulp bundle

Will result in the following folder structure:

-- public
   |-- content
   |   |-- fonts
   |   |-- images
   `main-8e6d79da08.css
   `main-5f17cd21a6.js
   `vendor-d66b96f539.js

Advanced Usage

See the examples folder for many other config options. The full example shows most all available options.

Also check out our api docs.

Integrating bundles into your app

You can programmatically render your bundles into your view via your favorite templating engine and the resulting bundle.result.json file. To generate the bundle.result.json, add a call to bundle.results:

// gulpfile.js
var gulp = require('gulp'),
  bundle = require('gulp-bundle-assets');

gulp.task('bundle', function() {
  return gulp.src('./bundle.config.js')
    .pipe(bundle())
    .pipe(bundle.results('./')) // arg is destination of bundle.result.json
    .pipe(gulp.dest('./public'));
});

Which results in a bundle.result.json file similar to:

{
  "main": {
    "styles": "<link href='main-8e6d79da08.css' media='screen' rel='stylesheet' type='text/css'/>",
    "scripts": "<script src='main-5f17cd21a6.js' type='text/javascript'></script>"
  },
  "vendor": {
    "scripts": "<script src='vendor-d66b96f539.js' type='text/javascript'></script>",
    "styles": "<link href='vendor-23d5c9c6d1.css' media='screen' rel='stylesheet' type='text/css'/>"
  }
}

The order of the bundles will be the same as the order in which they were specified in the config.

See here for a full example using hogan

Other Features

1. watch src files and only build specific bundles
   • Greatly speeds up development
   • e.g. split out vendor and custom js files into different bundles so the custom bundle continues to build quickly on src change
2. different bundles for different environments
   • e.g. NODE_ENV=production gulp bundle could produce a set of bundles with minified src while just gulp bundle would have unminified src
3. custom gulp transforms
   • e.g. use gulp-less, gulp-sass, gulp-coffee, etc to further transform your files
4. consume pre-minified src files
   • e.g. use jquery.min.js in production and jquery.js in dev
5. custom result types
   • e.g. create a bundle.result.json for html, jsx or any custom results you can think of
6. works alongside 3rd party transformers
   • e.g. create a bundle using browserify, 6to5, etc.
7. guarantee bundle content order
8. modify built-in behavior with custom gulp plugin options
9. and much more!

Why?

There are a number of ways to bundle static assets for use in your webapp. Take for example: lumbar, brunch, webpack, browserify, optimizer, cartero, assetify, assets-packager, or simply a mashup of custom grunt or gulp plugins. All of these approaches are good in their own way but none of them did everything we needed:

• handle all file types: js, css, less, sass, coffeescript, images, fonts, etc...
• handle a variety of js managers: amd, requirejs, etc...
• support common transforms: compression, minification, revisioning
• support custom transforms, e.g. browserify
• logic must be common across webapps. That is, no copy/pasting of tasks. This disqualified straight gulp or grunt.
• work with existing community plugins, namely gulp tasks
• work with src from multiple locations, e.g. bower_components, node_modules, etc
• fast!

gulp-bundle-assets accomplishes all these goals and more. A main guiding principle behind this project is to provide all necessary bundling functionality while still being as flexible and customizable as possible.

Changelog

• 2016/05/23 - v2.27.0 - add consistent result.json ordering #71 (@PlasmaPower)
• 2016/05/06 - v2.26.0 - update many deps including: gulp-less 3.1.0, gulp-coffee 2.3.2 and gulp-if 2.0.1
• 2016/05/06 - v2.25.0 - update to use gulp-clean-css 2.0.7 instead of deprecated gulp-minify-css module
• 2016/03/17 - v2.24.0 - update to gulp-less 3.0.5 and gulp-uglify 1.5.3
• 2015/09/16 - v2.23.0 - add plugin option to modify built-in sourcemaps #65 (@narthollis)
• 2015/07/17 - v2.22.0 - add config option for consistent file content ordering #25
• 2015/06/11 - v2.21.0 - update all deps, including: gulp-rev 4.0.0, gulp-less 3.0.3, gulp-sourcemaps 1.5.2
• 2015/05/07 - v2.20.0 - add pluginOptions config option #50
• 2015/05/07 - v2.19.2 - update to gulp-minify-css 1.1.1 (@ZaleskiR)
• 2015/04/24 - v2.19.1 - fix result.json url separator on windows #52 (@gregorymaertens)
• 2015/03/01 - v2.19.0 - fix error handling for bundle.watch #47
• 2015/02/08 - v2.18.0 - add flag to disabled sourcemaps #45 (@21brains-zh)
• 2015/02/04 - v2.17.5 - update examples
• 2015/02/04 - v2.17.4 - add logging for errors from custom transforms #41
• 2015/02/03 - v2.17.3 - update examples
• 2015/02/03 - v2.17.2 - add logging of bundle config parse errors
• 2014/12/05 - v2.17.1 - fix custom result file name during bundle.watch (@roberto)
• 2014/12/05 - v2.17.0 - add custom result file name #36 (@roberto)
• 2014/12/04 - v2.16.1 - fix tests
• 2014/12/01 - v2.16.0 - update deps, including: gulp-rev 2.0.1, gulp-sourcemaps 1.2.8, gulp-uglify 1.0.1
• 2014/10/21 - v2.15.2 - add support for both minCSS and minCss #34
• 2014/10/10 - v2.15.1 - add example using 6to5 (aka babel)
• 2014/09/29 - v2.15.0 - add bundle.watch for copy files #33
• 2014/09/29 - v2.14.0 - add flag to disable logging #16
• 2014/09/25 - v2.13.1 - fix when bundleAllEnvironments: true, srcMin is always true #32
• 2014/09/23 - v2.13.0 - add to allow different watch vs bundle targets #30
• 2014/09/23 - v2.12.1 - fix to only publish results during watch when opts defined
• 2014/09/23 - v2.12.0 - add bundle.watch for bundles #26

License

MIT