81 lines
2.4 KiB
Markdown
81 lines
2.4 KiB
Markdown
# 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
|