Browserify brings some common programming conventions to the wild west of javascript. Most important, probably, is that it makes it easier to reuse pieces of code, and handles dependencies across a broad codebase.

To use browserify, just create a new file with the .bsfy extension. The gulp javascript task will "browserify" it and save it in the same location with a .js extension. For the examples below, let's say you've made a file foobar.bsfy and put it next to your index.html.

This video helped me to get my head around what's going on here.

Imports

In your file, declare any dependencies at the top using the require keyword and the relative path to the bsfy file you want to include. Let's say you want to see if the request contained a certain query parameter, then do something with that information. We have a convenience method for dealing with query parameters in meta/www/v2/js/modules/params.bsfy, so, taking care to get the relative path right, you might start your file with:

var params = require('../v2/js/modules/params.bsfy');

Now you have a javascript object containing the functionality exported from the params.bsfy file, so you can, e.g.

var fooParam = params.get('foo')
if(fooParam){
  //do something
} else {
  //do something else
}

At this point, you can include the file in your page and it will run when called just like regular javascript (it compiles to regular javascript!). If you saved the above file as foobar.bsfy in the same directory as your index.html, include it with

deferred.push(["loadJS","foobar.js"]);

Then when the page loads, your param logic will run.

Exports

At the end of your file, export any functions you want to expose publicly, like so:

function foo(){
  console.log('foo');
}

function bar(){
  foo()
  console.log('bar');
}

module.exports = {
  "barExport": bar
}

So if you save that code to foobar.bsfy, then in a new file, baz.bsfy you simply

var myImport = require('./foobar.bsfy');
myImport.barExport();

and add this to a script tag in your html:

deferred.push(function(){
  ["loadJS","baz.js"];
});

then when the script is asynchronously loaded, the console will output:

foo
bar

A few things to note:

• loadJS("foobar.js") will define the top-level foo and bar functions, but won't run anything when it's loaded.
• myImport.foo and myImport.bar will return undefined since the former wasn't exported and the latter was exported with the name barExport.
• You should try to design your page so that it can be rendered with just css and html. If you use javascript to change the display behavior of an element, be aware that if you load the script asynchronously, you may observe a "flash" of the element changing as the script is loaded. If there's a good reason for it, the "right way" is to use javascript in a script block which will run immediately (because it blocks render). Note that you won't have access to jQuery yet, nor to any elements that are defined after your script.