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 tomodule.exports
process
does not existglobal
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.jsvar helper = ;helper;// helper.jsexports { /*...*/ };
Without a prefix the transformation of the above would result in:
var helper = { var exports = moduleexports; exports { /*...*/ }; return moduleexports;}exports: {};var index = { var helper = helper; // THIS WILL NOT WORK AS EXPECTED helper; return moduleexports;}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 = ; cjs2web;
Transformation example
CommonJS code:
// src/index.jsvar two = ;var three = ;var sum = ;console;// src/numbers/two.jsmoduleexports = 2;// src/numbers/three.jsmoduleexports = 3;// src/calculation/sum.jsmodule { return a + b; };
Transformation call:
node cjs2web ./src/index.js --basePath ./src --prefix cjs_ --combine --iife
Transformation result:
{var cjs_numbers_two = { moduleexports = 2; return moduleexports;}exports: {}; var cjs_numbers_three = { moduleexports = 3; return moduleexports;}exports: {}; var cjs_calculation_sum = { module { return a + b; }; return moduleexports;}exports: {}; { var two = cjs_numbers_two; var three = cjs_numbers_three; var sum = cjs_calculation_sum; console; return moduleexports;}exports: {};};
Minified result using Closure Compiler with Simple Optimizations:
{var a={}{return a+b};console};
Minified result using Closure Compiler with Advanced Optimizations:
console;