Writing Modular JavaScript With AMD, CommonJS & ES Harmony
Modularity The Importance Of Decoupling Your Application
When we say an application is modular, we generally mean it's composed of a set of highly decoupled, distinct pieces of functionality stored in modules. As you probably know, loose coupling facilitates easier maintainability of apps by removing dependencies where possible. When this is implemented efficiently, its quite easy to see how changes to one part of a system may affect another.
Unlike some more traditional programming languages however, the current iteration of JavaScript (ECMA-262) doesn't provide developers with the means to import such modules of code in a clean, organized manner. It's one of the concerns with specifications that haven't required great thought until more recent years where the need for more organized JavaScript applications became apparent.
Instead, developers at present are left to fall back on variations of the module or object literal patterns. With many of these, module scripts are strung together in the DOM with namespaces being described by a single global object where it's still possible to incur naming collisions in your architecture. There's also no clean way to handle dependency management without some manual effort or third party tools.
Whilst native solutions to these problems will be arriving in ES Harmony, the good news is that writing modular JavaScript has never been easier and you can start doing it today.
In this article, we're going to look at three formats for writing modular JavaScript: AMD,CommonJS and proposals for the next version of JavaScript, Harmony.
Prelude A Note On Script Loaders
It's difficult to discuss AMD and CommonJS modules without talking about the elephant in the room - script loaders. At present, script loading is a means to a goal, that goal being modular JavaScript that can be used in applications today - for this, use of a compatible script loader is unfortunately necessary. In order to get the most out of this article, I recommend gaining a basic understanding of how popular script loading tools work so the explanations of module formats make sense in context.
There are a number of great loaders for handling module loading in the AMD and CJS formats, but my personal preferences are RequireJS and curl.js. Complete tutorials on these tools are outside the scope of this article, but I can recommend reading John Hann's post about curl.js and James Burke's RequireJS API documentation for more.
From a production perspective, the use of optimization tools (like the RequireJS optimizer) to concatenate scripts is recommended for deployment when working with such modules. Interestingly, with the Almond AMD shim, RequireJS doesn't need to be rolled in the deployed site and what you might consider a script loader can be easily shifted outside of development.
That said, James Burke would probably say that being able to dynamically load scripts after page load still has its use cases and RequireJS can assist with this too. With these notes in mind, let's get started.
AMD A Format For Writing Modular JavaScript In The Browser
The overall goal for the AMD (Asynchronous Module Definition) format is to provide a solution for modular JavaScript that developers can use today. It was born out of Dojo's real world experience using XHR+eval and proponents of this format wanted to avoid any future solutions suffering from the weaknesses of those in the past.
The AMD module format itself is a proposal for defining modules where both the module and dependencies can be asynchronously loaded. It has a number of distinct advantages including being both asynchronous and highly flexible by nature which removes the tight coupling one might commonly find between code and module identity. Many developers enjoy using it and one could consider it a reliable stepping stone towards the module systemproposed for ES Harmony.
AMD began as a draft specification for a module format on the CommonJS list but as it wasn't able to reach full concensus, further development of the format moved to the amdjsgroup.
Today it's embraced by projects including Dojo (1.7), MooTools (2.0), Firebug (1.8) and even jQuery (1.7). Although the term CommonJS AMD format has been seen in the wild on occasion, it's best to refer to it as just AMD or Async Module support as not all participants on the CJS list wished to pursue it.
Getting Started With Modules
The two key concepts you need to be aware of here are the idea of a define method for facilitating module definition and a require method for handling dependency loading.define is used to define named or unnamed modules based on the proposal using the following signature:
- define(
- module_id /*optional*/,
- [dependencies] /*optional*/,
- definition function /*function for instantiating the module or object*/
- );
As you can tell by the inline comments, the module_id is an optional argument which is typically only required when non-AMD concatenation tools are being used (there may be some other edge cases where it's useful too). When this argument is left out, we call the module anonymous.
When working with anonymous modules, the idea of a module's identity is DRY, making it trivial to avoid duplication of filenames and code. Because the code is more portable, it can be easily moved to other locations (or around the file-system) without needing to alter the code itself or change its ID. The module_id is equivalent to folder paths in simple packages and when not used in packages. Developers can also run the same code on multiple environments just by using an AMD optimizer that works with a CommonJS environment such as r.js.
Back to the define signature, the dependencies argument represents an array of dependencies which are required by the module you are defining and the third argument ('definition function') is a function that's executed to instantiate your module. A barebone module could be defined as follows:
Understanding AMD: define()
- // A module_id (myModule) is used here for demonstration purposes only
- define('myModule',
- ['foo', 'bar'],
- // module definition function
- // dependencies (foo and bar) are mapped to function parameters
- function ( foo, bar ) {
- // return a value that defines the module export
- // (i.e the functionality we want to expose for consumption)
- // create your module here
- var myModule = {
- doStuff:function(){
- console.log('Yay! Stuff');
- }
- }
- return myModule;
- });
- // An alternative example could be..
- define('myModule',
- ['math', 'graph'],
- function ( math, graph ) {
- // Note that this is a slightly different pattern
- // With AMD, it's possible to define modules in a few
- // different ways due as it's relatively flexible with
- // certain aspects of the syntax
- return {
- plot: function(x, y){
- return graph.drawPie(math.randomGrid(x,y));
- }
- }
- };
- });
require on the other hand is typically used to load code in a top-level JavaScript file or within a module should you wish to dynamically fetch dependencies. An example of its usage is:
Understanding AMD: require()
- // Consider 'foo' and 'bar' are two external modules
- // In this example, the 'exports' from the two modules loaded are passed as
- // function arguments to the callback (foo and bar)
- // so that they can similarly be accessed
- require(['foo', 'bar'], function ( foo, bar ) {
- // rest of your code here
- foo.doSomething();
- });
Dynamically-loaded Dependencies
- define(function ( require ) {
- var isReady = false, foobar;
- // note the inline require within our module definition
- require(['foo', 'bar'], function (foo, bar) {
- isReady = true;
- foobar = foo() + bar();
- });
- // we can still return a module
- return {
- isReady: isReady,
- foobar: foobar
- };
- });
Understanding AMD: plugins
The following is an example of defining an AMD-compatible plugin:
- // With AMD, it's possible to load in assets of almost any kind
- // including text-files and HTML. This enables us to have template
- // dependencies which can be used to skin components either on
- // page-load or dynamically.
- define(['./templates', 'text!./template.md','css!./template.css'],
- function( templates, template ){
- console.log(templates);
- // do some fun template stuff here.
- }
- });
Loading AMD Modules Using require.js
- require(['app/myModule'],
- function( myModule ){
- // start the main module which in-turn
- // loads other modules
- var module = new myModule();
- module.doStuff();
- });
Loading AMD Modules Using curl.js
- curl(['app/myModule.js'],
- function( myModule ){
- // start the main module which in-turn
- // loads other modules
- var module = new myModule();
- module.doStuff();
- });
Modules With Deferred Dependencies
- // This could be compatible with jQuery's Deferred implementation,
- // futures.js (slightly different syntax) or any one of a number
- // of other implementations
- define(['lib/Deferred'], function( Deferred ){
- var defer = new Deferred();
- require(['lib/templates/?index.html','lib/data/?stats'],
- function( template, data ){
- defer.resolve({ template: template, data:data });
- }
- );
- return defer.promise();
- });
Why Is AMD A Better Choice For Writing Modular JavaScript?
- Provides a clear proposal for how to approach defining flexible modules.
- Significantly cleaner than the present global namespace and