Using curl.js with CommonJS Modules

Using curl.js with CommonJS Modules

CommonJS defines its own module standard. Unfortunately, the CommonJS Modules/1.1 standard was designed for server-side environments and doesn't support "legacy" javascript environments, such as those in browsers.

Not without help, at least.

Some frameworks, such as SproutCore, have built-in tools to "transport" CommonJS Modules (CJS modules) to the browser. AMD defines a method to do this, as well. Both of these methods are achieved by wrapping the CJS modules with a function wrapper. With AMD, the wrapper is a define() call with a specific signature.

Here's the AMD wrapper signature:

define(function (require, exports, module) {
	// your CJS module goes here
	// use require('module-id') to require dependencies
	// use exports to expose methods and properties to other modules
});

The special pseudo-dependencies are injected into the module by curl.js. These pseudo-dependencies mimic the "free variables" described in CJS. The order of these three pseudo-dependencies (require, exports, module) is critical, but not all of them must be specified. (In general though, just specify all three, if possible, for maximum compatibility with all AMD environments.)

Node.js

A special exception is made for node.js modules. Rather than use the exports variable to expose methods and properties, devs can assign their entire module to the module.exports property. This is a special feature of curl.js and is useful for exporting functions, constructors, or other modules that don't fit the strict CJS standard:

define(function (require, exports, module) {
	function MyConstructor () {}
	MyConstructor.prototype = {
		someMethod: function () {}
	};
	module.exports = MyConstructor;
});

Hybrid

curl.js also allows hybrids of AMD and CJS modules by explicitly naming the pseudo-dependencies like the following:

define(['require', 'module'], function (require, module) {
	function MyConstructor () {}
	MyConstructor.prototype = Object.create(require('BaseObject'));
	module.exports = MyConstructor;
});

Unwrapped CJS modules

curl.js 0.6 has an experimental feature to load CJS modules without wrapping them. If you specify moduleLoader: 'curl/loader/cjsm11' for a package, curl.js will assume that the entire package consists of unwrapped CJS modules and will wrap them when they arrive at the browser.

This feature is perfect for rapid development in a dev environment, but is probably not the fastest choice for production. Consider compiling and optimizing CJS modules, which will wrap them, for production environments.

Concatenating / Optimizing CJS modules

RequireJS's r.js will wrap CJS modules, as will an upcoming version of cram.js.