npm Fundamentals

npm (Node Package Manager) is the default package manager for Node.js and the world's largest software registry. Understanding it deeply - install flags, lock files, scripts, and the audit tools - is essential for any JavaScript developer.

Initializing & Installing

# Initialize a new project
npm init                        # Interactive prompt
npm init -y                     # Accept all defaults (fastest)
npm init --scope=@myorg         # Scoped package init

# Install packages
npm install express             # Install + add to dependencies
npm install -D typescript       # Install + add to devDependencies
npm install -O nodemon          # Optional dependency
npm install -g vercel           # Global install (available as CLI)
npm install                     # Install all from package.json
npm install express@4.18.2      # Exact version
npm install express@latest      # Latest (same as no tag)
npm install express@next        # Next/beta dist-tag
npm install github:expressjs/express        # From GitHub repo
npm install github:expressjs/express#v4.18  # Specific tag/branch
npm install ./path/to/local-package         # Local package
npm install https://example.com/pkg.tgz     # Remote tarball

# Install flags
npm install --save-exact        # Pin to exact version (no ^ or ~)
npm install --legacy-peer-deps  # Skip peer dep resolution errors
npm install --force             # Force re-install even if present
npm install --prefer-offline    # Use cache, avoid network

# npm ci (clean install - strictly from lock file)
npm ci                          # Faster than npm install in CI
# npm ci vs npm install:
# - npm ci requires package-lock.json to exist
# - npm ci deletes node_modules first, then installs exact versions
# - npm ci never updates package-lock.json
# - npm ci fails if lock file doesn't match package.json
# Use npm ci in CI/CD pipelines; npm install in local development

Updating & Removing

# Update packages
npm update                      # Update all to latest allowed by semver range
npm update express              # Update specific package
npm update -g npm               # Update npm itself
npm update --save               # Update + write new versions to package.json

# Check for outdated packages
npm outdated                    # Show current/wanted/latest versions
npm outdated -g                 # Check global packages

# Uninstall
npm uninstall express           # Remove from node_modules + package.json
npm uninstall -D typescript     # Remove devDependency
npm uninstall -g vercel         # Uninstall global

# Prune (remove packages not in package.json)
npm prune                       # Remove extraneous packages
npm prune --production          # Remove devDependencies (for production builds)

Listing & Auditing

# List installed packages
npm list                        # Full tree (verbose)
npm list --depth=0              # Top-level only
npm list -g --depth=0           # Global top-level
npm list express                # Find a specific package in tree
npm ls express                  # Alias for npm list

# Package info
npm info express                # Full registry info
npm info express version        # Latest version only
npm info express versions       # All published versions
npm info express peerDependencies
npm docs express                # Open package docs in browser
npm home express                # Open package homepage
npm repo express                # Open GitHub repo

# Security audit
npm audit                       # Show vulnerabilities
npm audit --json                # JSON output for parsing
npm audit fix                   # Auto-fix vulnerabilities (semver-compatible)
npm audit fix --force           # Force updates (may introduce breaking changes)
npm audit fix --dry-run         # Preview what would change

# Cache management
npm cache clean --force         # Clear npm cache
npm cache verify                # Verify cache integrity

Running Scripts

# Run scripts defined in package.json "scripts"
npm run dev
npm run build
npm run test
npm test          # Shorthand (no "run" needed for test)
npm start         # Shorthand for npm run start
npm stop          # Shorthand for npm run stop

# Pass args to scripts (after --)
npm run test -- --watchAll
npm run build -- --profile
npm test -- --testPathPattern=auth

# List all available scripts
npm run

# npx: run a package binary without installing globally
npx create-next-app@latest my-app
npx tsc --noEmit
npx prisma migrate dev
npx tsx scripts/seed.ts

# npx with specific version
npx cowsay@1.5 "hello"

# Check npm version and config
npm --version
npm config list
npm config list --json
npm config get registry         # https://registry.npmjs.org/
npm config set registry https://registry.npmjs.org/
npm config set save-exact true  # Always pin exact versions globally