capsule-js

capsule

Simple browser module system.

// src/foo.js
capsule('foo', function(exports) {
  capsule('external-dep');
  capsule('bundled-dep');
  exports.bar = capsule('foo.bar');
});


// src/bar.js
capsule('foo.bar', function(exports, module) {
  module.exports = function() { return 23; };
});

$ capsule -m foo -e external-dep bundled-dep.js src/**/*.js > foo.js

// somewhere in browser global land
foo.bar();  // 23


// somewhere in amd land
define(['foo'], function(foo) {
  foo.bar();  // 23
});


// somewhere in commonjs land
var foo = require('foo');
foo.bar();

why another module system?

Even with the awesome browserify, I wasn't finding the things I needed in a module system:

importable external dependencies: I needed control over which dependencies are bundled, and which stay outside of the bundle, while still allowing importing of the external modules in any environment the bundle is placed in (amd, commonjs or browser global land).

a better module system for browser-based tests: I needed a module system that can be used directly with browser-based tests, without a bundling step obscuring stack traces and slowing down each test run (and no shims, plugins, preprocessors or duct tape to attempt to fix things)

when to use

capsule is suited to browser based projects (both library and non-library projects). For projects where the tests can be run from nodejs in a sensible way, use browserify instead.

install

To use cli:

# npm install -g capsule-js
$ capsule --help
Usage: capsule [options] [files to bundle]

Options:
  --help          Show help                     
  -m, --main      Name of the entry point module
  -e, --external  Add an external dependency    

To use bundler:

$ npm install capsule-js

var capsule = require('capsule-js/bundler');

To use in browser:

$ bower install capsule-js

<script src="/bower_components/capsule-js/capsule.js"></script>

example

bundler api

capsule(files)

Creates a new bundler. files can be a string (eg. 'foo.js'), an array (eg. ['foo.js', 'bar.js']), a glob string or array, or a readable text stream. All files that should be bundled should be provided, including the dependencies that should be bundled.

var b = capsule('src/**/*.js');

.main(name)

Configures the bundler to use the module with the given name as the entry point for accessing the bundle as a standalone module in amd, commonjs and browser global land.

capsule('src/**/*.js')
  .main('foo');

.externals(names)

Configures the bundler to recognise the given names as external dependencies. When modules inside the bundle try import the named modules, the modules will be imported according to the environment the bundle is used in (amd, commonjs or browser global land).

capsule('src/**/*.js')
  .externals(['d3']);

Environment-dependent mappings can also be made. name is used as both the module import name inside capsule and the default for the module's name in each environment.

capsule('src/**/*.js')
  .externals([{
    name: 'lodash',
    global: '_'
  }, {
    name: 'jquery',
    global: '$',
    amd: 'jquery',
    commonjs: 'jquery'
  }]);

.bundle([fn])

Initiates the bundling and returns a readable text stream of the result. If fn is provided, it will be called as fn(err) if an error occurs during the bundling, or as fn(null, data) when the bundling completes, where err is an error object and data is the concatenated result of the bundling.

capsule('src/**/*.js')
  .bundle()
  .pipe(process.stdout);

The returned stream is q-stream based, so its promise will be resolved when the bundling completes, or rejected with an error object if the bundling fails.

capsule('src/**/*.js')
  .bundle()
  .promise()
  .then(success, failure)
  .done();

function success() { console.log(':)'); }
function failure(err) { console.log(err); }

capsule api

capsule(name[, fn])

Imports, defines or clears the module represented by name.

If fn is a function, the function will be used to define the module. The function is given the arguments exports and module. exports is an empty data object which should be populated with the module's exports. module is a data object with exports as its only property, and allows for cases where a new exports value needs to be assigned.

capsule('foo', function(exports, module){
  exports.bar = function() { return 23; };
});

If fn is not given, the module will be imported. capsule will first look for explicitly defined modules, then already loaded modules, then properties attached to the this context created for the bundle, then properties in the global namespace.

capsule('foo').bar();

If fn is null, the module will be cleared and will no longer be accessible.

capsule('foo', null);

capsule.exists(name)

Returns whether a module of the given name exists as either a defined or loaded module, bundle-global module, or an environment global.

capsule.alias(src, dest)

Creates a new module with the name dest that uses the module with the name src as its exports value.

capsule('foo', function(exports, module) { module.exports = 3; });
capsule.alias('foo', 'bar');
capsule('bar');  // 3

Useful as a test setup step when a global module (eg. $) needs to be importable under a different name (eg. jquery) to match how the module's external dependencies are configured during bundling (see .externals).