Browserify

Contents

• Folder Structure
• Introduction
• Bundles
• Quick CommonJS Overview
• Relative Dependencies
• waitFor Helper

Folder Structure

├───config/              # Configuration files
├───lib/                 # Typically tools and such. Polyfills, plugins.
├───modules/             # Reusable modules. Probably export some methods and properties
├───templates/           # EJS templates
└───views/               # Page-specific code

Introduction

Browserify takes a set of js files and concatenates them into a single bundle file to be used on all of your pages. It doesn't do anything fancy when the page loads. It does its work while you're developing. The idea is to have a single HTTP request for your scripts instead of multiple requests for script files which block the rendering of your page. You also take advantage of browser caching since you are always serving the same file.

For a better overview check out this article For a more in-depth understanding of Browserify, [check out the Browserify handbook(https://github.com/substack/browserify-handbook).

Bundles

To create bundles add items to the array in _src/js/config/bundles.js.

var main = {
  outputName: 'main.js',
  entries: [
    './modules/responsiveImages',
    './modules/sampleModule'
  ]
};

var blog = {
  outputName: 'blog.js',
  entries: [
    './modules/responsiveImages',
    './views/blog'
  ]
};

module.exports = [main, blog];

outputName – The name of the bundle to be created.

entries – The modules to be included in the bundle. Must be included manually.

Don't get hung up on the order of the entries in the array. Browserify takes care of that through its knowledge of the CommonJS module system.

Notice that ./ in the file paths in the entries array denotes a relative path to _src/js/. Also notice that the .js extension is optional.

Quick CommonJS Overview

Browserify modules are written using the CommonJS module format module.exports = .... Whenever you reference a module inside of another module with require('./module') you get a reference to whatever that module exports.

For example:

a.js

module.exports = {
  property1: 'Hello',
  property2: '!'
};

This file exports an object with two properties.

b.js

var a = require('./a');

module.exports = function(input) {
  return a.property1 + ' ' + input + a.property2;
};

This module references a.js and has access to the two properties it exported. It exports a function that can take a parameter input when being called from another module.

c.js

var b = require('./b');

module.exports = function() {
  var sayHello = b('George');

  console.log(sayHello);
};

This module exports a function that calls the function exported by b, passing it a string, and then logs the result to the console. But of course c's function doesn't do anything until it is called from another module.

d.js

var c = require('./c');

c();
// "Hello George!"

Finally, d uses c which requires b which requires a.

Note that a.js could be rewritten like this:

module.exports.property1 = 'Hello';
module.exports.property2 = '!';

or simply:

exports.property1 = 'Hello';
exports.property2 = '!';

Relative Dependencies

Whenever you use require you reference your own modules by prepending the filename with ./path/to/. This tells Browserify to look for a module relative to the current one. If you only use the filename Browserify will think that you are trying to reference a module inside the node_modules directory which was installed with npm.

tl;dr

Reference a file in the same directory:

var module = require('./module');

Reference a file in a child directory:

var module = require('./myfolder/module');

Reference a file in a sibling directory:

var module = require('../module');

Reference a module installed with npm install module:

var module = require('module');

waitFor Helper

_src/js/lib/waitFor.js

waitFor is a simple helper module you can use to keep a module's functionality from running until a selector is in the DOM. After running the init task you will also notice that this file has been aliased inside of package.json so that you can simply use require('waitFor') inside of your modules. That way you don't have to mess with all the relative paths.

Examples:

var waitFor = require('waitFor');

function hello() {
  console.log('Hello!');
}

waitFor('header.some-class', hello);

or multiple selectors

waitFor('header.some-class, .another-class', hello);

Transforms

Browserify can utilize transform modules, like Babel or CoffeeScript, to transform your module's code. Declare your transforms in the configuration object that you pass into your instance of gulp-eta and Browserify will handle that.

Here's a good list of Browserify Transforms

Eta makes use of the EJS and Browserify Shim transforms.