Getting started
Introduction
npm is the package manager for Node.js. This reference covers everyday commands, package specifiers, and npm 12 defaults.
- npm CLI documentation (docs.npmjs.com)
- package.json reference (docs.npmjs.com)
Install
| Command | Description |
|---|---|
npm install | Install dependencies from package.json |
npm install --omit=dev | Skip devDependencies |
npm install --min-release-age=7 | Only install releases older than 7 days |
npm install -g pkg | Install a package globally |
npm ci | Clean install from package-lock.json |
--production is deprecated; use --omit=dev.
See: npm install
Add packages
| Command | Description |
|---|---|
npm i lodash | Add to dependencies |
npm i -D vitest | Add to devDependencies |
npm i -E lodash | Save an exact version |
npm i -O fsevents | Add to optionalDependencies |
npm i --no-save lodash | Install 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
| Command | Description |
|---|---|
npm rm lodash | Remove from dependencies |
npm rm -D vitest | Remove from devDependencies |
npm rm -g pkg | Remove a global package |
See: npm uninstall
Inspecting
Listing
Outdated and audit
| Command | Description |
|---|---|
npm outdated | List outdated packages |
npm audit | Report known vulnerabilities |
npm audit fix | Apply compatible fixes |
npm audit fix --force | Apply breaking fixes |
npm audit signatures | Verify registry signatures |
See: npm audit
Explain a dependency
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
| Command | Description |
|---|---|
npm update | Update within semver ranges |
npm update --save | Also update package.json |
npm update -g | Update global packages |
npm update lodash | Update one package |
npm update updates production and dev packages; it leaves package.json alone unless --save is given.
See: npm update
Version
| Command | Description |
|---|---|
npm version 1.2.3 | Set an exact version |
npm version major | Bump to 2.0.0 |
npm version minor | Bump to 1.3.0 |
npm version patch | Bump to 1.2.4 |
npm version prerelease --preid rc | Bump 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.
Scripts
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
| Command | Description |
|---|---|
npm i sax | Registry package |
npm i sax@latest | Latest tag |
npm i sax@3.0.0 | Exact version |
npm i sax@">=1 <2.0" | Version range |
npm i @org/sax | Scoped package |
npm i /path/to/repo | Local directory |
npm i ./archive.tgz | Local tarball |
See: Package spec
Version ranges
| Range | Matches |
|---|---|
1.2.3 | Exactly 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 <2 | Space 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!