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 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://user@hostname:project.git#commit-ish
  • git+http://user@hostname/project/blah.git#commit-ish
  • git+https://user@hostname/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 HEAD.

Installing any package directly from git will not install git submodules or workspaces.

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.

Note: Since modules are not required to have a package.json file, not all modules are packages. Only modules that have a package.json file are also packages.

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

The req variable refers to the request module returned by the require() function.

Edit this page on GitHub
6 contributorsKCarlileKCarlilelukekarryslukekarrysseantcoyoteseantcoyote0liver0liverjoey-majoey-maethomsonethomson
Last edited by KCarlile on August 12, 2024