search

dowjones / gulp-bundle-assets

Create static asset (js, css) bundles from a config file: a common interface to combining, minifying, revisioning and more
MIT License
133 stars 36 forks source link

readme

gulp-bundle-assets NPM version Build Status Coverage Status

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
  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:

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

License

MIT