Deploying JavaScript Modules

JavaScript is used in many different environments, and each environment has its own method for deploying modules. Some allow importing objects into a local namespace, but notably web browsers do not. So, what is the best way to write a module that can be safely deployed across different environments?

Anonymous closure module pattern

My example module will be implemented as an anonymous closure. It will have one public class and a private member.

(function () {
  var PublicClass = function () {};
  var PrivateMember = new Object();
})();

I will incrementally add support for each environment by detecting whether that environment is present.

Web browsers

Web browsers do not support importing into a local namespace, so I simply add PublicClass to the global window namespace.

(function () {
  var PublicClass = function () {};
  var PrivateMember = new Object();
      
  if (typeof(window) !== 'undefined') {
    // browser
    window.PublicClass = PublicClass;
  }
})();

Client must first include the module with a script HTML tag.

<script type="text/javascript" src="sample-module.js"></script>
<script type="text/javascript">
  var instance = new PublicClass();
</script>

CommonJS

CommonJS is a pattern implemented by some server-side JavaScript engines such as Node and Narwhal. In this model, a module assigns its public interface to a special exports object.

(function () {
  var PublicClass = function () {};
  var PrivateMember = new Object();
    
  if (typeof(window) !== 'undefined') {
    // browser
    window.PublicClass = PublicClass;
  } else if (typeof(exports) !== 'undefined') {
    // commonjs
    exports.PublicClass = PublicClass;
  }
})();

Clients require the module, which returns the module's exports.

var PublicClass = require('./sample-module').PublicClass;
var instance = new PublicClass();

JavaScriptCore

JavaScriptCore (or "jsc") does not follow the CommonJS pattern. Instead, when a file is included with the load function, the last value in the file is returned to the caller.

I return an object literal from the anonymous function which simulates the exports object in CommonJS. Since the anonymous function is executed as the last statement in the file, the exports are returned to the client. This case doesn't rely on any special variable such as window or exports, so I will make it default rather than detecting the JavaScriptCore environment.

(function () {
  var PublicClass = function () {};
  var PrivateMember = new Object();

  if (typeof(window) !== 'undefined') {
    // browser
    window.PublicClass = PublicClass;
  } else if (typeof(exports) !== 'undefined') {
    // commonjs
    exports.PublicClass = PublicClass;
  } else {
    // jsc (default)
    return {
      "PublicClass": PublicClass
    };
  }
})();

Clients load the module, which returns the module's exports.

var PublicClass = load('sample-module.js').PublicClass;
var instance = new PublicClass();

Why not use a global variable?

There is another JavaScript module pattern that declares a global variable to contain the module's public interface, as in this example.

var PublicClass = (function () {
  var PublicClass = function () {};
  var PrivateMember = new Object();
  return PublicClass;
})();

This pattern will work perfectly in web browsers and JavaScriptCore, but it also pollutes JavaScriptCore's global namespace. Since JavaScriptCore supports local imports, global variables should be avoided. Furthermore, this pattern does not support multiple public interfaces, e.g., a single anonymous closure that exports two public classes.

Example: GraphJS

GraphJS is a JavaScript module of mine that uses the module deployment pattern I described. It works with Node, Narwhal, Ringo, JSC, and in web browsers.

Dodgeball Cannon