capsule-js

capsule

Simple browser module system.

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


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

$ capsule -m foo 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                 
  -i, --include  Add a dependency to be included in the bundle  
  -e, --exclude  Add a dependency to be excluded from the bundle

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 source files that should be bundled should be provided. Dependencies that should be bundled should be given using .includes.

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');

.includes(deps)

Configures the bundler to include the given array of dependencies in the bundle.

capsule('./src/**/*.js')
  .includes([{
    name: 'jquery',
    file: './bower_components/jquery/dist/jquery.js'
  }]);

file is the path to the dependency's source file, and is the only required option. name is the name to use when importing the module (for eg, 'foo' if one wanted to import it with capsule('foo')).

When a dependency is given as a string, the base name of file ('jquery' in the example below) will be used as the module's name.

capsule('./src/**/*.js')
  .includes(['./bower_components/jquery/dist/jquery.js']);

Each included dependency has its own module and exports available in the bundle, so if the dependency supports commonjs environments, capsule will use module.exports as the exported value.

If a dependency's global name is given, capsule will use it to look up the module in the global namespace instead of providing modules and exports to it.

capsule('./src/**/*.js')
  .includes([{
    name: 'jquery',
    global: '$',
    file: './bower_components/jquery/dist/jquery.js'
  }]);

.excludes(deps)

Configures the bundler to recognise the given array of dependencies 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')
  .excludes(['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')
  .excludes([{
    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 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 dependencies are configured during bundling (see.includes and .excludes).