An Overview of the Node Package Manager

npm package format

An npm package is a directory structure with a package.json file describing the package. This is exactly what we just referred to as a Complex Module, except npm recognizes many more package.json tags than does Node. The starting point for npm's package.json is the CommonJS Packages/1.0 specification. The documentation for npm's package.json implementation is accessed with the following command:

$ npm help json

A basic package.json file is as follows:

{ name: "packageName",
version: "1.0",
main: "mainModuleName",
modules: {
"mod1": "lib/mod1",
"mod2": "lib/mod2"
}
}

The file is in JSON format which, as a JavaScript programmer, you should already have seen a few hundred times.

The most important tags are name and version. The name will appear in URLs and command names, so choose one that's safe for both. If you desire to publish a package in the public npm repository it's helpful to check and see if a particular name is already being used, at http://search.npmjs.org or with the following command:

$ npm search packageName

The main tag is treated the same as complex modules. It references the module that will be returned when invoking require('packageName'). Packages can contain many modules within themselves, and those can be listed in the modules list.

Packages can be bundled as tar-gzip tarballs, especially to send them over the Internet.

A package can declare dependencies on other packages. That way npm can automatically install other modules required by the module being installed. Dependencies are declared as follows:

"dependencies":
{ "foo" : "1.0.0 - 2.9999.9999"
, "bar" : ">=1.0.2 <2.1.2"
}

The description and keywords fields help people to find the package when searching in an npm repository (http://search.npmjs.org). Ownership of a package can be documented in the homepage, author, or contributors fields:

"description": "My wonderful packages walks dogs",
"homepage": "http://npm.dogs.org/dogwalker/",
"author": [email protected]

Some npm packages provide executable programs meant to be in the user's PATH. These are declared using the bin tag. It's a map of command names to the script which implements that command. The command scripts are installed into the directory containing the node executable using the name given.

bin: {
'nodeload.js': './nodeload.js',
'nl.js': './nl.js'
},

The directories tag documents the package directory structure. The lib directory is automatically scanned for modules to load. There are other directory tags for binaries, manuals, and documentation.

directories: { lib: './lib', bin: './bin' },

The script tags are script commands run at various events in the lifecycle of the package. These events include install, activate, uninstall, update, and more. For more information about script commands, use the following command:

$ npm help scripts

This was only a taste of the npm package format; see the documentation (npm help json) for more.

Finding npm packages

By default npm modules are retrieved over the Internet from the public package registry maintained on http://npmjs.org. If you know the module name it can be installed simply by typing the following:

$ npm install moduleName

But what if you don't know the module name? How do you discover the interesting modules?

The website http://npmjs.org publishes an index of the modules in that registry, and the http://search.npmjs.org site lets you search that index.

npm also has a command-line search function to consult the same index:

$ npm search mp3
mediatags Tools extracting for media meta-data tags =coolaj86 util
m4a aac mp3 id3 jpeg exiv xmp
node3p An Amazon MP3 downloader for NodeJS. =ncb000gt

Of course upon finding a module it's installed as follows:

$ npm install mediatags

After installing a module one may want to see the documentation, which would be on the module's website. The homepage tag in the package.json lists that URL. The easiest way to look at the package.json file is with the npm view command, as follows:

$ npm view zombie
...
{ name: 'zombie',
description: 'Insanely fast, full-stack, headless browser testing
using Node.js',
...
version: '0.9.4',
homepage: 'http://zombie.labnotes.org/',
...
npm ok

You can use npm view to extract any tag from package.json, like the following which lets you view just the homepage tag:

$ npm view zombie homepage
http://zombie.labnotes.org/

Using the npm commands

The main npm command has a long list of sub-commands for specific package management operations. These cover every aspect of the lifecycle of publishing packages (as a package author), and downloading, using, or removing packages (as an npm consumer).

Getting help with npm

Perhaps the most important thing is to learn where to turn to get help. The main help is delivered along with the npm command accessed as follows:

For most of the commands you can access the help text for that command by typing the following:

$ npm help <command>

The npm website (http://npmjs.org/) has a FAQ that is also delivered with the npm software. Perhaps the most important question (and answer) is: Why does npm hate me? npm is not capable of hatred. It loves everyone, even you.