Module F-5·18 min read

package.json anatomy, semantic versioning, package-lock.json, npm scripts, and the essential dev tools every Node.js engineer installs first.

JJS

Written by Jatin Jain Saraf · Senior Software Engineer

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

Q: In a `package.json` file, what does the version range `"express": "^4.18.2"` permit npm to install?

Any version from 4.18.2 up to, but not including, 5.0.0 (i.e., minor and patch updates). — The caret (`^`) symbol in semantic versioning permits npm to automatically install minor and patch updates (which are meant to be backward-compatible). It will install anything `>= 4.18.2` and `< 5.0.0`. To restrict to patch updates only (4.18.x), you would use the tilde (`~`).

Q: Why is `npm ci` preferred over `npm install` in automated CI/CD environments?

Because `npm ci` strictly installs the exact versions recorded in `package-lock.json` and fails if the lock file is missing or out of sync. — `npm ci` (clean install) ensures perfectly reproducible builds by strictly adhering to `package-lock.json`. It deletes any existing `node_modules` folder, installs exact dependencies, and never updates the lock file. `npm install` can inadvertently update dependencies if the `package.json` ranges allow it.

Q: What is the main use case for the `npx` command?

To run an npm package executable without permanently installing it globally on your machine. — `npx` (Node Package Execute) is designed to run command-line tools and executables directly from the npm registry without needing a global installation. This is highly useful for one-off commands like project generators (e.g., `npx create-react-app`) or running specific tool versions.

What this module covers: npm is the package manager for Node.js — but it is also the command-line tool you use to run scripts, manage dependencies, and maintain your project. Understanding package.json, semantic versioning, the lock file, and the npm CLI is not optional. Every Node.js project uses these. This module also covers the essential packages every engineer installs on day one and the most common mistakes that cost hours to debug.

What npm Is

npm stands for Node Package Manager. It ships with Node.js — when you install Node, you get npm automatically. It does three things:

Registry: A central database of over two million open-source JavaScript packages at npmjs.com
CLI: The npm command you run to install, update, and remove packages
Package format: The conventions (package.json, node_modules, lock files) that define a Node.js project

When you run npm install express, npm downloads the Express package and its dependencies from the registry into your project's node_modules folder.

package.json

Every Node.js project has a package.json at its root. It is the project's manifest — its name, version, dependencies, scripts, and configuration. Create one:

bash

npm init          # Interactive prompts
npm init -y       # Accept all defaults (fastest)

A typical package.json:

json

{
  "name": "my-api",
  "version": "1.0.0",
  "description": "A simple REST API",
  "main": "src/index.js",
  "type": "module",
  "scripts": {
    "start": "node src/index.js",
    "dev": "nodemon src/index.js",
    "test": "jest",
    "lint": "eslint src/"
  },
  "dependencies": {
    "express": "^4.18.2",
    "dotenv": "^16.3.1"
  },
  "devDependencies": {
    "nodemon": "^3.0.1",
    "jest": "^29.7.0",
    "eslint": "^8.55.0"
  },
  "engines": {
    "node": ">=20.0.0"
  }
}

Key fields:

"name" — must be lowercase, no spaces. Used as the package name if you publish to npm.
"version" — follows semantic versioning (covered shortly).
"main" — the entry point when someone requires your package. For apps, this is your server entry file.
"type": "module" — makes all .js files use ES Modules. Omit for CommonJS.
"scripts" — shortcuts for commands. npm run dev runs whatever is under "dev".
"dependencies" — packages required to run in production.
"devDependencies" — packages only needed during development (testing, linting, build tools).
"engines" — documents the Node.js version(s) your project is intended to run on. By default npm does not enforce this — it will still install and run on the "wrong" version, just with a warning. It becomes a hard block only if you also set engine-strict=true in .npmrc.

dependencies vs devDependencies

bash

npm install express          # → goes in "dependencies"
npm install --save-dev jest  # → goes in "devDependencies"
npm install -D nodemon       # → shorthand for --save-dev

When you deploy to production, you can run npm install --omit=dev to skip devDependencies — keeping the production image smaller.

`peerDependencies`

There's a third dependency field you'll run into once you start using plugin-style packages: "peerDependencies". It declares "this package needs a compatible version of X to already be installed by whoever uses me" — instead of bundling its own copy of X. React component libraries do this with react itself; ESLint plugins do it with eslint.

json

{
  "name": "some-eslint-plugin",
  "peerDependencies": {
    "eslint": ">=8.0.0"
  }
}

This is the source of a warning almost every beginner hits and is confused by: npm install reports something like npm WARN some-eslint-plugin@1.0.0 requires a peer of eslint@>=8.0.0 but none is installed. It's not an error — npm is telling you the plugin expects you to also have eslint installed at a compatible version, because it assumes you already do (as the thing it's plugging into). Install the peer dependency yourself and the warning goes away.

Semantic Versioning

Every npm package uses semantic versioning (semver): MAJOR.MINOR.PATCH.

Part	When it changes	Example
`MAJOR`	Breaking change — your code may need updating	`4.0.0` → `5.0.0`
`MINOR`	New features, backwards compatible	`4.18.0` → `4.19.0`
`PATCH`	Bug fixes, backwards compatible	`4.18.2` → `4.18.3`

In package.json, version ranges control which updates you accept automatically:

json

"express": "4.18.2"    // exact — only this version
"express": "~4.18.2"   // patch updates only — 4.18.x
"express": "^4.18.2"   // minor + patch updates — 4.x.x (most common)
"express": "*"         // any version — avoid this
"express": ">=4.0.0"   // 4.0.0 or higher

^ (caret) is the default when you npm install express. It allows 4.19.0, 4.18.3, but not 5.0.0.

Analogy: The caret (^) is a bouncer who lets in anyone from the same major-version family as long as they don't break the dress code — patch and minor releases are safe guests, a major bump is a completely different party.

The practical rule: use ^ for most packages. Pin to an exact version only if the package is known to have breaking changes in minor versions (rare but it happens).

package-lock.json

The lock file records the exact version of every package — and every package's dependencies — that was installed. This is critical.

The problem it solves: package.json says "express": "^4.18.2". On Monday you install and get 4.18.2. On Tuesday a colleague installs and gets 4.19.0 (just released). Your environments are different. The lock file ensures everyone gets exactly the same versions.

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.

bash

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

bash

# 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

bash

# 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:

json

{
  "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:

bash

# 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:

json

{
  "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 (&):

json

{
  "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:

json

{
  "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:

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

bash

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

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

bash

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:

bash

# 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:

bash

# 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:

json

{
  "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.

bash

# 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:

ini

# .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:

json

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

bash

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:

bash

# ❌ 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:

bash

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

Not pinning the Node.js version:

json

// 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:

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

Using npm install in CI/CD:

bash

# ❌ 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.

Knowledge Check

In a package.json file, what does the version range "express": "^4.18.2" permit npm to install?

Why is npm ci preferred over npm install in automated CI/CD environments?

What is the main use case for the npx command?

Test your knowledge with more question sets

Sign in to keep reading

The rest of this module is free — sign in with Google to unlock it and track your progress.

PreviousModule F-4: Async JavaScript: Callbacks, Promises, and the Event Loop Intro Next Module F-6: Building HTTP Servers and REST APIs with Express

Discussion

Join the discussion

Loading comments...