← Node.js from Scratch to Advanced
Lesson 3 of 3

npm and package.json, Explained

SoftwareBeginner

Reusing Code Other People Wrote

npm (Node Package Manager) installs code other people published so you do not have to write it yourself. package.json is the manifest that lists which packages your project depends on and which versions are acceptable.

json
{
  "name": "my-app",
  "version": "1.0.0",
  "dependencies": {
    "express": "^4.19.2"
  }
}

The ^ before a version means "this version or a newer compatible one." package-lock.json then pins the exact versions actually installed, so everyone on a team - and your production server - gets identical code.

npm install reads package.json, downloads everything listed (and their own dependencies) into a node_modules folder, and writes or updates package-lock.json to match.

Semantic Versioning, Decoded

Package versions follow a MAJOR.MINOR.PATCH pattern - 4.19.2 means major version 4, minor version 19, patch 2. The convention (not enforced by anything, just widely followed) is: patch bumps are bug fixes, minor bumps add features without breaking existing code, major bumps are allowed to break things.

text
"express": "^4.19.2"   -> accepts 4.19.2 up to (but not including) 5.0.0
"express": "~4.19.2"   -> accepts 4.19.2 up to (but not including) 4.20.0
"express": "4.19.2"    -> accepts exactly that version, nothing else

A real, common mistake: committing node_modules to git (don't - it's regenerated from package.json and can be hundreds of megabytes) but NOT committing package-lock.json (do commit this one - it pins the exact versions everyone gets, and skipping it is how "works on my machine" bugs happen when two people install the same package.json a week apart and get different transitive dependency versions).

Where This Bites You at Work

Dependency drift is a real, ongoing cost on any team's codebase: packages you depend on get updated, some of those updates carry known vulnerabilities, and `npm audit` is the standard way to check. It's worth running periodically, not just when something breaks - supply-chain attacks (a legitimate package getting compromised and pushing malicious code in a routine update) are an increasingly real risk, and a stale lockfile is exactly the kind of thing that goes unnoticed for months.