Home

Awesome

Shampoo JS

Sorry, this documentation is a little out of date.

I am working on a full website with documentation which is why the README is a little old. Wasn't expecting people to find this library so soon...

The new version works:

The ultimate Grunt Browserify task.

Quick Start

If you already know Grunt, for basic usage create a Gruntfile.js as below filling in your destination path and source path.

// Gruntfile.js
module.exports = function(grunt) {
  grunt.initConfig({
    shampoo: {
      files: {
        './build/dest/path.js': './source/path.js'
      },
    },
  });
  grunt.loadNpmTasks('grunt-browserifying');
}

Then from your console:

grunt browserifying

This will start the task and watch the source file and all of its require'd dependencies for changes. It will rebuild when a file change is detected. It uses caching so its very fast. To quit watching, use CTRL-C.

Getting Started

This plugin requires Grunt ~0.4.2

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install grunt-browserifying --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-browserifying');

The Browserifying Grunt Plugin

Overview

In your project's Gruntfile, add a section named browserifying to the data object passed into grunt.initConfig().

Include a files Object where:

The source files are relative to the directory from where grunt is being run.

Optionally include an options Object. See the Options section for more info.

grunt.initConfig({
  browserifying: {
    options: {
      // See the options sections for all options.

      // popular option watches for file changes and updates only the changed
      // files. If watch is missing or set to false, browserifying will only
      // bundle the files once and exit.
      watch: true 
    },
    files: {
      './build/path/example.js': './source/path.js'
    },
  },
});

Running the Grunt Task

Run the grunt task from the command line using:

grunt browserify_plus

CoffeeScript

It works with CoffeeScript files (no configuration required):

grunt.initConfig({
  browserifying: {
    options: {},
    files: {
      './build/path/example.js': './source/path.coffee'
                                // .coffee files work
    },
  },
});

Multiple Source Files

For multiple files, pass in an array (feel free to mix js and coffee files):

grunt.initConfig({
  browserifying: {
    options: {},
    files: {
      './build/path/example.js': ['./source/path.coffee', './source/path_2.js']
                               // Array of String for sources works
    },
  },
});

Multiple Browserify Bundles

You can have multiple builds going on simultaneously:

grunt.initConfig({
  browserifying: {
    options: {
    },
    files: {
      // Multiple key/value pairs works to create multiple Browserify bundles
      './build/path/example.js': ['./source/path.coffee', './source/path_2.js']
      './build/path/example-2.js': './source/example-2.js'
    },
  },
});

Options

All options:

grunt.initConfig({
  browserifying: {
    options: {
      watch: false, // watch files for changes with caching (default true)
      map: {
        'underscore': './lib/underscore.js',
        'jquery': {
          exports: '$',
          path: './lib/jquery.js',
        }
      },
      sourceMaps: true,     // enable source maps (default true)
      brfs: true            // enable inlining files (default false)
    }
    },
    files: {
      ...
    },
  },
});

options.map

Type: Object Default value: {}

A map allows you to:

options.map - alias
// a map allows you to do this
require 'underscore'

Instead of this

// don't do this anymore
require '../node_modules/underscore/underscore.js'

Configure maps like this:

grunt.initConfig({
  browserifying: {
    options: {
      map: {
        'underscore': './lib/underscore.js'
      }
    },
    files: {
      ...
    },
  },
});
options.map - shim

You can also use a shim inside the map.

A shim allows you to use JavaScript files that are not designed for use with CommonJS.

In a CommonJS file, we export a variable by assigning it to module.exports like this:

// code goes here
module.exports = someVariable;

JavaScript files that don't conform to CommonJS, don't have a module.exports assignment. Normally we would have to modify the JavaScript file just to add module.exports to make it work with Browserify.

Instead, we can use a shim. We just tell that shim what variable to export. In the example above, that variable would be someVariable. For jQuery, it would be $ or jQuery (both reference the same object).

Here is how to use map to create a shim:

grunt.initConfig({
  browserifying: {
    options: {
      map: {
        // jQuery with a shim
        'jquery': {
          exports: '$',
          path: './lib/jquery.js'
        },
        // we can mix unshimmed maps in as well like below
        'underscore': './lib/underscore.js'
      }
    },
    files: {
      ...
    },
  },
});

Now we can do:

// this works now
$ = require('jquery');

options.sourceMaps

Type: Boolean Default value: true

When set to true, the output will include source maps. This means that when you are running the JavaScript code and there is an error you will see the error coming from the original file (not the bundle one). Your browser must support source maps (e.g. Chrome, Firefox, Safari).

grunt.initConfig({
  browserifying: {
    options: {
      sourceMaps: false    // disable source maps
    },
    files: {
      ...
    },
  },
});

options.brfs

Type: Boolean Default value: false

When set to true, calls to code like fs.readFileSync(__dirname + '/file.txt') will have the contents of the file inlined into the JavaScript.

Remember to include require 'fs' in the JavaScript or CoffeeScript file.

fs = require 'fs'
text = fs.readFileSync(__dirname + '/file.txt')

Roadmap

Here's some features I'd like to add.

Contributing

We accept and encourage commits.

Release History

February 2, 2014

Thanks To

Browserifying works by including the most popular Browserify modules and tools and configures them so that they all work together.

Browserifying is really just a manager over a lot of important work contributed to the following projects: