📦 NPM Package Management

What Is npm?

npm (Node Package Manager) ships with Node.js and wears three hats at once:

• A registry — a giant public database of reusable JavaScript packages at npmjs.com, with millions of packages and billions of weekly downloads.
• A command-line tool — the npm command you use to install, update, publish, and run.
• A standard — conventions (like package.json) for describing and structuring projects.

🍳 A useful analogy: npm is both a communal cookbook — where developers publish recipes (packages) anyone can reuse — and the kitchen tools that fetch those recipes into your own cooking. Instead of writing everything from scratch, you assemble your app from trusted, ready-made ingredients.

The package.json Manifest

Every Node project has a package.json at its root — the manifest that describes the project and everything it depends on. Here is an annotated example:

{
  "name": "my-awesome-project",
  "version": "1.0.0",
  "description": "A project that does awesome things",
  "type": "module",
  "main": "index.js",
  "scripts": {
    "start": "node index.js",
    "dev": "node --watch index.js",
    "test": "jest"
  },
  "keywords": ["awesome", "node"],
  "author": "Your Name <email@example.com>",
  "license": "MIT",
  "dependencies": {
    "express": "^4.19.2"
  },
  "devDependencies": {
    "jest": "^29.7.0"
  }
}

The fields you will touch most:

• name / version — identity of your project (version follows SemVer, below).
• type — "module" opts the project into ES Modules; omit it for CommonJS.
• main — the entry file loaded when someone imports your package.
• scripts — named commands you run with npm run.
• dependencies / devDependencies — the packages your project needs.

Creating one

Two ways to generate a package.json:

# Interactive — prompts you for each field
npm init

# Accept all defaults instantly
npm init -y

Dependencies & Semantic Versioning

A dependency is an external package your project relies on. npm splits them into two buckets, and getting the split right keeps your production builds lean.

🔧 Workshop analogy: dependencies are the parts that ship inside the finished product; devDependencies are the tools on your workbench that help you build it but never leave the shop.

Semantic Versioning (SemVer)

Package versions follow the pattern MAJOR.MINOR.PATCH:

In package.json, a prefix defines the range of versions npm may install:

Installing & Managing Packages

The everyday npm commands:

# Install a runtime dependency
npm install express        # or: npm i express

# Install a dev-only dependency
npm install jest --save-dev   # or: npm i jest -D

# Install a specific version
npm install express@4.18.2

# Install everything listed in package.json
npm install

# Install a global CLI tool (available system-wide)
npm install -g http-server

# Remove a package
npm uninstall express      # or: npm rm express

# See what is outdated, then update within your ranges
npm outdated
npm update

Installing packages creates a node_modules/ directory holding the actual code, plus a package-lock.json. Because node_modules/ can grow huge, you never commit it — you .gitignore it and let teammates rebuild it with npm install.

🍳 Kitchen analogy: package.json is your shopping list, node_modules/ is the delivery of ingredients to your kitchen, and package-lock.json is the itemized receipt recording exactly what arrived and from where.

package-lock.json & Reproducibility

Your package.json may say "^4.19.2" — a range. So how does every teammate and every server end up with the exact same code? The answer is package-lock.json, which npm generates automatically and which records:

• The exact resolved version of every package (and every package's packages)
• The full dependency tree, deeply nested
• An integrity checksum to verify each download was not tampered with
• The URL each package was fetched from

Because it pins exact versions, the lockfile kills the classic "but it works on my machine" bug:

npm Scripts & npx

The scripts field turns long commands into short, memorable names you run with npm run <name>:

"scripts": {
  "start": "node server.js",
  "dev": "node --watch server.js",
  "test": "jest",
  "lint": "eslint .",
  "build": "webpack --mode production",
  "deploy": "npm run build && firebase deploy"
}

npm run dev
npm run lint

# start and test have built-in shortcuts (no "run" needed)
npm start
npm test

Chaining and lifecycle hooks

Combine scripts with &&, and lean on npm's automatic pre/post hooks. Running npm run deploy automatically runs predeploy first (if it exists), then deploy, then postdeploy:

"scripts": {
  "clean": "rimraf dist",
  "prebuild": "npm run clean",
  "build": "webpack",
  "predeploy": "npm run build",
  "deploy": "firebase deploy"
}

npx — run without installing

npx executes a package's command-line tool without a global install, fetching it on the fly:

# Scaffold a new app without polluting your global installs
npx create-react-app my-app

# Pin a specific version for a one-off run
npx cowsay@2.0.0 "Hello!"

Keeping things secure

Every dependency is code you are trusting. Audit regularly:

# Report known vulnerabilities in your dependency tree
npm audit

# Auto-fix what can be fixed safely
npm audit fix

Hands-on Exercise

mkdir npm-lab && cd npm-lab
npm init -y
npm install express          # lands in "dependencies"
npm install jest --save-dev  # lands in "devDependencies"

"scripts": {
  "dev": "node --watch index.js",
  "test": "jest"
}

Summary & Quiz

📚 Further Reading

• npm docs — package.json reference
• Semantic Versioning specification
• npm docs — npm ci (reproducible installs)

🚀 What's Next?

With package management under your belt, the next lesson turns to Node's built-in toolbox — the core modules fs, path, and http — that let you read files, build cross-platform paths, and stand up a web server with zero dependencies.