You can create a package file by hand, or use the handy npm init command-line tool, which will prompt you for a series of values and automatically generate a package.json file. Let's run through some of these values:

You might also want to set the private field to true while you are developing your module. This ensures that npm will refuse to publish it, avoiding accidental releases of incomplete or time-sensitive code.

npm is ultimately a build tool, and the scripts field in your package file allows you to set various build directives executed at some point following certain npm commands. For example, you might want to minify JavaScript, or execute some other processes that build dependencies that your module will need whenever npm install is executed. The available directives are:

It should be clear that the commands with prefix pre will run before, and the commands with prefix post will run after their primary command (such as publish) is executed.

It is likely that a given module will itself depend on other modules. These dependencies are declared within a package.json file using four related properties, which are:

Dependencies are normally defined with a npm package name followed by versioning information:

"dependencies" : {
  "express" : "3.3.5"
}

However they can also point to a tarball:

"foo" : "http://foo.com/foo.tar.gz"

You can point to a GitHub repository:

"herder": "git://github.com/sandro-pasquali/herder.git#master"

Or even the shortcut:

"herder": "sandro-pasquali/herder"

Additionally, in cases where only those with proper authentication are able to install a module, the following format can be used to source secure repositories:

"dependencies": {
  "a-private-repo": "git+ssh://[email protected]:user/repo.git#master"
}

By properly organizing your dependencies by type, and intelligently sourcing those dependencies, build requirements should be easy to accommodate using Node's package system.

In order to publish to npm, you will need to create a user. npm adduser will trigger a series of prompts requesting your name, e-mail, and password. You may then use this command on multiple machines to authorize the same user account.

Once you have authenticated with npm you will be able to publish your packages using the command npm publish. The easiest path is to run this command from your package folder. You may also target another folder for publishing (remember that a package.json file must exist in that folder).

You may also publish a gzipped TAR archive containing a properly configured package folder.

Note that if the version field of the current package.json file is lower or equal to that of the existing, published package npm will complain and refuse to publish. You can override this by using the --force argument with publish, but you probably want to update the version and republish.

To remove a package use npm unpublish <name>[@<version>]. Note that once a package is published other developers may depend on it. For this reason you are strongly discouraged from removing packages that others are using. If what you want to do is discourage the use of a version, use npm deprecate <name>[@<version>] <message>.

To further assist collaboration, npm allows multiple owners to be set for a package:

All owners have equal privileges—special access controls are unavailable, such as being able to give write but not delete access.

Some Node modules are useful as command-line programs. Rather than requiring something such as > node module.js to run a program, we might want to simply type > module on the console and have the program execute. In other words, we might want to treat a module as an executable file installed on the system $PATH and therefore accessible from anywhere. There are two ways to achieve this using npm.

The first and simplest way is to install a package using the -g (global) argument:

npm install -g module

If a package is intended as a command-line application that should be installed globally, it is a good idea to set the preferGlobal property of your package.json file to true. The module will still install locally, but users will be warned about its global intentions.

Another way to ensure global access is by setting a package's bin property:

"name": "aModule",
"bin" : {
  "aModule" : "./path/to/program"
}

When this module is installed, aModule will be understood as a global CLI command. Any number of such programs may be mapped to bin. As a shortcut, a single program can be mapped like so:

"name": "aModule",
"bin" : "./path/to/program"

In this case the name of the package itself (aModule) will be understood as the active command.

Node modules are often stored in version control systems, allowing several developers to manage package code. For this reason the repository field of package.json can be used to point developers to such a repository, should collaboration be desired. For example:

"repository" : {
  "type" : "git",
  "url" : "http://github.com/sandro-pasquali/herder.git"
}
"repository" : {
  "type" : "svn",
  "url" : "http://v8.googlecode.com/svn/trunk/"
}

Similarly, you might want to point users to where bug reports should be filed by using the bugs field:

"bugs": {
  "url": "https://github.com/sandro-pasquali/herder/issues"
}