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 directory module except that npm recognizes many more package.json tags than Node.js does. The starting point for npm's package.json are the CommonJS Packages/1.0 specification. The documentation for npm's package.json implementation is accessed using 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 be familiar with.

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 whether a particular name is already being used at http://npmjs.com or with the following command:

$ npm search packageName

The main tag is treated the same as we discussed in the previous section on directory modules. It defines which file module will be returned when invoking require('packageName'). Packages can contain many modules within themselves and they 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.x.x", 
    "bar" : ">=1.0.2 <2.1.2"
 }

The description and keyword fields help people 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 that 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 describes 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 life cycle 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

We've already used the scripts feature when showing how to set up Babel. We'll use these later for automating the build, test, and execution processes.

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

By default, npm modules are retrieved over the Internet from the public package registry maintained on http://npmjs.com. 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.com publishes a searchable index of the modules in that registry.

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

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

$ npm install acoustid

After installing a module you may want to see the documentation, which would be on the module's website. The homepage tag in 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 akashacms
...
{ name: 'akashacms',
  description: 'A content management system to generate static websites using latest HTML5/CSS3/JS goodness.',
  'dist-tags': { latest: '0.4.16' },
  versions: 
   [ '0.0.1',
…
  author: 'David Herron <[email protected]> (http://davidherron.com)',
  repository: { type: 'git', url: 'git://github.com/akashacms/akashacms.git' },
  homepage: 'http://akashacms.com/',
…

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 akashacms homepage
http://akashacms.org/

Other fields in the package.json can be viewed by simply giving the desired tag name.

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

You can view the list of these commands just by typing npm (with no arguments). If you see one you want to learn more about, view the help information:

$ npm help <command>
The help text will be shown on your screen.  
Or, see the website: http://docs.npmjs.com

$ npm install express
/home/david/projects/notes/
– [email protected]
…

$ npm install -g grunt-cli

$ sudo npm install -g grunt-cli

Initializing a new npm package

If you want to create a new package, you can create the package.json file by hand or you can get npm's help. The npm init command leads you through a little dialog to get starting values for the package.json file.

Once you get through the questions, the package.json file is written to disk.

$ npm install akashacms –-save

"dependencies": {
    "akashacms": "^0.4.16"
}

$ npm install –-production

$ npm install [email protected] --save

"dependencies": {
    "express": "http://example.com/my/patched/express.tar.gz"
}

"engines": {
    "node": ">= "5.x"
}

$ npm outdated

$ npm update express
$ npm update

$ npm install http://dev.mydomain.com/path/to/v1.2.3/packageName.tar.gz --save

$ npm install git+ssh://user@hostname:project.git#tag --save

$ npm install strongloop/express --save

We've been showing version numbers all along without explaining how npm uses them.

Node.js doesn't know anything about version numbers. It knows about modules, and it can treat a directory structure as if it were a module. It has a fairly rich system of looking for modules, but it doesn't know version numbers.

The npm package, however, knows about version numbers. It uses the Semantic Versioning model (http://semver.org), and as we saw, you can install modules over the Internet, query for out-of-date modules, and update them with npm. All of this is version controlled, so let's take a closer look at the things npm can do with version numbers and version tags.

Earlier, we used npm list to list installed packages, and the listing includes version numbers of installed packages. If instead, you wish to see the version number of a specific module, type the following command:

$ npm view express version
4.13.4

Whenever npm commands take a package name, you can append a version number or version tag to the package name. This way, you can deal with specific package versions if needed. Sometimes, package maintainers introduce bugs that you want to avoid. The dependencies in your application can list a specific version number. You can list specific version numbers, changing the version dependency only when you're satisfied it is safe to do so. The npm install command, and several other npm commands, take version numbers as follows:

$ npm install [email protected]

The npm help package.json documentation has a full discussion of what you can do with version number strings, including these choices:

One feature of the Twelve-Factor methodology is step 2, explicitly declaring your dependencies. We've already touched on this, but it's worth reiterating and to see how npm makes this easy to accomplish.

Step 1 of the Twelve-Factor methodology is ensuring that your application code is checked into a source code repository. You probably already know this, and even have the best of intentions to ensure that everything is checked in. With Node.js, each module should have its own repository rather than putting every single last piece of code in one repository.

Doing so ensures that each module progresses on its own timeline. For example, a breakage in one module is easy to back out by changing the version dependency in package.json.

This gets us to step 2. There are two aspects of this step, one of which is the package versioning we discussed previously. With npm, we can explicitly declare module version numbers in dependencies and devDependencies. It's extremely easy, then, to ensure that everyone on the team is on the same page, developing against the same versions of the same modules. When it's time to deploy to testing, staging, or production servers, and the deployment script runs npm install or npm update, the code will use a known version of the module.

The lazy way to declare dependencies is putting * in the version field. Doing so uses whatever is the latest version in the npm repository. Maybe this will work for you, until one day the maintainers of that package introduce a bug. You'll head over to the Github site for the package, look in the issue queue, and see that others have already reported the problem you're seeing. Some of them will say that they've pinned on the previous release until this bug is fixed. What that means is their package.json file does not depend on * for the latest version but on a specific version number before the bug was created.

Don't do the lazy thing, do the smart thing.

The other aspect of explicitly declaring dependencies is to not implicitly depend on global packages. Earlier, we said that some in the Node.js community caution against installing modules in the global directories. This might seem like an easy shortcut to sharing code between applications. Just install it globally, and you don't have to install the code in each application.

But, doesn't that make deployment harder? Will the new team member be instructed on all the special files to install here and there to make the application run? Will you remember to install that global module on all destination machines?

You don't want installation instructions to be the length of a small book full of arcane steps to ensure correct setup. That's error prone and hard to automate for modern cloud-based computing systems. Instead, you would want to automate as much of the installation and setup as possible.

For Node.js, that means listing all the module dependencies in package.json, and then the installation instructions are simply npm install, followed perhaps by editing a configuration file.