Every JavaScript developer has had the experience of installing Node.js for one specific task — building a React project, running a build tool, executing a tutorial — and never quite understanding what they installed or why npm came along for the ride. The two pieces of software are quietly foundational to the entire modern web (almost every site you load is built or served with help from at least one of them), and they’re explained badly almost everywhere because the documentation assumes you already know what a JavaScript runtime is and why package management matters.
This monograph is the plain-language explanation, written for the developer who is comfortable with one or two other languages, has used Node and npm without understanding them, and now wants to understand them. The first half is what they each are, separately and together. The second half is how to actually use them — the command cheat-sheet, the dependency model, the worked example of building a small web server, and the dozen gotchas that catch new developers in their first month.
What it covers
Twelve sections, about twelve minutes of reading.
§ 01 — The one-sentence version. Node.js is JavaScript outside the browser. npm is the package manager that ships with it. Everything else is footnotes on these two facts.
§ 02 — What is Node.js, really? The V8 JavaScript engine (Chrome’s, originally) packaged as a standalone runtime, with a standard library for filesystem access, networking, child processes, and the rest of the things browsers won’t let JavaScript do. The event loop and why it’s non-blocking by design.
§ 03 — What is npm, really? The world’s largest package registry (>3 million packages as of 2026). The CLI tool of the same name that downloads from that registry. The package.json file that declares what your project depends on. Why the registry exists, who maintains it, and what happens when it breaks (the famous left-pad incident).
§ 04 — How they fit together. Why npm ships with Node. The directed-graph relationship: Node is the runtime, npm is the tool that adds capabilities to that runtime by downloading other people’s code into a local node_modules/ folder. The mental model that makes the rest of the ecosystem make sense.
§ 05 — Quick side-by-side. The comparison table for anyone who’s used another language’s runtime + package manager combo. Python’s python + pip. Ruby’s ruby + gem. Rust’s cargo. What’s similar, what’s different.
§ 06 — Worked example: a real web server. A 40-line Express.js web server built from scratch. npm init. npm install express. The actual server.js file. node server.js. The browser-loadable result. The whole arc from empty folder to running server in a single section.
§ 07 — The command cheat sheet. The twenty npm and Node commands that account for 99% of usage. npm install, npm install --save-dev, npm run, npm test, npm publish, node, node --inspect. With the gotcha for each.
§ 08 — Dependencies vs. devDependencies. The single distinction that catches every new developer. What goes in each. Why mixing them up creates production bugs that are surprisingly hard to diagnose.
§ 09 — Versioning & semver. The ^ and ~ and >= and * syntax that controls how npm resolves dependency versions. Why your project that worked yesterday breaks today (and the package-lock.json mechanism that’s supposed to prevent that).
§ 10 — The alternatives. What you’ll meet outside vanilla npm. Yarn (Facebook’s alternative, faster, better lockfile semantics). pnpm (the modern winner on speed and disk usage). Bun (the 2024–25 rewrite that bundles runtime + package manager + bundler in one binary).
§ 11 — Common gotchas. The dozen mistakes that bite new developers. node_modules checked into git. Missing .nvmrc. Mismatched node versions across team members. Forgetting --save-dev. The transitive-dependency rabbit hole.
§ 12 — Further reading. The official Node.js documentation. The handful of tutorials that get this right. The npm blog (which is more interesting than it has any right to be).
Read it
The monograph lives at its own URL with a warm-paper layout — Node-green accent, twelve sections, runnable code wherever the explanation earns it.
← Back to Autonomy