Chapter 8. Extending Node

Modules

The module system in Node makes it easy to create extensions to the platform. It is simple to learn and enables us to easily share reusable library code. The Node module system is based on the commonJS module specification. We’ve already used lots of modules in the previous chapters, but here we’ll study how to create our own modules. Example 8-1 shows one simple implementation.

Example 8-1. A simple module

exports.myMethod = function() { console.log('Method output') };
exports.property = "blue";

As you can see, writing a module is as simple as attaching properties to the exports global variable. Any script that is included with require() will return its exports object. This means that everything returned from require() is in a closure, so you can use private variables in a module that are not exposed to the main scope of the program.

Node developers have created a few conventions around modules. First, it’s typical to create factory methods for a class. Although you might also expose the class itself, factory methods give us a clean way to instantiate objects. For I/O-related classes, one of the arguments is normally a callback for either the I/O being done or one of its most common aspects. For example, http.Server has a factory method called http.createServer() that takes a callback function for the request event, the most commonly used http.Server event.

Package Manager

Being able to make modules is great, but ultimately having a good way to distribute them and share them with the rest of your team or the community is essential. The package manager for Node, npm, provides a way of distributing code, either locally or via a global repository of Node modules. npm helps you manage code dependencies, installation, and other things associated with distributing code. Best of all, npm is all JavaScript and Node. So if you are already using Node, you are ready to use npm, too. npm provides both the installation tools for developers and the distribution tools for package maintainers.

Most developers will start by using npm to install packages using the simple npm install command. You can install packages you have locally, but you’ll probably want to use npm to install remote packages from the npm registry. The registry stores packages that other Node developers make available to you to use. There are many packages in the registry: everything from database drivers to flow control libraries to math libraries. Most things you’ll install with npm are 100% JavaScript, but a few of them require compilation. Luckily, npm will do that for you. You can see what’s in the registry at http://search.npmjs.org.

The search command lists all packages in the global npm registry and filters for a package name:

npm search packagename

If you don’t supply a package name, all of the available packages will be displayed.

If the package list is out of date (because you added or removed a package, or you know the package you want should be available but it isn’t), you can instruct npm to clean the cache using the following command:

npm cache clean

The next time you ask npm for a list of packages, the command will take longer because it will need to rebuild its cache.

Although most of the packages you get using the npm install command are available to anyone who uses Node, writing a package does not require publishing it to the world. Consolidating your own code into module packages makes it easy to reuse your work across multiple projects, share it with other developers, or make it available to staging or production servers running your application.

Packages do not have to be limited to modules or extensions; in many cases, packages contain full applications intended for deployment. Package files make deployment easy by declaring dependencies, eliminating the library-labyrinth guesswork that was traditionally required when moving from development to production environments.

Creating a package doesn’t require much more work than creating a package.json file with some basic definitions about your module—its name and version number being the most critical components. To quickly generate a valid package file, run the command npm init from your module’s directory. You will be prompted to enter descriptive information about your module. Then the command will emit a packages.json file into the directory. If a package file already exists, its attributes will be used as the default values and you will be given a chance to overwrite them with new information.

To use your package, install it using npm install /path/to/yourpackage. The path may be a directory on your filesystem or an external URL (such as GitHub).

If your module is useful to a broader audience and ready for prime time, you can release it to the world using npm’s publish command. To publish the contents of your package:

  1. Create a user with the adduser command:

    npm adduser

    Follow the instructions that appear. You will be prompted for a username, password, and email address.

  2. Publish your package with the publish command:

    npm publish

That’s all there is to the process. At present, no registration or validation is needed.

Warning

This raises an interesting point about npm: because anyone can publish a package without any prefiltering or oversight, the quality of the libraries you install using npm is uncertain. So “buyer beware.”

If you decide later to unpublish your package, you may do so with the npm unpublish command. Note that you will need to clear your package list cache.

Although npm excels at publishing and deploying, it was designed primarily as a tool for managing dependencies during development. The npm link command creates a symbolic link between your project and its dependencies, so any changes in the dependencies are available to you as you work on your project.

There are two major reasons you would want to do this:

Typing npm link with no arguments creates a symbolic link for the current project inside the global packages path, making it available to npm in all other projects on your system. To use this feature, you need to have a packages.json file, described earlier. Using npm init is the fastest way to generate a barebones version of this file.

Typing npm link packagename creates a symbolic link from the project’s working directory to the global modules path for that package. For example, typing npm link express will install the Express framework in the global packages directory and include it in your project. Whenever Express is updated, your project will automatically use the latest version from the global packages directory. If you have linked Express in more than one project, all of those projects will be synchronized to the most recent version, freeing you from having to update every one of them whenever Express is updated.

Add-ons

Whereas modules are the JavaScript extensions for Node, add-ons are the C/C++ extensions. Add-ons frequently wrap existing system libraries and expose their functionality to Node. They can, of course, create new functionality too, although most people choose to do that in JavaScript for obvious reasons. Add-ons are dynamically linked shared objects.

To create an add-on, you’ll need at least two sets of files: the add-on code and the build files. Node uses the waf build system written in Python. Let’s start with a “Hello World” example. Example 8-2 is equivalent to exports.hello = "world"; in JavaScript.

Example 8-2. A simple add-on for Node

#include <v8.h>

using namespace v8;

extern "C" void init (Handle<Object> target) {
  HandleScope scope;
  target->Set(String::New("hello"), String::New("world"));
}

The first thing this code needs to do is include the v8 header file because Node is built on top of V8. This provides a lot of standard objects that we will use. Next, we declare the namespace. Then we create the wrapper, which is required by all add-ons. The wrapper functions like the exports global variable for JavaScript modules. We’ll hang everything we expose from the add-on off a function with the signature extern 'C' void init (Handle<Object> target).