# modules [](http://travis-ci.org/thetalecrafter/modules)
> Use CommonJS modules client-side in web applications
## Getting started
Install via npm
npm install modules --save-dev
Add the middleware to your express or connect app
app.get('/module', require('modules').middleware({
root: './component', // where modules live in the filesystem
// ... other options
});
Add the client script to your html
### Mapping and Bundling
You can create bundles (files containing multiple modules), and/or map modules to
urls outside of the conventional location.
Client-side, this mapping is handled with the `data-urls` attribute on the script
tag, or with a call to `define.url()`. `define.url(url, ids)` maps a single url
to all the modules at that url, and the `data-urls` attribute expects a JSON
object with urls as keys, and arrays of module ids as the values.
define.url("url/of/bundle.js", [ "moduleid" ])
Server-side and at build time you can generate bundles with the following snippets:
// Generate a bundle with a specific set of modules included
require('modules').modules(
[ 'module1', 'module2' ],
{ /* options */ }, // specify optional compression, etc.
function(err, js, modified) {
// js is a string containing the AMD-wrapped javascript for the modules
// modified is the most recent modified date among the included modules
}
);
// Generate a bundle with all of the deep dependencies of the modules, excluding
// the deep dependencies of another list of modules
require('modules/lib/bundles').bundle(
[ 'module1', 'module2' ], // include these and their deep dependencies
[ 'module3', 'module4' ], // except any of these or their deep dependencies
{ /* options */ },
function(err, js, modified) {
}
);
## API
### In Browser
#### define.js or define.min.js
These scripts create the `define` function used to create a module environment
in the browser. You can reference the file how ever you'd like; they are in the
`lib` folder in the source code. However, the preferred way is to include a
script tag pointing to the path the middleware is listening to, or to a bundle
including define:
* `define(id, dependencies?, factory)` -- Define module `id`. `id` is required
in this implementation. If the `dependencies` parameter is omitted, the factory
will not be scanned for `require()` calls, `[ 'require', 'exports', 'module' ]`
will be used instead.
See the [AMD wiki](https://github.com/amdjs/amdjs-api/wiki/AMD) for details.
* `define.amd` -- Object denoting AMD compatibility.
#### define.shim.js
This is only useful to include first in a bundle that may be loaded before the
`define` or `define.min` script has run. Usually the main bundle includes
`define.min` and the shim is not needed.
* `define(id, dependencies?, factory)` -- Saves the arguments for when `define`
or `define.min` is loaded.
* `define.amd` -- Object denoting AMD compatibility.
#### module scope
(inside the factory function)
See the [CommonJS Module spec](http://wiki.commonjs.org/wiki/Modules/1.1.1),
the [AMD spec](https://github.com/amdjs/amdjs-api/wiki/AMD), and
[Node.js modules](http://nodejs.org/api/modules.html)
* `exports` -- Alias for `module.exports`. An object to assign properties to
in order to export values.
* `module` -- An object representing this module.
* `module.children` -- An array of `module` objects for the modules this one
requires synchronously.
* `module.exports` -- This object will be returned from `require()` calls for
this module. Assign to this to export the value. Note if you assign to this
property, the `exports` variable is not automatically updated.
* `module.filename` -- Alias of `uri`. The url of the script containing this
module.
* `module.loaded` -- True if the module has already been defined.
* `module.parent` -- The `module` object for the module that first required
this module.
* `module.id` -- A string of slash separated terms identifying the module.
* `module.require()` -- A `require()` function that always resolves relative
ids against this module's id.
* `module.uri` -- Alias of `filename`. The url of the script containing this
module.
* `require(id)` -- Returns the `exports` for the module identified. Throws an
error if the module has not been loaded. `id` is a module id string.
* `require(ids, next)` -- Asynchronously load the modules, require them, and
pass them as arguments to the callback function `next`. `ids` may be a
single id string, or an array of module id strings.
* `require.cache` -- A store of all modules the system knows about. You may
undefine a module by `delete require.cache[module.id]`. Assigning to
this property will have no effect.
* `require.main` -- The `module` object of the module loaded by the `data-main`
attribute of the define script.
* `require.resolve(id)` -- Resolves a relative module id against this module's
id, and returns the `uri` for that module.
* `require.toUrl(id)` -- Similar to `require.resolve()`. See the AMD spec.
* `require.map(url, ids)` -- Tell require where to load specific modules.
`url` is the url to request, and `ids` is an array of module ids that are
defined by the file at the url.
### In Node.js
#### modules
modules = require('modules')
Provides middleware and functions to wrap and bundle your modules for use in the
browser.
* `modules.dependencies(id, js, options?)` -- Finds all literal synchronous
`require()` calls in a module identified by `id`. `js` is the code for the
module as a string. If `options.absolute` is true, the returned dependency ids
are made absolute, otherwise they are returned as written in the code. Returns
an array of module id strings. *Note: this uses regular expressions instead
of a parser. Comments are excluded. The function will miss any calls with a
renamed require, or a variable instead of a string literal id.*
* `modules.middleware(options?)` -- Returns an express / connect middleware using
the `options` passed in.
* `compress` -- Defaults to `false`. If a function is specified, it will be
passed a module object with `id`, `filename`, `code`, and `modified`
properties as the first parameter, and a function as the second. It expects
the function to be called with either an error or null in the first argument,
and the compressed code as a string in the second. Example:
compress:function(js, next) {
var UglifyJS = require('uglify-js');
js = UglifyJS.minify(js.code, { fromString:true });
next(null, js);
}
* `forbid` Defaults to `[]`. If the file path to a module matches an entry
in this list, a `'Forbidden'` error will be passed to the next error
middleware. Entries can be a string module id (filename starts with
entry), a regular expression (`exp.test(filename)`) or any object with
a `test` function property (`obj.test(filename)`). Files outside of the
`root` directory are always forbidden, unless they have been mapped.
Mapped files are always allowed. Example:
forbid: [
'server', /\.middleware\.js$/,
{ test:function(filename) {
return filename.slice(-3) === 'foo';
} }
]
* `encoding` Defaults to `'utf8'`. Encoding to read module files in.
* `map` Defaults to `{}`. Map module ids to files in the filesystem.
`define`, `define.min`, and `define.shim` will be mapped to their
locations in `lib` unless explicitly mapped elsewhere. Relative paths
are resolved against `root`. Values can also be functions Example:
map: {
jquery: './vendor/jquery.min.js',
session: function(id, options) {
// figure out or generate the file for this user
return sessionFilename;
}
}
* `maxAge` -- Defaults to `undefined`. Seconds the browser should cache the
module code. If set, will be put in a `Cache-Control: public, max-age=`
HTTP header.
* `nowrap` Defaults to `[ 'uris.json', /\.amd\.js$/i ]`. If a module id
matches an entry in this list, it is not wrapped with a `define()`
call. Entries can be a string module id (`entry === id`), a regular
expression (`exp.test(id)`) or any object with a `test` function
property (`obj.test(id)`).
* `root` -- Defaults to `process.cwd()`. Base path for modules in the filesystem.
* `translate` Defaults to `{}`. Translate specific files into CommonJS
modules. Object keys may be filenames, module ids, or file extensions.
The functions are passed a module object, with `id`, `filename`, and
`buffer` properties. Example:
translate: {
html: function(module, options, next) {
var id = module.id, // String
filename = module.filename, // String
content = module.buffer, // Buffer
_ = require('underscore');
content = content.toString('utf8');
next(null, 'exports.template = ' + _.template(content).source);
}
}
If they do not match any keys in this option, modules are converted from
`Buffer` to string with `options.encoding`.
* `modules.module(id, options?, next)` -- Generate the client-side code for
the module. `id` is a module id string. `options` are the same as for
`modules.middleware()`. `next(err, result)` will be called when
done. `err` is any error that may have occured, or `null` otherwise.
`result` is an object with properties `code`, which is the browser javascript
as a string, and `modified`, which is a `Date` of the last modified time on
the source file.
* `modules.modules(ids, options?, next)` -- Exactly like `modules.module` only
`ids` is an array of module id strings, all of which are included in the
resulting `result.code`. The `result.modified` is the most recent modified
time among all of the source files loaded.
#### bundles
bundles = require('modules/lib/bundles')
Provides functions for bundling modules with their deep dependencies.
* `bundles.bundle(ids, exclude, options?, next)` -- Generate a bundle including
the browser code for all of the modules in the `ids` array and their deep
dependencies, except `exclude` and all of their deep dependencies.
`ids` and `exclude` are arrays of module id strings. `options` are the
same as `modules.middleware()`. `next` is called when complete, with the
same arguments as `next` in `modules.module()`.
* `bundles.dependencies(ids, options?, next)` -- Gets a list of `ids` and all
of their deep dependencies. Modules need to be loaded in order to determine
their dependencies, so `modules.module()` is called inside this method,
with the `options` passed in. `next(err, ids)` is called when complete,
with `ids` as an array of absolute module id strings.
* `bundles.expand(ids, exclude, options?, next)` -- Gets a list just like
`bundles.dependencies()`, only the ids in `exclude` and their deep
dependencies are omitted from the list.
## Client-Side Features
* CommonJS Modules 1.1.1 implementation for in-browser use
* `module.require` function similar to Node.js implementation
* `require(id, callback)` for async a la require.js
* Map module ids to arbirary uris
## Server-Side Features
* Middleware for express / connect
* Create bundles of all the deep dependencies of a list of modules
* Configure minification using your favorite compressor
## Browser Support
* IE 8+, Chrome, Firefox, Safari, Opera
* IE Mobile, Chrome Mobile, Firefox Mobile, Safari Mobile, Opera Mobile
Basically, bugs reported in any common browser will get fixed.
If you need to support IE6 or IE7, please use the last version to support them:
[v0.3.3](https://github.com/thetalecrafter/modules/tree/v0.3.3).
## Who and Why
**modules** was written by Andy VanWagoner
([thetalecrafter](http://github.com/thetalecrafter)).
Some of the motivation for this project can be found in
[this article](http://thetalecrafter.com/2011/09/22/commonjs-in-the-browser/).
* If you like writing your modules in AMD, use
[require.js](http://requirejs.org).
* If you want the browser environment to be just like Node.js, use
[browserify](http://browserify.org/).
* If you want simple CommonJS in the browser, then **modules** is for you.