CommonJS Everywhere

CommonJS (node module) browser bundler with source maps from the minified JS bundle to the original source, aliasing for browser overrides, and extensibility for arbitrary compile-to-JS language support.

Install

npm install -g commonjs-everywhere

Usage

CLI

$ bin/cjsify --help

  Usage: cjsify OPT* path/to/entry-file.ext OPT*

  -m, --minify            minify output
  -o, --output FILE       output to FILE instead of stdout
  -r, --root DIR          unqualified requires are relative to DIR (default: cwd)
  -v, --verbose           verbose output sent to stderr
  -w, --watch             watch input files/dependencies for changes and rebuild bundle
  -x, --export NAME       export the given entry module as NAME
  --deps                  do not bundle; just list the files that would be bundled
  --help                  display this help message
  --ignore-missing        continue without error when dependency resolution fails
  --node                  include process object; emulate node environment (default: on)
  --source-map-file FILE  output a source map to FILE

Note: use - as an entry file to accept JavaScript over stdin

Note: to disable an option, prefix it with no-, e.g. --no-node

Example:

Common usage

cjsify src/entry-file.js --export MyLibrary --source-map-file my-library.js.map >my-library.js

Watch entry file, its dependencies, even newly added dependencies. Use verbose flag to show that only the files that need to be rebuilt are touched.

cjsify -wvo my-library.js -x MyLibrary src/entry-file.js

Module Interface

cjsifySync(entryPoint, root, options) → Spidermonkey AST

Bundles the given file and its dependencies; returns a Spidermonkey AST representation of the bundle. Run the AST through escodegen to generate JS code.

• entryPoint is a file relative to process.cwd() that will be the initial module marked for inclusion in the bundle as well as the exported module
• root is the directory to which unqualified requires are relative; defaults to process.cwd()
• options is an optional object (defaulting to {}) with zero or more of the following properties
  • export: a variable name to add to the global scope; assigned the exported object from the entryPoint module. Any valid Left-Hand-Side Expression may be given instead.
  • aliases: an object whose keys and values are root-rooted paths (/src/file.js), representing values that will replace requires that resolve to the associated keys
  • handlers: an object whose keys are file extensions ('.roy') and whose values are functions from the file contents to a Spidermonkey-format JS AST like the one esprima produces. Handles for CoffeeScript and JSON are included by default. If no handler is defined for a file extension, it is assumed to be JavaScript.
  • node: a falsey value causes the bundling phase to omit the process stub that emulates a node environment
  • verbose: log additional operational information to stderr
  • ignoreMissing: continue without error when dependency resolution fails

cjsify(entryPoint, root, options, callback) → void

Same as cjsifySync, except takes a callback that is given err and bundle arguments.

Examples

CLI example

Say we have the following directory tree:

* todos/
  * components/
    * users/
      - model.coffee
    * todos/
      - index.coffee
  * public/
    * javascripts/

Running the following command will export index.coffee and its dependencies as App.Todos.

cjsify -o public/javascripts/app.js -x App.Todos -r components components/todos/index.coffee

Since the above command specifies components as the root directory for unqualified requires, we are able to require components/users/model.coffee with require 'users/model'. The output file will be public/javascripts/app.js.

Node Module Example

jsAst = (require 'commonjs-everywhere').cjsifySync 'src/entry-file.coffee', __dirname,
  export: 'MyLibrary'
  aliases:
    '/src/module-that-only-works-in-node.coffee': '/src/module-that-does-the-same-thing-in-the-browser.coffee'
  handlers:
    '.roy': (roySource, filename) ->
      # the Roy compiler outputs JS code right now, so we parse it with esprima
      (require 'esprima').parse (require 'roy').compile roySource, {filename}

{map, code} = (require 'escodegen').generate jsAst,
  sourceMapRoot: __dirname
  sourceMapWithCode: true
  sourceMap: true

Sample Output