title: The mind-boggling universe of JavaScript Module strategies
url: https://www.airpair.com/javascript/posts/the-mind-boggling-universe-of-javascript-modules
hash_url: 85169542c2bb95c8424a3081ec0b90b1

<p>If you feel like, no matter what you do, there is always something funky in your JavaScript code, I would bet that your Module strategy is not working out so well.</p>
<p>The importance of adopting a proper JavaScript Module strategy is often underestimated as a preference contest, so it is important to truly understand your needs. This article exposes the foundations of different JavaScript Module strategies such as ad hoc, CommonJS, AMD and ES6 modules, and how to get started with ES6 modules right now.</p>
<h2 id="javascript-module-101">JavaScript Module 101</h2>
<p>In brief terms, JavaScript Modules were created in order to apply some classic Object Orientation ideas when building components, once the current JavaScript language support for those ideas isn't as explicit as in other languages as C++, Java and Ruby.</p>
<p>In order to build a module as a special type of object, which strongly needs to leverage encapsulation, we need to add support for declaring private/public attributes and methods inside a single object. Enter the <a href="http://addyosmani.com/resources/essentialjsdesignpatterns/book/#modulepatternjavascript">Module pattern</a>, where such encapsulation is achieved through <strong>function closures</strong>, taking advantage of the <strong>function scope</strong> to publicly disclose only what is necessary through the return of the function. </p>
<p>Look at the following example for an ad hoc module implementation:</p>
<p><strong>zoo.js:</strong></p>
<pre><code class="lang-javascript">var Zoo = (function() { 
  var getBarkStyle = function(isHowler) {
    return isHowler? 'woooooow!': 'woof, woof!';
  }; 
  var Dog = function(name, breed) {
    this.bark = function() {
      return name + ': ' + getBarkStyle(breed === 'husky');
    };
  };
  var Wolf = function(name) {
    this.bark = function() {
      return name + ': ' + getBarkStyle(true);
    };
  };
  return {
    Dog: Dog,
    Wolf: Wolf
  };
})();
</code></pre>
<p>In <code>zoo.js</code>, we have built the module <code>Zoo</code> which only publicly exposes the functions <code>Dog</code> and <code>Wolf</code>, keeping the function <code>getBarkStyle</code> as private to the module. Precisely, this implementation is a module variation known as the <a href="http://addyosmani.com/resources/essentialjsdesignpatterns/book/#revealingmodulepatternjavascript">Revealing Module pattern</a>.</p>
<p>Now, let's see how to consume this module:</p>
<p><strong>main.js:</strong> </p>
<pre><code class="lang-javascript">var myDog = new Zoo.Dog('Sherlock', 'beagle');
console.log(myDog.bark()); // Sherlock: woof, woof!

var myWolf = new Zoo.Wolf('Werewolf');
console.log(myWolf.bark()); // Werewolf: woooooow!
</code></pre>
<p>In <code>main.js</code>, we are reading the global variable <code>Zoo</code> and instantiating <code>Dog</code> and <code>Wolf</code> from it. Note here that <code>Zoo</code> is also serving as a namespace for its functions, which is encouraged over root-level functions in order to avoid conflicts with other modules defining functions with similar names. </p>
<p>I have put together a full <a href="http://tiagorg.com/js-modules/ad-hoc/index.html">live example of the ad-hoc module</a>. You can also <a href="https://github.com/tiagorg/js-modules/tree/gh-pages/ad-hoc">check the source code</a>.</p>
<h2 id="ok-modules-are-cool-but-why-should-i-use-them-">Ok, modules are cool, but why should I use them?</h2>
<p>Just to name a few reasons why every JavaScript developer should use modules as much as possible:</p>
<ul>
<li>Writing scattered global JavaScript code is bad for performance, terrible for reusability, causes awkward readability, is painful for side-effects, and horrible for code organization.</li>
<li>In JavaScript, literal objects' attributes and methods are all public, making it impossible to conceal internal details of objects, which is a real demand for Components, Features, Subsystems and Façades.</li>
<li>A module can be delivered as a dependency for other modules, leveraging a composite architecture of reusable components, when properly implemented.</li>
<li>Modules can also be packaged and deployed separately from each other, allowing changes on a particular module to be properly isolated from everything else, therefore mitigating those dreaded side-effects known as the "butterfly effect" (yes, just like the movie).</li>
<li>Splitting your global code into modules is the first step on bringing cohesion up and coupling down.</li>
</ul>
<h2 id="to-be-or-not-to-be-commonjs-or-amd-">To be or not to be, CommonJS or AMD?</h2>
<p>Have another look on the ad hoc module example above. Since we are defining 2 files, we are still writing and reading the variable <code>Zoo</code> into the global JavaScript context. This is definitely not recommended, because it is:</p>
<ul>
<li>fragile (as it is possible for any posterior code to modify/redefine your module),</li>
<li>not scalable (if you need to define 100 modules, all of them will be loaded on the global JavaScript context, even if you end up consuming just 1 out of those 100 modules, making it really bad for performance),</li>
<li>counter-productive (you have to manually resolve your dependencies, and you would need to remember to bring them altogether if you were to use your module in another application).</li>
</ul>
<p>A good solution for such setbacks is adopting a Module Loader. As a matter of fact, it would be entirely possible for you to write your own module loader! A simple homemade loader would just need to register modules under aliases, resolve dependencies through Dependency Injection and instantiate the modules through a Factory.</p>
<p>Over the course of time, many developers started to elaborate around modules and module loaders, striving for defining a multi-purpose Module Standard. After some coming and going, two module standards have gained some momentum:</p>
<h3 id="1-commonjs">1) CommonJS</h3>
<p><a href="http://www.commonjs.org/"><strong>CommonJS</strong></a> is a standard for <strong>synchronous</strong> modules.</p>
<p><strong>Pros:</strong></p>
<ul>
<li>It was adopted as the official module format for <a href="https://nodejs.org">Node.js</a> and <a href="http://npmjs.com">NPM</a> components. This means that any module defined in CommonJS will have access to the whole NPM ecosystem.</li>
<li>It has a simple and convenient syntax.</li>
<li>It is possible to guarantee the order of execution of modules.</li>
</ul>
<p><strong>Cons:</strong></p>
<ul>
<li>It doesn't naturally work on the browser, however there are great solutions for this constraint as <a href="http://browserify.org">Browserify</a> and <a href="http://webpack.github.io">Webpack</a>.</li>
<li>Since it is synchronous, the modules have to be loaded sequentially, which might take more time than if they were to be loaded asynchronously.</li>
<li>Usually, NPM modules are composed by many other modules, which means that you might end up depending on a high number of modules, and your bundles can easily get big.</li>
</ul>
<p><strong>When to use:</strong> CommonJS is already a mature standard for the server-side, and a good option for the client-side when the Javascript bundles executed during the page load time are not too big.</p>
<p><strong>How to use:</strong> Your module file will publicly expose whatever is assigned to <code>module.exports</code> while everything else is private. In order to use your module, the client code needs to use the <code>require(dependency)</code> function, referencing your module per file location or alias.</p>
<p>Check out the following example:</p>
<p><strong>zoo.js:</strong></p>
<pre><code class="lang-javascript">var getBarkStyle = function(isHowler) {
  return isHowler? 'woooooow!': 'woof, woof!';
}; 
var Dog = function(name, breed) {
  this.bark = function() {
    return name + ': ' + getBarkStyle(breed === 'husky');
  };
};
var Wolf = function(name) {
  this.bark = function() {
    return name + ': ' + getBarkStyle(true);
  };
};

module.exports = {
  Dog: Dog,
  Wolf: Wolf
};
</code></pre>
<p>Note that the public content is returned at once through <code>module.exports</code>.</p>
<p><strong>main.js:</strong></p>
<pre><code class="lang-javascript">var Zoo = require('./zoo');

var myDog = new Zoo.Dog('Sherlock', 'beagle');
console.log(myDog.bark()); // Sherlock: woof, woof!

var myWolf = new Zoo.Wolf('Werewolf');
console.log(myWolf.bark()); // Werewolf: woooooow!
</code></pre>
<p>This code is also available as a <a href="http://tiagorg.com/js-modules/commonjs/index.html">live example of a Common.js module</a>. Make sure to <a href="https://github.com/tiagorg/js-modules/tree/gh-pages/commonjs">check the source code</a>. In this example I am using Browserify to transform the source code on a browser bundle.</p>
<h3 id="2-amd">2) AMD</h3>
<p><a href="https://github.com/amdjs/amdjs-api"><strong>AMD</strong></a> (Asynchronous Module Definition) is a standard for <strong>asynchronous</strong> modules.</p>
<p><strong>Pros:</strong></p>
<ul>
<li>Multiple modules can be loaded in parallel.</li>
<li>It naturally works on the browser.</li>
<li>It is very convenient to defer the loading of modules that are not necessary on page load.</li>
</ul>
<p><strong>Cons:</strong></p>
<ul>
<li>Asynchronous loading is a complex subject and it can easily create race conditions if not properly designed.</li>
<li>It isn't possible to guarantee the order of execution of asynchronous modules.</li>
<li>Its syntax can get hard to understand, specially when the dependencies array is large.</li>
</ul>
<p><strong>When to use:</strong> AMD is specially interesting for client-side applications that can benefit from the lazy loading of modules, when this can be properly leveraged.</p>
<p><strong>How to use:</strong> Your module will publicly expose whatever is being returned on the callback function, similarly to our first ad hoc example. In order to use your module, the client code needs to refer to it (per file location or alias) on its dependencies array, which will map to an argument on its own callback function.</p>
<p>The following example uses the quintessential AMD implementation, <a href="http://requirejs.org">Require.js</a>, where it declares the <code>zoo</code> module using <code>define(alias, dependenciesArray, callbackFunction)</code> and consumes it later using <code>require(dependenciesArray, callbackFunction)</code>:</p>
<p><strong>zoo.js:</strong></p>
<pre><code class="lang-javascript">define('zoo', [], function() {
  var getBarkStyle = function (isHowler) {
    return isHowler? 'woooooow!': 'woof, woof!';
  }; 
  var Dog = function (name, breed) {
    this.bark = function() {
      return name + ': ' + getBarkStyle(breed === 'husky');
    };
  };
  var Wolf = function (name) {
    this.bark = function() {
      return name + ': ' + getBarkStyle(true);
    };
  };
  return {
    Dog: Dog,
    Wolf: Wolf
  };
});
</code></pre>
<p>Note that the public content is returned at once through the function return, just like the ad hoc implementation.</p>
<p><strong>main.js:</strong></p>
<pre><code class="lang-javascript">require(['zoo'], function(Zoo) {
  var myDog = new Zoo.Dog('Sherlock', 'beagle');
  console.log(myDog.bark()); // Sherlock: woof, woof!

  var myWolf = new Zoo.Wolf('Werewolf');
  console.log(myWolf.bark()); // Werewolf: woooooow!
});
</code></pre>
<p>This code is also available as a <a href="http://tiagorg.com/js-modules/amd/index.html">live example of an AMD module</a>. Make sure to <a href="https://github.com/tiagorg/js-modules/tree/gh-pages/amd">check the source code</a>.</p>
<h3 id="is-there-any-interop-">Is there any interop?</h3>
<p>As you might guess, you will run into both standards quite frequently, and there will be times you might want to use a CommonJS module with an AMD component and vice-versa. Please allow me to spoil your surprise: these standards are not naturally compatible!</p>
<p>Nevertheless, a number of approaches are there to provide more compatibility between CommonJS and AMD, striving to come up with a way to write your module just once and have it working on both standards. Great interop examples are <a href="https://github.com/umdjs/umd">UMD</a>,  <a href="https://github.com/systemjs/systemjs">SystemJS</a> and <a href="http://urequire.org">uRequire</a>.</p>
<p>AMD aficionados might also consider <a href="https://github.com/jrburke/almond">Almond</a>, a nifty lightweight AMD implementation which natively supports both synchronous and asynchronous loading. It is not really interop, however it is a single solution that benefits from both worlds.</p>
<h2 id="now-forget-about-that-es6-is-right-around-the-corner-">Now, forget about that. ES6 is right around the corner!</h2>
<p>Earlier I've affirmed that the JavaScript language support for Modules isn't much explicit on its current version (officially known as ECMAScript 5 or just ES5). However, it turns out that JavaScript Modules <strong>have just become explicit</strong>!</p>
<p>The upcoming version of JavaScript (ECMAScript 6 or ES6) offers native support for modules in a compact and effective way, quite a bit similar to CommonJS. See how it will look like:</p>
<p><strong>zoo.js:</strong>    </p>
<pre><code class="lang-javascript">var getBarkStyle = function(isHowler) {
  return isHowler? 'woooooow!': 'woof, woof!';
}; 
export function Dog(name, breed) {
  this.bark = function() {
    return name + ': ' + getBarkStyle(breed === 'husky');
  };
}
export function Wolf(name) {
  this.bark = function() {
    return name + ': ' + getBarkStyle(true);
  };
}
</code></pre>
<p>Note that now we can have more than one <code>export</code> per module. This way, the client code can choose which functions it wants to <code>import</code> from the module:</p>
<p><strong>main.js:</strong></p>
<pre><code class="lang-javascript">import { Dog, Wolf } from './zoo';

var myDog = new Dog('Sherlock', 'beagle');
console.log(myDog.bark()); // Sherlock: woof, woof!

var myWolf = new Wolf('Werewolf');
console.log(myWolf.bark()); // Werewolf: woooooow!
</code></pre>
<p>This code is also available as a <a href="http://tiagorg.com/js-modules/es6/index.html">live example of an ES6 module</a>. Make sure to <a href="https://github.com/tiagorg/js-modules/tree/gh-pages/es6">check the source code</a>. 
Not only ES6 has brought modules, but it also brought a solution for the CommonJS vs AMD battle! According to this <a href="http://www.2ality.com/2014/09/es6-modules-final.html">Dr. Axel Rauschmayer's article</a>, ES6 modules will support both synchronous and asynchronous loading within the same syntax. And even better, they will work both on the browser and on the server!</p>
<p>One more piece of good news: this syntax is finalized, so further syntax changes aren't expected for ES6 Modules. This means that you can start learning it right now!</p>
<h2 id="babel-to-the-rescue">Babel to the rescue</h2>
<p>Using ES6 modules sound thrilling, but since they are targeted for June 2015, what can you do before it gets released and adopted by all the major browsers and devices?</p>
<p>Enter <a href="https://babeljs.io/">Babel</a>, my personal choice of ES6 to ES5 transpiler (a transpiler is a source-to-source compiler, i.e., it will transform ES6 source code into ES5 source code). Babel works for both client-side and server-side JavaScript.</p>
<p>To implement the example above, I am using the <a href="https://github.com/babel/babelify">Babelify plugin</a> over Browserify to transform the ES6 source code directly into an ES5 browser bundle. However, it would be just as simple to transpile the files individually, if you are curious to know how the ES5 source would be. You can even choose it to be transpiled to a specific format, like Common.js or AMD! All you would need to do is:</p>
<pre><code class="lang-bash">npm install -g babel
babel --modules common zoo.js -o zoo-commonjs.es6
babel --modules amd zoo.js -o zoo-amd.es6
</code></pre>
<p>Since in a real project you are hopefully not transpiling files manually, but instead adopting some build system to do that for you, you will be very happy to know that Babel supports most of builders and assets pipelines, and even Rails is on the list! Check out how Babel integrates with your <a href="https://babeljs.io/docs/using-babel/#build-systems">favorite asset pipeline</a>.</p>
<h2 id="who-you-gonna-call-">Who you gonna call?</h2>
<p>Modules are a big deal for sure. All the most successful MV* frameworks rely on a strong module-oriented architecture, such as AngularJS, Ember.js, Marionette.js and React. This is why the JavaScript community is so concerned with helping everyone use them as seamless as possible, as you can see with the ES6 modules initiative.</p>
<p>However, we still have to take into consideration the plethora of existing code which is too big to be rewritten into ES6 anytime soon. Depending on the size, complexity and risk of the project, this might never happen. Still, even if all the major browsers start supporting ES6 this year, it would take a handful of years for most of the worldwide population (or at least your clients) to be effectively using those browser versions supporting ES6. Just for an example [cue the sad-trombone], IE 8 was released exactly 6 years ago.</p>
<p>Anyhow, the other way around is totally feasible and recommended. Writing new code on ES6 with a good transpiler is totally worth taking a deep look at. The benefits are great: more concise syntax, great support for the current Module strategies, and the best thing: you are embracing the future of JavaScript!</p>
<p>When in doubt, remember that Fortune favors the brave. Or just remember Ghostbusters: I ain't afraid of no ghost.</p>
