Node: Up and Running

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.

Searching Packages

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.

Creating Packages

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).

Publishing Packages

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.

Linking

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:

• You want to use requires() to access one of your projects from another one of your projects.

• You want to use the same package in multiple projects, without needing to maintain its version in each of your projects.

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.