# node-ensure
A simple library that shims asynchronous module loading into Node.js to help
with building module bundlers and client-side loaders for isomorphic apps.
This library is super slim (read the source) and mainly represents an agreement
between developers and users of a particular bundler/loader.
NOTE: This module is *not* compatible with Browserify. It is for developers that
want to split their bundles for the client. For example, see
[dynapack](https://github.com/bauerca/dynapack).
*Syntax is inspired by the CommonJS
[Modules/Async/A](http://wiki.commonjs.org/wiki/Modules/Async/A) proposal.*
## Installation
```
npm install node-ensure
```
## Example
```js
var ensure = require('node-ensure');
ensure(['superagent', 'react'], function(err) {
var request = require('superagent');
var React = require('react');
// Do the coolest of things.
});
```
If your bundler needs `require.ensure`, do this instead:
```js
require.ensure = require('node-ensure');
require.ensure(['superagent', 'react'], function(err) {
var request = require('superagent');
var React = require('react');
// Do the coolest of things.
});
```
## Usage
The returned function takes an array of strings and a callback, in that
order (see the example above). The callback takes a single error argument, which
usually indicates a network problem or other client-side loader-specific runtime
error (it should never receive an error when used in Node.js).
Within the ensure callback, load modules with standard require calls.
## Bundlers/Loaders
This library primarily constitutes an agreement between users and developers of
module bundlers and (client-side) loaders. The users agree to the usage instructions
supplied above.
Bundlers and/or loaders must adhere to the following:
- The bundler/loader uses the package.json `"browser"` property for replacing
server-only modules with browser-ready counterparts (a la Browserify).
- The `require` function passed to a module must have a `require.ensure`
function.
- Each `require.ensure` must accept the same arguments as described in [Usage](#usage).
- Each `require.ensure` must not access variables via closure unless those variables
are shared by **all** `require.ensure` functions.
- Each `require.ensure` may access properties
on `this`. However, this assumes users have attached node-ensure to `require` via
`require.ensure = require('node-ensure')`.
Happy loading!
# License
MIT
|