2. Package Managers and the Supply Chain
“I have 1,400 dependencies and I’ve read none of them.”— every modern web developer, if honest
The story: eleven lines
Section titled “The story: eleven lines”In March 2016, a developer named Azer Koçulu got into a dispute with npm over a package name. In protest, he unpublished all of his packages from the registry. One of them was called left-pad. It was about eleven lines long. It padded the left side of a string.
Within hours, builds broke across the world. Babel broke. React’s build broke. Thousands of projects that had never heard of left-pad failed to install, because something they depended on depended on something that depended on it. npm took the unprecedented step of restoring the package, then changed its rules so popular packages could no longer simply vanish.
Nobody had chosen left-pad. Nobody had reviewed it. It arrived the way most of your code arrives: as a dependency of a dependency of a dependency.
That’s the lesson of this chapter in one sentence: when you type npm install, you are executing the decisions of thousands of strangers, some of whom will one day be tired, compromised or malicious. Package managers are the machinery that makes that both wonderfully productive and quietly terrifying.
What a package and a registry are
Section titled “What a package and a registry are”A package is a folder with a package.json, compressed into a tarball. A registry (npmjs.com is the default) is a big HTTP server that stores tarballs and metadata: for each package name, a list of versions, each with its dependencies, its tarball URL and its integrity hash.
When you install, the package manager:
- reads your
package.jsondependency ranges, - asks the registry for metadata about each,
- resolves a concrete version for every package in the whole tree,
- downloads tarballs (or reuses cached ones), verifying integrity hashes,
- lays them out on disk (
node_modules, or not), - runs lifecycle scripts (
preinstall,install,postinstall) — arbitrary code, from every package that declares them, - writes a lockfile recording exactly what it chose.
Step 6 deserves the bold. Hold onto it.
What package.json really does
Section titled “What package.json really does”It’s a manifest with several jobs that people blur together:
dependencies— needed at runtime by the package. For an app, the distinction from dev dependencies is mostly organizational (the bundler includes whatever you import). For a library, it’s everything consumers must install.devDependencies— needed only to build or test (TypeScript, Vite, Vitest). Consumers of a library never install them.peerDependencies— “I work with this, but you provide it.” A React component library declaresreactas a peer, so the app has one React, not two. Two Reacts in one page is a famous bug: hooks throw “invalid hook call” because they look for the dispatcher in the wrong copy.optionalDependencies— install if possible, don’t fail if not (often platform-specific binaries).scripts— named commands fornpm run.exports— the modern, explicit map of what a package exposes: which fileimport 'pkg'resolves to, separately forimportvsrequire, browser vs node. It also hides everything not listed, so consumers can’t reach into private files.type—"module"makes.jsfiles ES Modules; otherwise they’re CommonJS.engines— which Node versions it supports (advisory unless enforced).packageManager— e.g."pnpm@9.x", so tooling can use the exact package manager the repo expects.
How node_modules is laid out — four philosophies
Section titled “How node_modules is laid out — four philosophies”This sounds like trivia. It is actually the reason for a whole category of bugs.
1. Nested (npm v1–2). Each package gets its own node_modules with its own dependencies inside. Correct, simple, and catastrophic: the same package duplicated hundreds of times, paths so deep they broke Windows’ path length limit.
2. Flat / hoisted (npm v3+, Yarn classic). Lift as many packages as possible to the top-level node_modules, nest only when versions conflict. Disk use drops dramatically. But it creates two new problems:
- Phantom dependencies. Your code can
import 'debug'even though you never declared it, because something else you depend on did, and it got hoisted to the top. It works — until that something dropsdebug, and your app breaks without you changing anything. - Doppelgangers. When two versions conflict, one is hoisted and the other is duplicated, possibly many times, in nested folders. Two copies of a library means two copies of its state.
3. Content-addressable store + symlinks (pnpm). Every version of every package is stored once on your disk, in a global store, keyed by content hash. Each project’s node_modules contains only your direct dependencies, as symlinks into a hidden .pnpm folder where each package can see exactly its own declared dependencies — and nothing else. Phantom dependencies become errors, which is correct. Disk usage across many projects drops enormously, because a package used by ten projects is stored once (hard-linked).
4. Plug’n’Play (Yarn Berry). No node_modules at all. Yarn writes a .pnp.cjs file mapping each package to a location (often inside zip archives) and patches Node’s resolution to use it. Very fast and strict. The cost: tools that assume a node_modules folder on disk need workarounds, which is why many teams that tried PnP fell back to Yarn’s node_modules linker.
Bun ships a very fast installer that, by default, produces a conventional hoisted node_modules (with options for isolated, pnpm-like layouts).
Which one should you pick?
Section titled “Which one should you pick?”For new projects and monorepos: pnpm. Strict by default (no phantoms), very disk-efficient, fast, excellent workspace support, and it has taken a firm line on supply-chain safety by not running dependencies’ install scripts unless you allow them. npm is the safe default when you want zero extra tooling. Bun is compelling if you’re already using the Bun runtime. Yarn Berry is excellent and strict, but its PnP mode asks your whole toolchain to cooperate.
The wrong answer is mixing them: two lockfiles in one repo means two different dependency trees, and whichever one CI uses is the real one.
Executing packages without installing them
Section titled “Executing packages without installing them”npx create-next-app, pnpm dlx, yarn dlx, bunx all do the same thing: download a package into a temporary or cache location and run its binary, without adding it to your project.
That’s convenient and it’s also running a stranger’s code with your user’s permissions, fetched at whatever version the registry says is latest right now. Typo-squatting (npx create-nxet-app) is a real attack. Pin versions for anything you run in CI (npx some-tool@1.4.2).
Related plumbing worth knowing: when a package declares a bin, the package manager creates an executable shim in node_modules/.bin. npm run build prepends node_modules/.bin to PATH before running your script — that’s why "build": "vite build" works without a global Vite. Corepack is a small tool, shipped with some Node versions, that reads the packageManager field and runs the exact package manager version your repo expects.
Semver, deeply
Section titled “Semver, deeply”Semantic versioning says a version is MAJOR.MINOR.PATCH:
- PATCH — bug fixes, no API change.
- MINOR — new features, backwards compatible.
- MAJOR — breaking changes.
It’s a promise, made by humans, and humans are imperfect. Ranges in package.json express how much you trust that promise:
| Range | Means | Accepts |
|---|---|---|
1.2.3 |
exactly | 1.2.3 |
~1.2.3 |
patch updates | ≥1.2.3 <1.3.0 |
^1.2.3 |
minor + patch | ≥1.2.3 <2.0.0 |
^0.2.3 |
patch only | ≥0.2.3 <0.3.0 |
^0.0.3 |
exactly | 0.0.3 |
1.x |
any 1.. | ≥1.0.0 <2.0.0 |
* |
anything | anything (please don’t) |
The caret behaves differently below 1.0.0, and this trips up experienced people. Semver says that in 0.x, anything can change at any time, so ^ treats the leftmost non-zero number as the “major.” ^0.2.3 won’t accept 0.3.0, because for a 0.x package a minor bump is allowed to break you.
Prereleases (2.0.0-rc.1) are excluded from ranges unless the range itself names a prerelease of the same version, so ^1.0.0 won’t silently pull in 2.0.0-beta.
Lockfiles: what they lock and why you commit them
Section titled “Lockfiles: what they lock and why you commit them”Ranges describe what you’re willing to accept. A lockfile (package-lock.json, pnpm-lock.yaml, yarn.lock, bun.lock) records what you actually got: the exact version of every package in the entire tree, where it came from, and an integrity hash of its tarball.
Without a lockfile, two npm installs a week apart can produce different trees, because some transitive dependency published a new patch. “It works on my machine” becomes “it worked on Tuesday.” With a lockfile:
- every developer, every CI run and every production build installs the same bytes;
- a changed tarball (same version, different content) fails the integrity check;
- dependency changes show up in code review as lockfile diffs.
Commit it. For apps, always. (Library authors commit theirs for their own CI too; consumers ignore it.)
npm install reads the lockfile but may update it to satisfy package.json. npm ci (“clean install”) deletes node_modules, installs exactly what the lockfile says, and fails if the lockfile and package.json disagree. CI should always use the clean-install form (npm ci, pnpm install --frozen-lockfile, yarn install --immutable).
Lockfile merge conflicts are common and scary-looking. Don’t hand-edit. Take either side, then re-run the install so the tool regenerates a consistent file, and review the resulting diff.
The supply chain: install scripts as an attack vector
Section titled “The supply chain: install scripts as an attack vector”Back to step 6. When you install a package, every package in its tree that declares a preinstall or postinstall script gets to run arbitrary code on your machine — with access to your files, your environment variables, your SSH keys, your npm token, your cloud credentials. In CI, it runs with access to CI secrets.
There are legitimate reasons (compiling a native module, downloading a platform binary). There are also attackers who know that compromising one popular package means code execution on millions of developer laptops and CI runners.
When it goes wrong: a rogues’ gallery
Section titled “When it goes wrong: a rogues’ gallery”Told for their lessons; the details are from memory and rounded.
left-pad (2016). Availability, not malice. One unpublish broke a big chunk of the ecosystem. Lesson: the registry is infrastructure, and your build depends on its availability. npm changed its unpublish policy; serious teams added registry mirrors/caches.
event-stream (2018). A popular, unmaintained package’s author handed it over to a helpful stranger who offered to maintain it. The new maintainer added a dependency, flatmap-stream, containing an encrypted payload that only activated inside one specific Bitcoin wallet app’s build, to steal funds. It went unnoticed for weeks. Lesson: maintainer handover is a security event, and targeted payloads hide well.
ua-parser-js (2021). A very widely used user-agent parsing library (millions of weekly downloads) had its maintainer’s npm account hijacked. Malicious versions installed a cryptominer and, on Windows, a credential stealer, via install scripts. They were live for a few hours. Lesson: account security (2FA) of other people is your security, and install scripts are the delivery mechanism.
colors and faker (2022). The maintainer himself, in protest over unpaid open-source labour, published versions that printed garbage in an infinite loop (colors) or wiped the project (faker). Lesson: “trusted maintainer” is not a permanent state, and auto-accepting new versions means auto-accepting your maintainers’ moods.
polyfill.io (2024). Not npm at all, but the same lesson at the CDN layer. A once-respected polyfill service’s domain was sold to a new owner, who began serving malicious redirects to mobile users from the script that an enormous number of websites — estimates ran past a hundred thousand — loaded directly via <script src="https://cdn.polyfill.io/…">. Lesson: a third-party <script> tag is a dependency with no lockfile, no integrity hash and no review. Chapter 13 returns to this.
The 2025 npm compromises. In September 2025, a prolific maintainer of extremely popular small packages (chalk, debug and friends — together billions of weekly downloads) was phished by an email impersonating npm support. The attacker published versions containing browser-side code that swapped cryptocurrency wallet addresses in web pages. They were caught within hours, largely because the community and security vendors were watching. Days later came a different beast: a self-replicating worm nicknamed “Shai-Hulud” (after the sandworms of Dune). Its install-time payload hunted the developer’s machine and CI environment for tokens and cloud secrets — even running secret-scanning tools to find them — exfiltrated them, and then used any npm tokens it found to publish infected versions of that developer’s packages, spreading further. A second wave hit again later in the year. Lesson: the install step is now an active battlefield, and the defaults of the past decade were too trusting.
The best way to do it
Section titled “The best way to do it”A practical, layered defence, in order of value:
- Use a lockfile and clean installs in CI. Non-negotiable.
- Don’t run install scripts by default. pnpm requires you to allow-list packages that may run build scripts. With npm,
--ignore-scripts(and an explicit rebuild for the few native modules that need it) gets you most of the way. - Don’t adopt brand-new versions instantly. Most malicious versions are detected within hours to days. A “minimum release age” policy (some package managers support it directly; Renovate supports it as a setting) means you only take versions that have survived in the wild for a few days.
- Automate updates, but review them. Dependabot or Renovate opens PRs; CI runs tests; a human skims the changelog and lockfile diff. Group minor/patch updates to keep the noise down.
- Prefer fewer, better dependencies. Every dependency is a relationship. Eleven lines of
left-padis cheaper to own than to trust. - Protect publishing. If you publish packages: 2FA, short-lived tokens, and trusted publishing from CI (the registry trusts your CI’s identity instead of a long-lived secret), plus provenance attestations so consumers can verify which repo and workflow built a version.
npm auditwith judgment. It reports known vulnerabilities in your tree. Many are irrelevant (a ReDoS in a dev-only CLI). Triage by reachability and environment, not by red text.- Least privilege in CI. Install steps don’t need deploy secrets. Split jobs so the job that runs untrusted install scripts can’t see the keys to production (Chapter 3).
What you now know
Section titled “What you now know”You can explain what every important package.json field means, why hoisting creates phantom dependencies and how pnpm prevents them, why ^0.2.3 won’t take 0.3.0, what a lockfile guarantees, why CI uses clean installs, and why the install step is one of the most attacked surfaces in software. You can also defend an opinionated choice of package manager. Most teams can’t.
Self-quiz
Section titled “Self-quiz”1. What is a phantom dependency?
A package your code imports without declaring it, which only works because a hoisted layout put another package’s dependency at the top level.
2. Which versions does ^0.0.3 accept?
Only 0.0.3. The leftmost non-zero part (the patch) is treated as “major.”
3. What’s the difference between npm install and npm ci?
npm install may update the lockfile; npm ci installs exactly the lockfile from scratch and fails if it disagrees with package.json.
4. Why is a peer dependency used for React in component libraries?
So the app supplies one React; bundling a second copy breaks hooks and doubles bytes.
5. Why is a third-party script tag a supply-chain risk?
It’s code from someone else, fetched at runtime, with no lockfile, version pin or integrity check unless you add SRI. If the host changes hands or is compromised, so are you.
Exercises
Section titled “Exercises”Warm-up 1. Range reading. For ~2.4.1, ^2.4.1, ^0.4.1 and 2.x, which of 2.4.9, 2.5.0, 0.4.7, 0.5.0, 3.0.0 match?
Solution
~2.4.1: 2.4.9. ^2.4.1: 2.4.9, 2.5.0. ^0.4.1: 0.4.7. 2.x: 2.4.9, 2.5.0.
Warm-up 2. Diagnose. After upgrading an unrelated package, import debug from 'debug' fails with “module not found”. You never added debug. Explain.
Solution
It was a phantom dependency, hoisted from something else; the upgrade removed or moved it. Declare it explicitly.
Warm-up 3. Lockfile review. A PR changes one line in package.json but 900 lines in the lockfile. Is that suspicious?
Solution
Not necessarily: one direct dependency bump can pull a different transitive tree. But it’s worth skimming for unexpected new packages and registry URLs.
Lab 4. Three installs. Install the same small app with npm, then pnpm. Compare node_modules size, the folder structure, and try importing a transitive dependency directly in each.
Expected outcome
npm’s hoisted layout lets the phantom import work; pnpm’s does not. pnpm’s node_modules contains only direct deps as symlinks.
Lab 5. Lumen gets a lockfile. Convert Lumen (now on Vite) to pnpm, commit the lockfile, and add the packageManager field. Delete node_modules and do a frozen-lockfile install.
Hint
If the frozen install fails, your lockfile and package.json disagree; regenerate with a normal install and commit.
Lab 6. Find the install scripts. List every package in Lumen’s tree that declares an install script. Decide, for each, whether it needs to run.
Hint
pnpm will tell you which build scripts it blocked. With npm, search node_modules/*/package.json for "postinstall". Typical legitimate cases: esbuild/sharp-style native binaries.
Lab 7. Configure automated updates. Set up Renovate or Dependabot for Lumen with grouped minor/patch updates and a delay before adopting new versions.
Expected outcome
Weekly grouped PRs, each running CI. Majors arrive separately so you can read their changelogs.
Staff 8. Dependency policy RFC. Write a one-page policy for your team: when a new dependency is acceptable, who reviews it, how updates are adopted, and how install scripts are handled.
Model outline
Criteria (maintenance activity, size, transitive count, license, alternatives incl. “write it”); review by one other engineer for new deps; automated updates with minimum release age; install scripts blocked by default with an allow-list; quarterly prune of unused deps; incident runbook for “a dependency was compromised”.
Staff 9. Incident drill. It’s 10 a.m. and a package in your tree has been reported compromised as of 2 a.m. Write the first hour of your response.
Model answer
Check lockfiles across repos for affected versions. If present: identify which machines and CI runs installed it since 2 a.m., rotate every secret those environments could see (npm, cloud, CI tokens), pin to a known-good version, purge caches, check published artifacts built in that window, and communicate status. Lessons: was the version adopted automatically? Why could install scripts see those secrets?