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

    shampoopublic

    Shampoo JS

    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

    install

    npm i shampoo

    Downloadsweekly downloads

    2

    version

    1.0.12

    license

    none

    repository

    github.com

    last publish

    collaborators

    • avatar