About packages and modules

Table of contents

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() or import syntax.

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.

To use the import syntax, a module should also include "type": "module" in its package.json file:

{
  "name": "my-package",
  "type": "module"
}

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:

const req = require('request')

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