Nonviolent Pirate Mobster
Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »


2.28.2 • Public • Published

This package has been deprecated

Author message:



This gulp plugin is a fork of gulp-bundle-assets with gulp-concat-css used instead of the JavaScript suited gulp-concat. While this substitution allows for properly url rebasing, it also may break the sourcemaps.

Unit tests are a whole other story. Significant amounts of the out-of-box tests are heavily dependent on the output of used libraries, and as such break easily. They also don't consider platform specific path delimiters, and as such depend on a Unix-like OS.

Full credit for this plugin goes to its original creater, switching out similar plugins is a simple feat on my part.

If node-sass causes an error during install, and your running Windows;

npm i -g --production windows-build-tools
#Wait for lengthy post install...
npm config set msvs_version 2015 --global

Original documentation follows:

gulp-bundle-assets NPM version

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.


$ 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')
// bundle.config.js
module.exports = {
  bundle: {
    main: {
      scripts: [
      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

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.results('./')) // arg is destination of bundle.result.json

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!


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.


  • 2017/04/15 - v2.28.0 - add options to output src files in result #90 (@PlasmaPower)
  • 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 #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 (@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 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 for bundles #26




npm i gulp-uf-bundle-assets

Downloadsweekly downloads








last publish


  • avatar