Writing and Publishing node.js Modules

Writing and publishing node.js modules

The purpose of this is to introduce the idea of creating and publishing your own node modules to expand ease of use with node.js. If you’ve messed around with node at all, you’re probably aware that to include one of the pre-installed modules is simple with the “require” construct. Installing modules is also quite easy with npm, using only a single command: “npm install <app_name>”; which can then be used in future node apps. But how does someone get their module up so that others can install and use them? It’s quite simple.

Supposing you want to make something SUPER useful, like a module that does factorials! You’d want to start simply with a function that can do exactly that…

function factorial(n){

return n <= 1 ? 1 : factorial(n-1) * n;

};

Great. Now to make this available for your node app to test.

exports.factorial = factorial;

This little magic line is what makes it able to be require’d by a node app. We can test this by making a new node app, and pasting this:

var jmath = require("./mathModule");

console.log("factorial(5): " + jmath.factorial(5));

Now you have a module. Let’s expand on this a little bit to see what else we can do:

CMath = function(){

this.PI = 3.14159;

}

CMath.prototype.factorial = function(n){

return n <= 1 ? 1 : factorial(n-1) * n;

};

module.exports = CMath;

What’s changed here is that now we’re exporting an object that can be dished out on the fly in our node app. Although it isn’t really necessary for a math module, it could be used for other applications. The point to take away here is that it is possible. Here’s how we’d use this.

var jmath = require("./mathModule");

var myMath = new jmath();

console.log("factorial(5): " + myMath.factorial(5));

console.log("\npi: " + myMath.PI);

If for your uses, you didn’t want to expose a variable, like I have with PI, you could declare it outside the class simply as a var, and then give an accessor through the object, or just keep it locked away in hiding.

These examples are all fine and dandy if you want to keep this amazing module to yourself, but I know how you think, you want to share it with everyone. I got your back. What you want to do is get yourself a git-repo, unless you’re savvy enough to have one set up and ready, and push this as a project to it.

You’ll want to set up the project in a self-explanatory file-structure. What I mean by this is to put the mathModule.js file in: ./lib/; and keep the example for use in a: ./test/; folder. You may also want a /doc folder to keep any documents to describe using your module/api and a README in the main dir to keep track of any changes, or simple documentation to get a user going. The only other thing you need in there is the package.json file. This is a JSON object that has a few different properties that should be set, and a few others that can be set for different reasons. Here is a very simple version of this type of file that I’ve done for test publishing on a module:

{

"author": "daniel montgomery",

"name": "mathModule",

"description": "testing node module creation and publishing",

"version": "0.1.0",

"repository": {

"type": "git",

"url": "git://github.com/dmonty/dmonty_mm.git"

},

"engines": {

"node": "0.6.6"

},

"directories": {

"doc": "./doc",

"lib": "./lib"

},

"main": "./lib/mathModule.js"

}

I’ll point out what a few of these are doing for you now. 'author’ is you, you did some work, take credit for it. ‘name’ is the name of your module. ‘description’ is just a brief description of what your module is used for, keep the detailed description for your documentation/README/git pages. ‘version’ is the version this module is at. ‘repository’ is the repo that you set up for this project. Make sure to put the proper version you used for node in the ‘node’ section. ‘directories’ is to define what directories you’ve set up for the project. And most importantly, ‘main’, which says where the entry point to your module is. The reason this is important is because you can link many modules/files together, and will only have to have the entry and the actual published title. For a lot better explanation of what is available in package.json files, check out this cheatsheet: http://package.json.nodejitsu.com/

Now all that’s left to do is to register at the npm registry (npm adduser), then just run a few commands:

npm install

npm publish