npm: Managing Packages

npm (Node Package Manager) is the world's largest software registry — over 2 million packages. It handles installing libraries, running scripts, and managing your project's dependencies. Every JavaScript project you'll work on uses it.

package.json

Every npm project starts with package.json — the manifest file:

# Initialize a new project (interactive)
npm init

# Quick init with defaults
npm init -y

{
  "name": "my-project",
  "version": "1.0.0",
  "description": "A cool project",
  "main": "index.js",
  "type": "module",
  "scripts": {
    "start": "node index.js",
    "dev": "node --watch index.js",
    "build": "tsc",
    "test": "vitest",
    "lint": "eslint src/"
  },
  "dependencies": {
    "express": "^4.21.0",
    "dotenv": "^16.4.0"
  },
  "devDependencies": {
    "typescript": "^5.6.0",
    "vitest": "^2.1.0",
    "@types/express": "^5.0.0"
  }
}

Installing Packages

# Install and save to dependencies
npm install express
npm i express           # shorthand

# Install dev dependency (build tools, testing, type definitions)
npm install -D typescript
npm install --save-dev vitest

# Install globally (available anywhere on your system)
npm install -g typescript
npm install -g pnpm

# Install exact version
npm install react@18.3.1

# Install all dependencies from package.json
npm install

# Update packages
npm update
npm update express      # update specific package

# Remove a package
npm uninstall lodash
npm uninstall -g old-tool

Semantic Versioning

npm uses semver: MAJOR.MINOR.PATCH

1.2.3
│ │ └─ Patch: bug fixes (backwards compatible)
│ └─── Minor: new features (backwards compatible)
└───── Major: breaking changes

# Version ranges in package.json
"express": "4.21.0"   # exact version only
"express": "^4.21.0"  # compatible: 4.x.x (most common)
"express": "~4.21.0"  # patch only: 4.21.x
"express": ">=4.0.0"  # minimum version
"express": "*"        # any version (avoid!)

package-lock.json

# ALWAYS commit package-lock.json to git
# It locks exact versions for reproducible builds

# npm ci — install from lock file exactly (for CI/CD)
npm ci

# npm install — updates lock file based on package.json ranges
npm install

npm Scripts

Scripts are shortcuts for common commands:

{
  "scripts": {
    "start": "node dist/index.js",
    "dev": "tsx watch src/index.ts",
    "build": "tsc && vite build",
    "test": "vitest run",
    "test:watch": "vitest",
    "test:coverage": "vitest run --coverage",
    "lint": "eslint src/ --fix",
    "format": "prettier --write src/",
    "db:migrate": "prisma migrate dev",
    "db:seed": "tsx prisma/seed.ts",
    "clean": "rimraf dist"
  }
}

# Run scripts
npm run dev
npm run test
npm run build

# Special scripts (no 'run' needed)
npm start
npm test

# Pass arguments
npm run test -- --reporter verbose

Viewing Packages

# List installed packages
npm list                  # all (tree view)
npm list --depth=0        # top-level only

# Check outdated packages
npm outdated

# Get info about a package
npm info express
npm info express version  # latest version only

# Search for packages
npm search "http client"

# View package on npm website
npm home express

Important Packages to Know

# HTTP
npm i axios           # HTTP client (alternative to fetch)
npm i got             # modern HTTP client

# Utilities
npm i lodash          # utility functions (though ES6+ reduces need)
npm i date-fns        # date manipulation

# Validation
npm i zod             # schema validation
npm i joi             # validation

# Testing
npm i -D vitest           # fast test runner (Vite-based)
npm i -D jest             # popular test runner
npm i -D @testing-library/dom  # DOM testing

# Build tools
npm i -D typescript   # TypeScript
npm i -D vite         # build tool
npm i -D esbuild      # ultra-fast bundler

# Linting
npm i -D eslint       # JavaScript linter
npm i -D prettier     # code formatter

npx — Run Without Installing

# Run a package without installing globally
npx create-react-app my-app
npx create-next-app@latest my-project
npx prisma generate

# Run specific version
npx typescript@4.9 --version

# Run a local binary (in node_modules/.bin)
npx vitest run

.npmrc Configuration

# .npmrc — per-project or global settings
registry=https://registry.npmjs.org/
save-exact=true          # install exact versions instead of ^ ranges
engine-strict=true       # fail if Node.js version doesn't match "engines" field

Alternatives to npm

# pnpm — faster, uses hard links (saves disk space)
npm i -g pnpm
pnpm install
pnpm add express
pnpm run dev

# yarn — developed by Facebook, similar to npm
npm i -g yarn
yarn install
yarn add express
yarn dev

# bun — super fast runtime + package manager
bun install
bun add express
bun run dev

For new projects, pnpm is highly recommended — it's faster and more disk-efficient than npm.

Next lesson: Vite — the modern build tool that makes development fast.