npm & package.json Cheat Sheet

New

npm commands, package.json fields, scripts, versioning, and workspace management

Common Commands

npm install

Install all dependencies from package.json

npm install
npm i              # shorthand
npm install --production  # skip devDependencies

npm install <pkg>

Install a package and add to dependencies

npm install react
npm install -D typescript   # devDependency
npm install -g nodemon      # global install

npm run

Execute a script defined in package.json

npm run dev
npm run build
npm start    # shorthand for npm run start
npm test     # shorthand for npm run test

npm update

Update packages to the latest allowed version

npm update             # update all
npm update react       # update one package
npm outdated           # list outdated packages

npm uninstall

Remove a package and update package.json

npm uninstall lodash
npm uninstall -D eslint  # remove devDependency

npm publish

Publish a package to the npm registry

npm login
npm publish
npm publish --access public  # for scoped packages

package.json Fields

name & version

Required fields that identify the package

"name": "my-app",
"version": "1.0.0",

scripts

Custom commands runnable with npm run <name>

"scripts": {
  "dev": "next dev",
  "build": "next build",
  "start": "next start",
  "lint": "eslint ."
},

dependencies

Packages required at runtime

"dependencies": {
  "react": "^18.2.0",
  "next": "14.0.0"
},

devDependencies

Packages only needed during development and build

"devDependencies": {
  "typescript": "^5.0.0",
  "eslint": "^8.0.0"
},

peerDependencies

Packages the consumer must provide (plugins, libraries)

"peerDependencies": {
  "react": ">=17.0.0"
},

Versioning (SemVer)

Caret (^)

Allow minor and patch updates (compatible changes)

"react": "^18.2.0" // allows 18.x.x but not 19.x.x

Tilde (~)

Allow only patch updates

"react": "~18.2.0" // allows 18.2.x but not 18.3.x

Exact version

Lock to an exact version

"react": "18.2.0" // exactly this version

Range notation

Accept a specific version range

"react": ">=17.0.0 <19.0.0"

npx

Run without install

Execute a package binary without installing it globally

npx create-next-app@latest my-app
npx tsc --noEmit
npx prettier --write .

npm Workspaces

Workspace setup

Define workspaces in root package.json for monorepos

"workspaces": ["packages/*", "apps/*"]

Run in workspace

Run a script in a specific workspace

npm run build --workspace=packages/ui
npm run dev -w apps/web

Common Patterns

package.json Scripts Section

Common scripts configuration for a Next.js project

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint",
    "lint:fix": "eslint . --fix",
    "type-check": "tsc --noEmit",
    "format": "prettier --write .",
    "test": "jest",
    "test:watch": "jest --watch",
    "clean": "rm -rf .next node_modules"
  }
}

.npmrc Configuration

Common .npmrc settings for a project

# .npmrc
save-exact=true          # use exact versions (no ^ or ~)
engine-strict=true       # fail if Node version doesn't match
legacy-peer-deps=false   # enforce peer dep resolution
@myorg:registry=https://npm.pkg.github.com  # scoped registry

Lockfile Explained

Why package-lock.json matters

# package-lock.json
# - Records the exact resolved version of every dependency
# - Must be committed to version control
# - npm ci installs from lockfile exactly (faster in CI)

npm ci          # clean install from lockfile (CI/CD)
npm install     # install + may update lockfile

# Never delete package-lock.json without a reason
# It ensures reproducible builds across environments