npm 27 🌐 Cheatsheet

A quick-reference for npm commands, configuration, and dependency resolution. Organized for lookup, not for reading.

---

Core Commands

Command	Purpose
npm init	Create package.json interactively
npm init -y	Create with defaults
npm install	Install all dependencies
npm install <pkg>	Install and save to dependencies
npm install <pkg>@<ver>	Install specific version
npm install -D <pkg>	Install as devDependency
npm install -g <pkg>	Install globally
npm uninstall <pkg>	Remove package
npm update	Update within semver ranges
npm outdated	List outdated packages
npm ls	Show dependency tree
npm explain <pkg>	Why is this installed? (alias: npm why)
npm dedupe	Flatten duplicate dependencies
npm prune	Remove extraneous packages
npm ci	Clean install from lockfile
npm run <script>	Run a script
npm start	Run start script (no run needed)
npm test	Run test script (no run needed)

---

package.json Fields

Field	Purpose
name	Package name (lowercase, no spaces)
version	Semver (x.x.x)
private	Prevent accidental publish
main	CJS entry point
module	ESM entry point (bundler convention)
types	TypeScript declarations
exports	Conditional entry-point map
files	Allowlist of published files
scripts	Named commands
dependencies	Runtime deps
devDependencies	Build/test deps
peerDependencies	Host package expectations
peerDependenciesMeta	Mark peers as optional
overrides	Force transitive versions
workspaces	Monorepo directories
engines	Node/npm version requirements
publishConfig	Publish-time settings (registry, access)

---

Semver Ranges

Range	Meaning
1.2.3	Exact
~1.2.3	Patch updates only (>=1.2.3 <1.3.0)
^1.2.3	Minor updates (>=1.2.3 <2.0.0)
1.2.x	Any patch
* or ""	Any version
>=1.2.3 <2.0.0	Range
1.2.3 - 2.0.0	Inclusive range
latest	The latest dist-tag

---

Publishing

Command	Purpose
npm login	Authenticate with registry
npm whoami	Show logged-in user
npm publish	Publish package
npm publish --access public	Publish scoped package as public
npm publish --tag next	Publish under custom dist-tag
npm unpublish <pkg>@<ver>	Remove version (restricted)
npm deprecate <pkg> "msg"	Mark as deprecated
npm deprecate <pkg> ""	Undeprecate
npm owner ls <pkg>	List maintainers
npm owner add <user> <pkg>	Add maintainer
npm owner rm <user> <pkg>	Remove maintainer
npm dist-tag ls <pkg>	List dist-tags
npm dist-tag add <pkg>@<ver> <tag>	Move a tag
npm dist-tag rm <pkg> <tag>	Remove a tag
npm pack	Create tarball
npm pack --dry-run	List tarball contents without writing

---

Security

Command	Purpose
npm audit	Report vulnerabilities
npm audit --audit-level=moderate	Fail on moderate+
npm audit --omit=dev	Skip devDependencies
npm audit fix	Fix within semver ranges
npm audit fix --force	Fix including major changes
npm audit fix --dry-run	Preview fixes
npm token list	List access tokens
npm token revoke <id>	Revoke a token

---

Configuration

File	Scope
Project .npmrc	Current project
User ~/.npmrc	Current user
Global $PREFIX/etc/npmrc	All users
Builtin	npm installation

Precedence

CLI flags > environment > project .npmrc > user .npmrc > global .npmrc > builtin > defaults

Common .npmrc Keys

Key	Purpose
registry=https://...	Default registry
@scope:registry=https://...	Scoped registry
//host/:_authToken=${NPM_TOKEN}	Scoped auth token
save-exact=true	Pin exact versions
engine-strict=true	Enforce engines
strict-peer-deps=true	Fail on peer conflicts
fund=false	Disable funding messages

Config Commands

Command	Purpose
npm config get <key>	Read effective value
npm config set <key> <val>	Write to user config
npm config delete <key>	Remove setting
npm config list	Show all config

---

Dependency Resolution

Peer Dependencies

{
  "peerDependencies": { "react": "^18.0.0 || ^19.0.0" },
  "peerDependenciesMeta": {
    "chalk": { "optional": true }
  }
}

Situation	Behavior
Peer absent, not optional	ERESOLVE (npm 7+)
Peer absent, optional: true	Install succeeds
Peer present, incompatible	ERESOLVE
--legacy-peer-deps	Skip peer checks (last resort)
--strict-peer-deps	Fail on any conflict

Overrides

{
  "overrides": {
    "semver": "7.5.2",
    "@some/cli": { "semver": "7.5.2" },
    "ejs@2.7.4": "3.1.10",
    "react": "$react"
  }
}

Form	Scope
"pkg": "1.2.3"	Entire tree
"parent": { "pkg": "1.2.3" }	Only under parent
"pkg@1.0.0": "1.2.3"	Only when resolved version is 1.0.0
"pkg": "$pkg"	Match root dependency

---

Workspaces

Command	Purpose
npm init -w ./packages/a	Create a workspace
npm install	Install all, symlink workspaces
npm install <dep> -w <name>	Add dep to one workspace
npm install <ws> -w <name>	Add local workspace as dep
npm run <script> -w <name>	Run script in one workspace
npm run <script> --workspaces	Run in all workspaces
--if-present	Skip workspaces without the script
npm publish -w <name>	Publish one workspace
npm publish --workspaces	Publish all

Root package.json

{
  "private": true,
  "workspaces": ["packages/*", "apps/*"]
}

Hoisting

Situation	Result
Compatible versions	Hoisted to root node_modules
Incompatible versions	Nested in the package that needs it
Undeclared import	Works via hoisting (phantom dependency)

---

Scoped Packages

Command	Purpose
npm init --scope=@org	Initialize with scope
npm publish --access public	Publish scoped package as public
npm publish	Publish as private (paid account)
npm access get status @org/pkg	Check access level
npm access set status=public @org/pkg	Make public
npm access grant read-write @org:team @org/pkg	Grant team access
npm access revoke @org:team @org/pkg	Revoke access

Scope to Registry

@myorg:registry=https://npm.company.com/
//npm.company.com/:_authToken=${NPM_TOKEN}

---

Lifecycle Scripts

Script	Runs When
preinstall	Before install
install	During install
postinstall	After install
prepublishOnly	Before npm publish only
prepare	Before pack/publish, on local install, on git install
prepack	Before tarball creation
postpack	After tarball creation
preversion	Before npm version
version	After version bump
postversion	After commit and tag

---

Debugging

Command	Purpose
npm ls <pkg>	Show resolved version
npm explain <pkg>	Why is it installed?
npm ls --all | grep deduped	Find duplicates
npm install --dry-run	Preview install
npm cache clean --force	Clear cache
npm doctor	Check environment

---

npx

Command	Purpose
npx <pkg>	Run a package binary
npx <pkg>@<ver>	Run a specific version
npx --no-install <pkg>	Fail if not installed locally
npx -p <pkg> <cmd>	Make package available to command

---

Gotchas

Trap	Reality
npm install installs exact versions	It respects semver ranges from package.json
npm ci is the same as install	ci requires lockfile, is faster, fails on mismatch
--legacy-peer-deps is a fix	It hides conflicts; fix them properly
npm update crosses major versions	No; respects package.json ranges
latest tag is the highest version	No; it’s whatever latest points to
devDependencies are omitted in production	Only if NODE_ENV=production or --omit=dev
files field includes everything	It’s an allowlist; only listed files ship
.npmignore overrides files	files takes precedence
Token in .npmrc is safe	Only if scoped to host and gitignored
postinstall runs on npm ci	Yes, unless --ignore-scripts

---

One-Page Flow

INIT → INSTALL → CODE → TEST → PUBLISH

INIT
  npm init -y
  npm install <deps>
  npm install -D <devdeps>

RESOLVE
  npm ls <pkg>          (what version?)
  npm explain <pkg>     (why installed?)
  overrides             (force version)
  peerDependencies      (declare host contract)

PUBLISH
  npm pack --dry-run    (what ships?)
  npm version patch     (bump + tag)
  npm publish           (upload)
  npm audit             (check CVEs)

MONOREPO
  workspaces field      (link packages)
  -w <name>             (target one)
  --workspaces          (target all)
  build tool            (task ordering)

---

---

Stop using slow, ad-bloated tool sites! 🤮

🔎 Search “KandZ Tools” on Google to use many professional utilities for free.

KandZ.me is the ultimate minimalist hub for:
✅ Finance (Mortgage, Interest, Inflation)
✅ Tech (Base64, JSON, Dev Suite, IP)
✅ Health (BMI, BMR, TDEE)
✅ Productivity (Timer, Workspace, QR)

⚡️ Fast & Private
🔒 No data leaves your device
💎 100% Free

🔗 Use it now: https://tools.kandz.me
🔖 Bookmark it—you’ll need it later!