install

The CommonJS module syntax is one of the most widely accepted conventions in the JavaScript ecosystem. Everyone seems to agree that require and exports are a reasonable way of expressing module dependencies and interfaces, and the tools for managing modular code are getting better all the time.

Much less of a consensus has developed around the best way to deliver CommonJS modules to a web browser, where the synchronous semantics of require pose a non-trivial implementation challenge. This module loader contributes to that confusion, yet also demonstrates that an amply-featured module loader need not stretch into the hundreds or thousands of lines.

Installation

From NPM:

npm install install

From GitHub:

cd path/to/node_modules
git clone git://github.com/benjamn/install.git
cd install
npm install .

Usage

The first step is to create an install function by calling the makeInstaller method. Note that all of the options described below are optional:

var install = require("install").makeInstaller({
  // Optional list of file extensions to be appended to required module
  // identifiers if they do not exactly match an installed module.
  extensions: [".js", ".json"],

  // If defined, the options.fallback function will be called when no
  // installed module is found for a required module identifier. Often
  // options.fallback will be implemented in terms of the native Node
  // require function, which has the ability to load binary modules.
  fallback,

  // Boolean flag indicating whether the installed code will be running in
  // a web browser.
  browser,

  // List of fields to look for in package.json files to determine the
  // main entry module of the package. The first field listed here whose
  // value is a string will be used to resolve the entry module. Defaults
  // to just ["main"], or ["browser", "main"] if options.browser is true.
  mainFields: ["browser", "main"],
});

The second step is to install some modules by passing a nested tree of objects and functions to the install function:

var require = install({
  "main.js"(require, exports, module) {
    // On the client, the "assert" module should be install-ed just like
    // any other module. On the server, since "assert" is a built-in Node
    // module, it may make sense to let the options.fallback function
    // handle such requirements. Both ways work equally well.
    var assert = require("assert");

    assert.strictEqual(
      // This require function uses the same lookup rules as Node, so it
      // will find "package" in the "node_modules" directory below.
      require("package").name,
      "/node_modules/package/entry.js"
    );

    exports.name = module.id;
  },

  node_modules: {
    package: {
      // If package.json is not defined, a module called "index.js" will
      // be used as the main entry point for the package. Otherwise the
      // exports.main property will identify the entry point.
      "package.json"(require, exports, module) {
        exports.name = "package";
        exports.version = "0.1.0";
        exports.main = "entry.js";
      },

      "entry.js"(require, exports, module) {
        exports.name = module.id;
      }
    }
  }
});

Note that the install function merely installs modules without evaluating them, so the third and final step is to require any entry point modules that you wish to evaluate:

console.log(require("./main").name);
// => "/main.js"

This is the "root" require function returned by the install function. If you're using the install package in a CommonJS environment like Node, be careful that you don't overwrite the require function provided by that system.

If you need to change the behavior of the module object that each module function receives as its third parameter, the shared Module constructor is exposed as a property of the install function returned by the makeInstaller factory:

var install = makeInstaller(options);
var proto = install.Module.prototype;

// Wrap all Module.prototype.require calls with some sort of logging.
proto.require = wrapWithLogging(proto.require);

// Add a new method available to all modules via module.newMethod(...).
proto.newMethod = function () {...};

Many more examples of how to use the install package can be found in the tests.