API

Want more details about certain sections? There's a more extensive API doc available.

modul8() and .compile()

Statically analyze entryFile and its requirements recursively, and bundle up all dependencies in a browser compatible targetFile.

var modul8 = require('modul8');
modul8(entryFile)
  //chain on options here
  .compile(targetFile);

Options

The following can be inserted verbatim as chained options on the modul8 constructor, and a working .compile() call will end any further chaining.

domains()

Allow requiring code from namespaced domains,

.domains()
  .add('shared', './shared')
  .add('internal', './internal')

Or equivalently:

.domains({
  'shared'   : './shared'
, 'internal' : './internal'
})

Both would allow require('shared::file') to resolve on the client when file.js exists on ./shared.

Reserved domain names:

data()

Injects raw data in the data domain from the server.

.data()
  .add('models', {user: {name: 'clux', type: 'String'})
  .add('versions', "{'templates' : 123}")

Or equivalently

.data({
  models  : {user: {name: 'clux', type: 'String'}}
, version : "{'templates' : 123}"
})

Values will be serialized using JSON.stringify if they are not strings, otherwise, they are assumed to be serialized.

use()

Call with Plugin instance(s).

.use(new Plugin())

analysis()

View the analyzers prettified output somehow.

.analysis()
  .output(console.log)
  .prefix(false)
  .suffix(true)
  .hide('external')

Or equivalently:

.analysis(console.log, false, true, 'external')

output()

Function or file to pipe to.

prefix()

Show the domain of each file in the dependency tree. Default true.

suffix()

Show the extension of each file in the dependency tree. Default false.

hide()

Call with domain(s) to hide from the tree. Default [].

libraries()

Pre-concatenate in an ordered list of libraries to the target output, or save this concatenation to a separate libs file.

.libraries()
  .list(['jQuery.js', 'history.js'])
  .path('./app/client/libs/')
  .target('./libs.js')

Or equivalently:

.libraries(['jQuery.js', 'history.js'], './app/client/libs/', './libs.js')

AltJS libraries are compiled with a safety wrapper, whenever the the registered language supports this.

npm()

Set the node_modules directory to allow requiring npm installed modules.

.npm('./node_modules')

before()

Pre-process all code before it gets sent to analysis with input function(s).

.before(function (code) { return code;})

modul8.testcutter is an example of such a function.

after()

Post-process all code after it has been bundled.

.before(function (code) { return code; })

modul8.minifier is an example of such a function.

set()

Set a few extra options. Available options to set are:

set('domloader', value)

domloader is the name of a global or arbitered function, or a direct substitution function, which wraps the application domain code and (usually) waits for the DOM.

Examples values:

The last example simply wraps the app domain code in an anonymous, self-executing funciton.

set('namespace', value)

The name of the global variable used in the browser to export console helpers to. The default value for this is M8.

set('logging', value)

This will set the amount of messages sent on the client. Allowed values:

logger()

Pass down a logule sub to fully control server side log output. A passed down instance will attempt to call .info(), .debug() and .error().

Error messages are used to aid on throws, recommended kept unsuppressed. If not used, only debug messages are suppressed.

in()

Only do chainOfStuff() when NODE_ENV matches environment.

in(environment).chainOfStuff()

To break out of the environment chain, use: in('all') or in(otherEnv).

register()

Register an AltJS language with a compilation function. CoffeeScript can be supported using:

.register('.coffee', function (code, bare){
  coffee.compile(code, {bare: bare})
})

arbiters()

Move browser globals to the require system safely.

.arbiters()
  .add('jQuery', ['$', 'jQuery'])
  .add('Spine')

Or with object style:

.arbiters({
  jQuery : ['$', 'jQuery']
  Spine  : 'Spine'
})

Values are either a list of global names to alias under the key's name, or a single name to alias, or - when using the chaining add style - undefined to indicate same as key.

Client API

modul8 exports debug functions and extension functions on the single global variable configurable via set('namespace').

The following functions exists on this global in the browser only, illustrated with ns as the global.

require()

A console specific version of require can require relatively from the main app domain.

ns.require('./fileOnAppRoot'); // exportObj of file

data()

Extend the data domain with a new key:

ns.data('libX', libXobj);
require('data::libX'); // -> libXobj

Modify a key on the data domain:

ns.data('libX', {});
require('data::libX'); // -> {}

Delete a key on the data domain:

ns.data('libX'); //unsets
require('data::libX'); // -> undefined

external()

Has identical behaviour to ns.data(), but modifies the external domain, which is only modified on the server, wheras the data domain is initialized on the server.

domains()

List the domains initialized by modul8

ns.domains(); // ['data', 'external', 'npm', 'app'] or similar

inspect()

Logs the contents of a specific domain by name

ns.inspect('app'); // logs object of keys -> raw export object

Can not be used to actually require things in the console.