<div class="intro">
<p>
This example will guide you through the recommended way to package a YUI module as
an exportable package with `npm` on Node.js.
</p>
</div>
<h2>Why Package?</h2>
<p>
Packaging up your scripts with `npm` makes them usable by others so they can benefit from
all your hard work. There's nothing quite like having others use something you worked hard
to create. So, why not make using your code as easy as possible?
</p>
<h2>How to Create a Usable Package</h2>
<p>
There are 2 primary ways a Node.js user could use your YUI module, below we will discuss both
ways as well as how to package up your code so they can both be available to your end user.
</p>
<h3>Setting up the Package</h3>
<p>First we need to set up the code so we can package it up all nice and neat.</p>
<p>We are going to use this simple version of a module in this example:</p>
```
YUI.add('my-module', function(Y) {
Y.MyModule = function() {
Y.log('Here');
};
});
```
<p>This file will be saved as `module.js` in a directory all by itself.</p>
<p>Next we create a `package.json` file that describes our Node.js package:</p>
```
{
"version": "0.1.0",
"name": "my-yui-module",
"description": "My YUI Module",
"dependencies": {
"yui": "*"
},
"main": "./index.js"
}
```
<p><strong>Note that we are using `index.js` here as our main script and not `module.js`, `index.js` will be created below.</strong></p>
<p>Your `index.js` file is the main file in your `npm` package, it's the file that executed when your module
is `required`. We need to make a special `index.js` file that will load YUI and `use` our module.</p>
<h3>The All in One Package</h3>
<p>
In this example, we will export our module as a working YUI instance. So when the user `requires` our
module they get all of YUI with it too. Here's the `index.js` file used in this case:
</p>
```
var path = require('path');
//setup our custom modules meta-data
var meta = {
'my-module': {
requires: [ 'yql' ],
//Give it a full path on the file system
}
};
module.exports = {
module: function() {
var inst = require('yui').getInstance();
inst.applyConfig({useSync: true, modules: meta });
return inst.use(Object.keys(meta));
}
};
```
<p>
This setup allows the user to do this:
</p>
```
var mod = require('my-yui-module').module();
mod.MyModule();
mod.YQL('select * from ...');
```
<p>
At this point `mod` will be a YUI instance containing `my-module` and all of it's dependencies (`yql`, `jsonp`).
This will allow you to create a module that the end user doesn't even have to that YUI is there. Making it
easy for them to just `require` and run your module.
</p>
<h3>Just Let Me Use It</h3>
<p>
The other type of user you want to deal with is the one that is already writing scripts with YUI
on Node.js and they want to use your module too. In this case you need to make your modules metadata
available so they can add it to their YUI instances. You can do this in your `index.js` to provide
the metadata needed to load your module.
</p>
```
var path = require('path');
//setup our custom modules meta-data
var meta = {
'my-module': {
requires: [ 'yql' ],
//Give it a full path on the file system
}
};
module.exports = {
metadata: function() {
return meta;
}
}
```
<p>
This will export the module metadata needed to allow `Loader` to load your module and
use it as if it was a native module.
</p>
```
var YUI = require('yui').YUI,
var mod = require('my-yui-module');
YUI({
//Populating the modules config option
// with the metadata from the package
modules: mod.metadata()
}).use('my-module', function(Y) {
Y.MyModule();
Y.YQL('select * from ...');
});
```
<h2>Putting Them All Together</h2>
<p>
Now that we have them individually covered, let's put them together so you have one
package that now works for both types of use cases. Here is the complete `index.js`
file.
</p>
```
var path = require('path');
//setup our custom modules meta-data
var meta = {
'my-module': {
requires: [ 'yql' ],
//Give it a full path on the file system
}
};
module.exports = {
/**
* Calling this method will create and return a YUI instance
* with the modules in the meta data attached.
* @method module
* @return YUI
*/
module: function() {
var inst = require('yui').getInstance();
inst.applyConfig({useSync: true, modules: meta });
return inst.use(Object.keys(meta));
},
/**
* Calling this method will return the modules meta data
* so that it can be passed to the YUI constructor.
* @method metadata
* @return Object
*/
metadata: function() {
return meta;
}
}
```
<p>Now that we have our `index.js` file ready to go, we can now include our package and use it both ways.</p>
```
#!/usr/bin/env node
var mod = require('my-yui-module');
mod.MyModule();
mod.YQL('select * from ...');
// OR
var YUI = require('yui').YUI;
YUI({
modules: mod.metadata()
}).use('my-module', function(Y) {
Y.MyModule();
Y.YQL('select * from ...');
});
```
<p>
Using this method to setup your YUI module, you can now publish your module to `npm` and
share it with others.
</p>