Getting started

Introduction

npm is the package manager for Node.js. This reference covers everyday commands, package specifiers, and npm 12 defaults.

Install

CommandDescription
npm installInstall dependencies from package.json
npm install --omit=devSkip devDependencies
npm install --min-release-age=7Only install releases older than 7 days
npm install -g pkgInstall a package globally
npm ciClean install from package-lock.json

--production is deprecated; use --omit=dev.

See: npm install

Add packages

CommandDescription
npm i lodashAdd to dependencies
npm i -D vitestAdd to devDependencies
npm i -E lodashSave an exact version
npm i -O fseventsAdd to optionalDependencies
npm i --no-save lodashInstall without saving

See: npm install

Clean install

npm ci
npm ci --omit=dev

npm ci requires a lockfile, removes node_modules, and never writes the lockfile.

See: npm ci

Remove

CommandDescription
npm rm lodashRemove from dependencies
npm rm -D vitestRemove from devDependencies
npm rm -g pkgRemove a global package

See: npm uninstall

Inspecting

Listing

CommandDescription
npm lsDependency tree
npm ls -g --depth=0Top-level global packages
npm view lodashRegistry metadata
npm view lodash versionsPublished versions
npm query '.prod'Query production dependencies

See: npm ls, npm query

Outdated and audit

CommandDescription
npm outdatedList outdated packages
npm auditReport known vulnerabilities
npm audit fixApply compatible fixes
npm audit fix --forceApply breaking fixes
npm audit signaturesVerify registry signatures

See: npm audit

Explain a dependency

npm explain lodash
npm why lodash

npm why is an alias for npm explain.

See: npm explain

Doctor

npm doctor
npm cache verify
npm cache clean --force

npm doctor checks the registry, cache, permissions, and environment.

See: npm doctor

Edit package.json

npm pkg get version
npm pkg set version=1.2.3
npm pkg set scripts.lint="oxlint"
npm pkg set keywords[0]="cli"
npm pkg delete scripts.lint
npm pkg fix

npm pkg edits JSON without reformatting it; fix applies the corrections npm publish would otherwise make.

See: npm pkg

Updating

Update

CommandDescription
npm updateUpdate within semver ranges
npm update --saveAlso update package.json
npm update -gUpdate global packages
npm update lodashUpdate one package

npm update updates production and dev packages; it leaves package.json alone unless --save is given.

See: npm update

Version

CommandDescription
npm version 1.2.3Set an exact version
npm version majorBump to 2.0.0
npm version minorBump to 1.3.0
npm version patchBump to 1.2.4
npm version prerelease --preid rcBump to 1.2.4-rc.0

In a git repo, npm version also commits and tags; add --no-git-tag-version to skip.

See: npm version

Workspaces

Define workspaces

{
  "name": "app",
  "workspaces": ["packages/a", "packages/b"]
}
npm init -w ./packages/c
npm install

npm install symlinks every workspace into the root node_modules.

See: Workspaces

Target a workspace

npm i lodash -w a
npm run build --workspace=a
npm run test --workspaces
npm run test --workspaces --if-present
npm publish -w a

-w takes a package name or folder path and can repeat. --workspaces runs across all of them in package.json order.

See: Running commands in workspaces

Scripts

Run scripts

npm run build
npm run build -- --watch
npm test

Arguments after -- pass through to the script.

See: npm run

Execute binaries

npx prettier --write .
npm exec -- prettier --write .

npx is shorthand for npm exec; both use local binaries first.

See: npm exec

Publishing

Publish

npm pack --dry-run
npm publish
npm publish --access public
npm publish --tag beta

See: npm publish

Deprecate and own

npm deprecate pkg@"< 0.2.0" "critical bug fixed in 0.2.0"
npm owner add user pkg
npm owner ls pkg

See: npm deprecate, npm owner

Package sources

Install names

CommandDescription
npm i saxRegistry package
npm i sax@latestLatest tag
npm i sax@3.0.0Exact version
npm i sax@">=1 <2.0"Version range
npm i @org/saxScoped package
npm i /path/to/repoLocal directory
npm i ./archive.tgzLocal tarball

See: Package spec

Version ranges

RangeMatches
1.2.3Exactly 1.2.3
^1.2.3>=1.2.3, <2.0.0
~1.2.3>=1.2.3, <1.3.0
1.x>=1.0.0, <2.0.0
>=1.2 <2Space means AND
*Any version

^ allows minor and patch upgrades, ~ patch only. A prerelease only matches a range that itself includes a prerelease.

See: Semantic Versioning

Git and URL installs

npm i user/repo --allow-git=all
npm i github:user/repo#main --allow-git=all
npm i https://site.com/archive.tgz --allow-remote=all

npm 12 blocks git and remote URL dependencies by default; opt in per command or in .npmrc.

See: allow-git, allow-remote

0 Comments for this cheatsheet. Write yours!