Building Your First Node.js Library
I’ve been playing with Node.js since its early days. One of my favourite hacking experiences was the first Node Knockout Competition (what a fun language!)
What has really impressed me, is how quickly the community has matured. Taking into account the conventions that have grown up around Node.js development, I thought I’d write a post targeted at helping people get their first library out the door.
Structuring your Library
The root directory of your library should have a structure resembling this:
I’ll go over each of the important parts:
The lib/ directory
I like my code to be very explicit, for this reason I tend to have most of my code in logically named files under lib, e.g., my Person library might consist of a head.js file, a torso.js file, and an arm.js file.
index.js represents the main entry point of the library, and has responsibilities similar to __init__.py in Python. It pulls the namespace together. An example helps I think:
The exports object
Speaking of namespaces, there’s an exports object available in each of your library files. Anything placed on the exports array is exposed to the outside world. When you require(‘class.js’) you gain access to class.js’ exports object.
When we require() the above file, we can see that the Foo and Bar classes are exposed:
I try to keep what I punch onto the exports object to a minimum. Generally one class per library file.
Testing
Do a bit of a literature review, and find out which testing framework you’d like to use.
Recently I’ve been using a really light-weight approach:
- I use Node.js’ built in assert module for performing assertions: http://nodejs.org/docs/v0.3.1/api/assert.html
- I expose all the tests in an object with semantically named keys:
- I expose a finished() callback which is used to move the tests forward, and can be called from deep within an asynchrounous stack of logic.
- Finally, you simply run my tests by typing: node test/index.js
TDD is Your Friend
People complain about JavaScript being a pain in the ass to test, in principal I’ll agree.
It’s really annoying to take an existing JavaScript library and get it under test. It’s so easy, a few closures deep, to introduce hard to test dependencies and sideeffects.
Having said this, I find that if you use a TDD approach to building your libraries, from the ground up, you tease apart these problems from the start.
Creating Your API
A library isn’t a good library, without a clean API. There are a few conventions used in the Node.js that are worth sticking to:
- asynchrounous calls tend to accept a callback of the form function(err, result). This allows errors occurring deep in an asynchronous set of operations, to bubble up to the application implementing your library.
- optional function arguments make for a much cleaner API. You very often see this form: function(doc, options [optional], callback [optional)]. Where the callback might occur in place of any of the arguments. This is nice for someone using your library, but can be a pain to implement over and over again. I’ve built a library for dealing with this:
Contribute to Sexy-Args Here: https://github.com/bcoe/node-sexy-args
- Finally, write a clean descriptive interface, as you would in any language. Naming is everything! name methods well, name classes well, name your library well.
Publishing Your Library
You’ve made a killer Node.js library, and you’re ready to share it with the outside world. Here’s what you’re going to want to do:
- Create clean descriptive documentation, and examples as needed.
- Throw everything up on Github. This is going to be your best bet for getting other people to contribute.
- Update your package.json. This describes your library to a package manager. Most of the keys are pretty self explanatory. Most importantly make sure that lib points to your lib folder, and that main points to your lib/index file.
Now install NPM and publish your package:
- Follow the instructions here, to install NPM: https://github.com/isaacs/npm
- Now, from your packages root directory, do something resembling this:
- Finally, hop on a computer that has NPM installed. install your newly published library npm install library. Hop in a node terminal, and make sure everything works as advertised (push point releases until this is the case).
Promote Your Library
Now that you’ve built something awesome for the Node.js community, don’t be shy to promote the hell out of it. People can’t benefit from what they don’t know about.
To help in this process, I built this recently:
NPM-Tweets: https://github.com/bcoe/npm-tweets (@nodenpm)
I hope some people found this useful,
— Benjamin Coe (@benjamincoe)
