Module F-5 — npm and the Node.js Ecosystem

From production: A team had an unpinned ^ dependency on a date/timezone library, deep in their package.json. The library shipped what its own semver labeled a "non-breaking" minor version — but that release quietly changed a default timezone-handling behavior. The same week that version was published, CI ran a fresh npm install (no lock file committed for that particular service, or the lock file was stale enough to allow the update) and pulled it in. Nobody touched application code. A UPI reconciliation job that depended on that library to compute settlement cut-off times started miscalculating them — by hours — because a "minor" version bump changed something the job's correctness quietly depended on. This is exactly the failure mode package-lock.json exists to prevent: committing it and using npm ci in CI/CD means a library publishing a surprising "non-breaking" change doesn't silently ride into your build the next time someone runs an install.

# Always commit package-lock.json to version control
git add package-lock.json

# Install from lock file exactly (use in CI/CD and production)
npm ci
 
# Install and update lock file (use during development when adding packages)
npm install

Key rule: npm ci for CI/CD pipelines and Docker builds. npm install when you're actively developing and want to add/update packages.

Never manually edit package-lock.json. It is generated by npm.

---

Essential npm Commands

# Install all dependencies (reads package.json + lock file)
npm install
 
# Install a specific package
npm install express
npm install -D nodemon          # devDependency
 
# Install a specific version
npm install express@4.18.2
npm install express@latest      # latest published version
 
# Remove a package
npm uninstall express
 
# Update packages (respects semver ranges in package.json)
npm update
npm update express              # update specific package
 
# Check for outdated packages
npm outdated
 
# See what's installed
npm list
npm list --depth=0              # only top-level packages
 
# Run a script from package.json
npm run dev
npm run build
npm test                        # shorthand for npm run test
npm start                       # shorthand for npm run start
 
# Check for security vulnerabilities
npm audit
npm audit fix                   # auto-fix safe updates

When npm audit fix Can't Fix It: the overrides Field

npm audit fix works well when the vulnerable package is one you depend on directly — it just bumps the version. It's much less useful when the vulnerability is several layers deep: your dependency depends on another package, which depends on the vulnerable one. You don't control that inner package.json, so there's nothing for npm audit fix to bump.

The "overrides" field in your own package.json forces a specific version of a package everywhere it appears in your dependency tree, no matter how deeply nested:

{
  "overrides": {
    "vulnerable-transitive-package": "2.1.4"
  }
}

After adding this and running npm install, every dependency that would have pulled in an older, vulnerable version of vulnerable-transitive-package gets 2.1.4 instead — even though none of your direct dependencies were updated. This is the tool to reach for when npm audit reports a vulnerability and npm audit fix says there's nothing it can safely do about it.

Beyond Known CVEs: Supply-Chain Risk

npm audit only catches vulnerabilities that have already been reported and cataloged. It says nothing about a broader category of risk: supply-chain attacks, where the package itself — not a bug in it — is the threat. Two common forms:

• Typosquatting: a malicious package published under a name one keystroke away from a popular package (expres instead of express, reactt instead of react), hoping a rushed npm install or a typo in a script catches someone.
• Compromised packages: an attacker gains access to a legitimate, trusted package's publishing credentials and slips malicious code into a new version of a package thousands of projects already depend on. npm audit won't flag this until (and unless) it's discovered and reported after the fact.

There's no single command that eliminates this risk, but the habits that reduce it: double-check package names before installing, be wary of packages with very few downloads or a very new publish date for something claiming to be well-established, and keep package-lock.json committed and use npm ci — so a compromised new version of a transitive dependency can't silently slide into a build just because someone happened to run npm install that week.

---

npx: Run Without Installing

npx runs a package without permanently installing it. Useful for one-off tools and project generators:

# Create a new project (runs create-react-app without installing it globally)
npx create-react-app my-app
 
# Run a package that's not installed
npx cowsay "Hello from Node.js"
 
# Run a specific version
npx node@20 --version
 
# Run a locally-installed package binary directly from the terminal
npx jest                        # runs jest from node_modules/.bin/jest

---

npm Scripts

The "scripts" field in package.json is more powerful than it looks. npm adds node_modules/.bin to the PATH when running scripts, so you can reference package binaries directly without npx:

{
  "scripts": {
    "start": "node src/index.js",
    "dev": "nodemon src/index.js --watch src",
    "build": "tsc --outDir dist",
    "test": "jest --coverage",
    "test:watch": "jest --watch",
    "lint": "eslint src --ext .ts,.js",
    "lint:fix": "eslint src --ext .ts,.js --fix",
    "db:migrate": "prisma migrate dev",
    "db:seed": "node scripts/seed.js",
    "clean": "rm -rf dist node_modules"
  }
}

You can also run scripts in sequence (&&) or in parallel (&):

{
  "scripts": {
    "build:all": "npm run lint && npm run test && npm run build",
    "dev:all": "node server.js & npx tailwindcss --watch"
  }
}

Pre and post hooks run automatically:

{
  "scripts": {
    "pretest": "npm run lint",     // runs before npm test
    "test": "jest",
    "posttest": "npm run clean"    // runs after npm test
  }
}

---

node_modules

When you run npm install, every package and its dependencies are downloaded into node_modules/. This folder can be enormous — a typical project has hundreds of megabytes. Two rules:

1. Never commit node_modules to git. Add it to .gitignore.
2. Always commit package-lock.json to git. Your colleagues need it to get the same versions.

# .gitignore
node_modules/
dist/
.env
*.log

If node_modules gets corrupted or out of sync, delete it and reinstall:

rm -rf node_modules
npm install

---

Essential Packages for Every Project

These are the packages you will install in almost every Node.js project:

Development tools:

# Auto-restarts server when files change
npm install -D nodemon
 
# TypeScript (covered in P-3)
npm install -D typescript ts-node @types/node
 
# ESLint for code quality
npm install -D eslint
 
# Prettier for formatting
npm install -D prettier

Runtime utilities:

# Environment variables from .env file
npm install dotenv
 
# HTTP framework (covered in F-6)
npm install express
 
# TypeScript types for Express
npm install -D @types/express
 
# Schema validation (covered in P-4)
npm install zod
 
# HTTP client for outbound requests
npm install axios
# or use built-in fetch (Node 18+) — no install needed

Nodemon configuration — create nodemon.json at the project root to avoid typing flags:

{
  "watch": ["src"],
  "ext": "ts,js,json",
  "ignore": ["src/**/*.test.ts"],
  "exec": "ts-node src/index.ts"
}

---

Global vs Local Packages

Most packages should be installed locally (in your project's node_modules). This ensures every project uses its own version and colleagues get the same thing.

# Local install (correct for project dependencies)
npm install express
npm install -D nodemon
 
# Global install (use only for CLI tools you run anywhere)
npm install -g typescript
npm install -g nodemon      # acceptable for personal tools
 
# See globally installed packages
npm list -g --depth=0

The rule: if the package is a dependency of your project, install it locally. If it's a CLI tool you want available everywhere on your machine (like ts-node for quick scripts), install globally. In CI/CD, always use local packages.

---

.npmrc: Configuring npm Itself

Separate from package.json (which describes your project), .npmrc is a plain config file for npm's own behavior. You've already seen one setting it controls — engine-strict=true, which turns the "engines" field from a warning into a hard install failure. A few other common uses:

# .npmrc
 
# Enforce the "engines" field instead of just warning
engine-strict=true
 
# Use a different registry (common for private/company packages)
registry=https://registry.npmjs.org/
 
# Save exact versions instead of ^-prefixed ranges by default
save-exact=true

.npmrc can live in your project root (applies to that project only), in your home directory (applies to every project you run npm in), or be set globally. Project-level .npmrc is the one worth committing to git — it's how a team agrees on shared npm behavior (like engine-strict) without every developer configuring it by hand.

---

Workspaces (Monorepos)

If you have multiple packages in one repository (a monorepo), npm workspaces let you manage them together:

// Root package.json
{
  "name": "my-monorepo",
  "workspaces": ["packages/*", "apps/*"]
}

npm install              # installs dependencies for all workspaces
npm run build -w api     # run build in the 'api' workspace only

Workspaces are out of scope for Foundation — just know they exist for when you encounter them.

---

Common Mistakes

Installing in the wrong directory:

# ❌ Wrong — running npm install from a subdirectory
cd src && npm install express
 
# ✅ Correct — always from the project root (where package.json is)
npm install express

Committing .env:

# Always in .gitignore
.env
.env.local
.env.production

Not pinning the Node.js version:

// package.json — documents the Node version your code targets
{
  "engines": {
    "node": ">=20.0.0"
  }
}

Note that this field is informational by default: npm install on the wrong Node version prints a warning but still proceeds. If you actually want installs blocked on the wrong version, add engine-strict=true to a .npmrc file. Either way, "engines" alone won't stop someone from running your code on an unsupported version — pair it with .nvmrc for that.

Also create a .nvmrc at the project root:

20

Then anyone running nvm use automatically switches to the right version.

Using npm install in CI/CD:

# ❌ npm install can update the lock file
npm install
 
# ✅ npm ci installs exactly what's in the lock file and is faster
npm ci

---

Summary

• package.json is the project manifest. dependencies for runtime packages, devDependencies for dev tools. "scripts" for commands.
• Semantic versioning: MAJOR.MINOR.PATCH. ^ (caret) allows minor and patch updates. Pin exact versions only when necessary.
• package-lock.json ensures reproducible installs. Always commit it. Use npm ci in CI/CD.
• npm install <pkg> for runtime, npm install -D <pkg> for dev tools. Never install project dependencies globally.
• npx runs packages without installing them globally — ideal for project generators and one-off tools.
• .nvmrc pins the Node.js version. .gitignore excludes node_modules/ and .env. Both are mandatory.

Next: building HTTP servers with Express — routing, middleware, query parameters, and the structure of a real REST API.

---