cjs2web

cjs2web

Transform CommonJS modules to a web browser suitable format with minimal code overhead.

Motivation

There are many existing tools to transform CommonJS modules to a browser format (examples: BrowserBuild, Browserfiy, OneJS, modulr, stitch). Most of the them emulate the CommonJS environment and provide features like client side versions of native node.js modules and require().

However if you only want to use the basic CommonJS syntax such tools unnecessarily bloat your project´s effective code size.

Features

cjs2web transforms a CommonJS module and all its dependencies to a single script for the browser using the Module Pattern. This results in code which contains almost no overhead and can also be minified very well.

Supported features:

• Using require() for local modules
• Assigning members to exports
• Assigning values to module.exports

Unsupported features (now and probably in the future):

• Using require() for third party modules
• Using require() for files which do not have a "js" extension
• this refers to window, not to module.exports
• process does not exist
• global does not exist
• Client side require() does not exist

Roadmap for future features:

• Support to use require() for browser globals such window and document

Installation

npm install cjs2web -g

Usage

Command line usage

For most projects the command line usage should be sufficient.

cjs2web <filename>

Options:
  -b, --basePath  base path to exclude from generated object names                 [string]
  -p, --prefix    prefix to add to the generated object names                      [string] [default: "__"]
  -c, --combine   combines all transformed modules to one script output            [boolean]
  -i, --iife      wrap code in an immediately invoked function expression          [boolean]
  -o, --output    filename to write the generated output to                        [string]
  -w, --watch     watch transformed files for change and automatically re-execute  [boolean]

Combining and IIFE

Normally you will want to enable the combine option. Otherwise the transformation output will not be a string of code but raw module data. The iife option wraps your code in an immediately invoked function expression to reduce global variables and can only be enabled in combination with combine.

Prefix

The prefix option is very important and can lead to unexpected results if not provided. Therefore it defaults to "__". Consider the following example:

// index.js
var helper = require('./helper');
helper.doSomething();
// helper.js
exports.doSomething = function() { /*...*/ };

Without a prefix the transformation of the above would result in:

var helper = (function(module) {
    var exports = module.exports;
    exports.doSomething = function() { /*...*/ };
    return module.exports;
}({exports: {}});
var index = (function(module) {
    var helper = helper; // THIS WILL NOT WORK AS EXPECTED
    helper.doSomething();
    return module.exports;
}({exports: {}});

The helper variable inside the index object hides the variable from the outer scope and therefore results in assigning the value of the local variable to itself (which is undefined).

Recommendation: Always use a distinct and non conflicting prefix such as module_ or cjs_.

Output

When an output name is provided the result is written to the disk and not to the standard output.

Watch

The watch option causes cjs2web to watch the main module and all its dependencies and re-execute the transformation whenever one of these files changes.

Code usage

The transform function accepts an options object of which fileName is the only mandatory property. Other option properties have the same names as the explicit parameters of the command line tool. The return value is a Deferred object.

var cjs2web = require('cjs2web');

cjs2web.transform(options).then(function(result) {
  // do something with result
});

Transformation example

CommonJS code:

// src/index.js
var two = require('./numbers/two');
var three = require('./numbers/three');
var sum = require('./calculation/sum');
console.log(sum(two, three));
// src/numbers/two.js
module.exports = 2;
// src/numbers/three.js
module.exports = 3;
// src/calculation/sum.js
module.exports = function(a, b) { return a + b; };

Transformation call:

node cjs2web ./src/index.js --basePath ./src --prefix cjs_ --combine --iife

Transformation result:

(function(){
var cjs_numbers_two = (function(module) {
    module.exports = 2;
    return module.exports;
}({exports: {}}));

var cjs_numbers_three = (function(module) {
    module.exports = 3;
    return module.exports;
}({exports: {}}));

var cjs_calculation_sum = (function(module) {
    module.exports = function(a, b) { return a + b; };
    return module.exports;
}({exports: {}}));

(function(module) {
    var two = cjs_numbers_two;
    var three = cjs_numbers_three;
    var sum = cjs_calculation_sum;
    console.log(sum(cjs_numbers_two, cjs_numbers_three));
    return module.exports;
}({exports: {}}));
}());

Minified result using Closure Compiler with Simple Optimizations:

(function(){var a={},a=function(a,b){return a+b};console.log(a(2,3))})();

Minified result using Closure Compiler with Advanced Optimizations:

console.log(5);