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-minify-css
5. gulp-rev

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-8e6d79da.css
   `main-5f17cd21.js
   `vendor-d66b96f5.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-8e6d79da.css' media='screen' rel='stylesheet' type='text/css'/>",
    "scripts": "<script src='main-5f17cd21.js' type='text/javascript'></script>"
  },
  "vendor": {
    "scripts": "<script src='vendor-d66b96f5.js' type='text/javascript'></script>",
    "styles": "<link href='vendor-23d5c9c6.css' media='screen' rel='stylesheet' type='text/css'/>"
  }
}

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.

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.

License

MIT