The npm registry contains packages, many of which are also Node modules, or contain Node modules. Read on to understand how they differ and how they interact.

About packages

A package is a file or directory that is described by a package.json file. A package must contain a package.json file in order to be published to the npm registry. For more information on creating a package.json file, see "Creating a package.json file".

Packages can be unscoped or scoped to a user or organization, and scoped packages can be private or public. For more information, see

• "About scopes"
• "About private packages"
• "Package scope, access level, and visibility"

About package formats

A package is any of the following:

• a) A folder containing a program described by a package.json file.
• b) A gzipped tarball containing (a).
• c) A URL that resolves to (b).
• d) A <name>@<version> that is published on the registry with (c).
• e) A <name>@<tag> that points to (d).
• f) A <name> that has a latest tag satisfying (e).
• g) A git url that, when cloned, results in (a).

npm package git URL formats

Git URLs used for npm packages can be formatted in the following ways:

• git://github.com/user/project.git#commit-ish
• git+ssh://[email protected]:project.git#commit-ish
• git+http://[email protected]/project/blah.git#commit-ish
• git+https://[email protected]/project/blah.git#commit-ish

The commit-ish can be any tag, sha, or branch that can be supplied as an argument to git checkout. The default commit-ish is master.

About modules

A module is any file or directory in the node_modules directory that can be loaded by the Node.js require() function.

To be loaded by the Node.js require() function, a module must be one of the following:

• A folder with a package.json file containing a "main" field.
• A JavaScript file.

package.json

package.json

In the context of a Node program, the module is also the thing that was loaded from a file. For example, in the following program:

var req = require('request')

we might say that "The variable req refers to the request module".