grunt-browserifying

The ultimate Grunt Browserify task.

• Run once or watch files for changes
• Uses a cache for super speed (instant builds)
• CoffeeScript support built in
• Alias mappings
• Shim non CommonJS files
• Super simple configuration and good defaults
• More...

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({
    browserifying: {
      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 keys are the destination file for the Browserify build (remember to include the ".js")
• The value is either a String or Array of String that represents the source files. The source files may be either .js or .coffee files. Remember to:
  1. Include the extension (.js or .coffee).
  2. Include the "./" part of the path

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:

• alias: Require files from any location using an alias
• shim: Use a non-CommonJS JavaScript file with require

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.

• gulp: Make it work with gulp
• command line: Make it work from the command line
• unit tests: Unit test everything
• dev and production modes: Create sensible defaults for a 'production' mode and a 'development' mode. For example, debug mode should have sourceMaps: true and watching for changes: true while development mode should have no sourceMaps and only do the build one.
• minification and obfuscation: Add minification and obfuscation options with good defaults

Contributing

• CoffeeScript: Browserifying is written in CoffeeScript.

• Comments: Please write a lot of comments. Since there are a lot of modules that get included (being that the purpose of Browserifying is to bring important modules together), it's important to comment everything that is going on in the code.

• Descriptive Variable Names: Use long descriptive variable names rather than short ones so that it's easy for anybody to look at the source code and understand what's going on.

We accept and encourage commits.

Release History

February 2, 2014

• Added a .watch option so the same Grunt task can be used to do a single build (e.g. for production) or watching and continuously building (e.g. for development)
• Merged .aliasMappings and .shim options into a single .map option. Easier to remember the name and its easier to convert an alias into a shim because you don't have to move the configuration options.
• Added brfs support.
• Renamed .debug option to .sourceMaps to be more intuitive.
• Renamed library from grunt-browserify-plus to grunt-browserifying

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:

• Browserify
• Coffeeify
• Watchify
• Aliasify
• Browserify-Shim
• BRFS