Table of Contents for

JavaScript Web Applications

Declaring a CommonJS module is fairly straightforward. Namespacing is baked directly in; modules are separated into different files, and they expose variables publicly by adding them to an interpreter-defined exports object:

// maths.js
exports.per = function(value, total) {
  return( (value / total) * 100 );
};

// application.js
var Maths = require("./maths");
assertEqual( Maths.per(50, 100), 50 );

To use any functions defined in a module, simply require() the file, saving the result in a local variable. In the example above, any functions exported by maths.js are available on the Maths variable. The key is that modules are namespaced and will run on all CommonJS-compliant JavaScript interpreters, such as Narwhal and Node.js.

So, how does this relate to client-side JS development? Well, lots of developers saw the implications of using modules on the client side—namely, that the standard, as it currently stood, required CommonJS modules to be loaded in synchronously. This is fine for server-side JavaScript, but it can be very problematic in the browser because it locks up the UI and requires eval-based compilation of scripts (always something to be avoided). The CommonJS team developed a specification, the module transport format, to address this issue. This transport format wraps CommonJS modules with a callback to allow for asynchronous loading on clients.

Let’s take our module example above. We can wrap it in the transport format to allow asynchronous loading, making it palatable for the browser:

// maths.js
require.define("maths", function(require, exports){

  exports.per = function(value, total) {
    return( (value / total) * 100 );
  };

});

// application.js
require.define("application", function(require, exports){

  var per = require("./maths").per;
  assertEqual( per(50, 100), 50 );

}, ["./maths"]); // List dependencies (maths.js)

Our modules can then be required by a module loader library and executed in the browser. This is a really big deal. Not only have we split up our code into separate module components, which is the secret to good application design, but we’ve also got dependency management, scope isolation, and namespacing. Indeed, the same modules can be run on browsers, servers, in desktop apps, and in any other CommonJS-compliant environment. In other words, it’s now possible to share the same code between server and client!

Yabble is an excellent and lightweight module loader. You can configure Yabble to either request modules with XHR or to use script tags. The advantage to fetching modules with XHR is that they don’t need wrapping in the transport format. However, the disadvantage is that modules have to be executed using eval(), making debugging more difficult. Additionally, there are cross-domain issues, especially if you’re using a CDN. Ideally, you should only use the XHR option for quick and dirty development, certainly not in production:

<script src="https://github.com/jbrantly/yabble/raw/master/lib/yabble.js"> </script>
<script>
  require.setModuleRoot("javascripts");

  // We can use script tags if the modules
  // are wrapped in the transport format
  require.useScriptTags();

  require.ensure(["application", "utils"], function(require) {
    // Application is loaded
  });
</script>

The above example will fetch our wrapped application module and then load its dependencies, utils.js, before running the module. We can load modules using the require() function:

<script>
  require.ensure(["application", "utils"], function(require) {
    var utils = require("utils");
    assertEqual( utils.per( 50, 200 ), 25 );
  });
</script>

Although utils is required twice—once by the inline require.ensure() function, and once by the application module—our script is clever enough to fetch the module only once. Make sure any dependencies your module needs are listed in the transport wrapping.

A great alternative to Yabble is RequireJS, one of the most popular loaders. RequireJS has a slightly different take on loading modules—it follows the Asynchronous Module Definition format, or AMD. The main difference you need to be concerned with is that the API evaluates dependencies eagerly, rather than lazily. In practice, RequireJS is completely compatible with CommonJS modules, requiring only different wrapping transport.

To load JavaScript files, just pass their paths to the require() function, specifying a callback that will be invoked when the dependencies are all loaded:

<script>
  require(["lib/application", "lib/utils"], function(application, utils) {
    // Loaded!
  });
</script>

As you can see in the example above, the application and utils modules are passed as arguments to the callback; they don’t have to be fetched with the require() function.

It’s not just modules that you can require—RequireJS also supports ordinary JavaScript libraries as dependencies, specifically jQuery and Dojo. Other libraries will work, but they won’t be passed correctly as arguments to the required callback. However, any library that has dependencies is required to use the module format:

require(["lib/jquery.js"], function($) {
  // jQuery loaded
  $("#el").show();
});

Paths given to require() are relative to the current file or module, unless they begin with a /. To help with optimization, RequireJS encourages you to place your initial script loader in a separate file. The library even provides shorthand to do this: the data-main attribute:

<script data-main="lib/application" src="lib/require.js"></script>

Setting the data-main attribute instructs RequireJS to treat the script tag like a require() call and load the attribute’s value. In this case, it would load the lib/application.js script, which would in turn load the rest of our application:

// Inside lib/application.js
require(["jquery", "models/asset", "models/user"], function($, Asset, User) {
    //...
});

So, we’ve covered requiring modules, but what about actually defining them? Well, as stated previously, RequireJS uses a slightly different syntax for modules. Rather than using require.define(), just use the plain define() function. As long as modules are in different files, they don’t need explicit naming. Dependencies come first, as an array of strings, and then comes a callback function containing the actual module. As in the RequireJS require() function, dependencies are passed as arguments to the callback function:

define(["underscore", "./utils"], function(_, Utils) {
  return({
    size: 10
  })
});

By default, there’s no exports variable. To expose variables from inside the module, just return data from the function. The benefit to RequireJS modules is that they’re already wrapped up, so you don’t have to worry about transport formats for the browser. However, the caveat to this API is that it’s not compatible with CommonJS modules—i.e., you couldn’t share modules between Node.js and the browser. All is not lost, though; RequireJS has a compatibility layer for CommonJS modules—just wrap your existing modules with the define() function:

define(function(require, exports) {
  var mod = require("./relative/name");

  exports.value = "exposed";
});

The arguments to the callbacks need to be exactly as shown above—i.e., require and exports. Your modules can then carry on using those variables as usual, without any alterations.

LABjs is one of the simplest dependency management solutions out there. It doesn’t require any server-side involvement or CommonJS modules. Loading your scripts with LABjs reduces resource blocking during page load, which is an easy and effective way to optimize your site’s performance. By default, LABjs will load and execute scripts in parallel as fast as possible. However, you can easily specify the execution order if some scripts have dependencies:

<script>
  $LAB
  .script('/js/json2.js')
  .script('/js/jquery.js').wait()
  .script('/js/jquery-ui.js')
  .script('/js/vapor.js');
</script>

In the above example, all the scripts load in parallel, but LABjs ensures jquery.js is executed before jquery-ui.js and vapor.js. The API is incredibly simple and succinct, but if you want to learn about LABjs’ more advanced features, such as support for inline scripts, check out the documentation.