An introduction to the npm package manager

npm is the package manager that comes with Node.js. You use it to install packages, record project dependencies, update them, and run project scripts.

Most npm projects have a package.json file and a package-lock.json file. Installed packages usually live in the node_modules folder.

Install npm

The simplest way to get npm is to install Node.js. npm is included with the official Node.js installers.

You can check the installed versions with:

node --version
npm --version

Install all project dependencies

If a project has a package.json file, run:

npm install

npm reads the dependency lists, installs the packages, and updates package-lock.json when needed. The lockfile records the exact dependency tree so repeated installs are more predictable.

In automated environments, use npm ci when the project has a lockfile. It performs a clean install and fails if package.json and package-lock.json disagree.

The npm install documentation explains the available install modes.

Install a package

Install a package your application needs with:

npm install fastify

npm adds it to dependencies by default.

Development tools belong in devDependencies:

npm install --save-dev eslint

You can also use the shorter -D flag:

npm install -D eslint

Use --save-exact if you want npm to record one exact version instead of a version range.

Update packages

Run this to update installed packages within the version ranges allowed by package.json:

npm update

You can update one package:

npm update fastify

npm update does not normally widen the ranges in package.json. The official npm update guide documents how the command treats package and dependency constraints.

Use this command to see which direct dependencies have newer versions available:

npm outdated

Package versions

npm packages normally follow semantic versioning:

major.minor.patch

For version 4.2.1:

• 4 is the major version
• 2 is the minor version
• 1 is the patch version

A caret range such as ^4.2.1 accepts compatible updates without moving to version 5. A tilde range such as ~4.2.1 stays within version 4.2.

Version zero has stricter caret behavior. For example, ^0.13.0 accepts versions below 0.14.0, not every 0.x minor release.

See the npm semantic versioning guide for the complete range rules.

Run project scripts

The scripts field in package.json gives a project short, repeatable commands:

{
  "scripts": {
    "dev": "node --watch server.js",
    "start": "node server.js",
    "test": "node --test"
  }
}

Run a script with:

npm run dev

start and test also have shortcuts:

npm start
npm test

npm adds executables from local dependencies to the script’s PATH. This means a script can call locally installed tools without a global installation.

The npm scripts documentation describes lifecycle scripts and the environment available to commands.

Related posts about node: