Skip to content
Tutorials Center
My learning

Topics

Lesson 34 of 36 ยท Projects and Practice

Project: A Mini Dependency Resolver

Build a tiny package manager core in Node.js. Parse semver ranges, resolve a dependency tree against a fake registry, write a lockfile and lay out a hoisted node_modules.

The best way to demystify npm install is to write a small one. In this project you build the core algorithm of a package manager in plain Node.js: a registry with versions, a range matcher, a resolver that walks the tree, a lockfile writer, and a hoisting layout. It is a teaching model (the real tools handle peer dependencies, optional packages, tarballs and a thousand edge cases) but every idea in it is the one the real tools use.

Everything runs here: the registry is a plain object, so there is no network. Each block is self-contained and repeats the small helpers it needs, so you can run them in any order.

Step 1: a fake registry and semver ranges

The registry maps package names to published versions and their dependency ranges.

Node.js Registry and range matching

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

maxSatisfying is the heart of resolution: of all published versions, choose the highest one that satisfies the range. That is why ^6.10.0 today gives 6.14.0 and next year might give something newer, and why a lockfile exists.

Step 2: walk the tree

Resolution is a graph walk. Start from the root's requested dependencies, pick a version for each, then resolve that version's dependencies, and so on. Two things to track: avoid infinite loops on cycles, and remember what was already decided.

flowchart TD
  app --> express
  app --> chalk
  express -->|"^6.13.0"| qs
  express -->|"2.0.0"| ms200["ms 2.0.0"]
  chalk -->|"^2.1.0"| ms213["ms 2.1.3"]

Two requests for ms with incompatible ranges produce two different versions in the tree.

Node.js Resolve the full tree

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Notice that ms appears twice, once at 2.0.0 (express pins it exactly) and once at 2.1.3 (chalk accepts anything compatible with 2.1). That duplication is exactly what a hoisted layout has to represent.

Step 3: write a lockfile

A lockfile is the resolved graph saved with exact versions. Add an integrity per package (here a hash of the name and version, standing in for the real tarball hash) so that the structure resembles a real lockfile.

Node.js Generate a lockfile and re-install from it

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

What matters: after the lockfile exists, installFromLock needs no version choosing. That is why npm ci is fast and reproducible, even if the registry later publishes [email protected].

Step 4: lay out node_modules with hoisting

Now turn the graph into folders. The algorithm places every package at the top level if no other version of that name is already there, and nests it under its parent otherwise. Real npm uses a smarter order, but the idea is the same.

Node.js Hoist the tree into a node_modules layout

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

You should see [email protected] hoisted to the top (it was placed first through express) and [email protected] nested inside chalk, which needs the newer one. Any copy shared by several parents is stored once. Phantom dependencies are visible too: your app could require('qs') because it sits at the top, even though qs is not in its own package.json (see node_modules layouts).

Step 5: audit your own tree

Because you own the data, adding an audit is a few lines. Use the lockfile's keys against an advisory list (compare with npm audit).

Node.js Audit and explain (why is this installed?)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

What the real tools add

Your mini version The real tool
Highest matching version only Full semver (pre-releases, `
Dependencies only Dev, optional and peer dependencies, overrides, workspaces
A fake registry object HTTP requests, caching, retries, integrity checks, signatures
No unpacking Tarball extraction or store + hard links, then install scripts
Simple hoist order Deduplication passes, --legacy-peer-deps behaviour, conflict reports

Extensions to try: support >= and || ranges, add devDependencies with an --omit=dev option, report peer-dependency conflicts, or make the layout pnpm-style (store keyed by name@version plus symlinks to direct dependencies only).

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How does a resolver choose the version for the range ^6.10.0?

    Resolvers pick the highest version that satisfies the range (unless a lockfile already fixed one).
  2. 2. Why can a tree contain two versions of ms?

    An exact 2.0.0 and a ^2.1.0 request cannot share one copy, so both versions are installed.
  3. 3. What does installing from a lockfile skip?

    The lockfile already holds the result of resolution, so the install only fetches and places those exact packages.
  4. 4. In the hoisting step, why was [email protected] nested inside chalk?

    The top-level name was taken by [email protected], so the conflicting version had to stay under its parent.

Summary

  • A resolver picks the highest matching version for each range, walks the graph and memoizes decisions to survive cycles.
  • A lockfile is the saved result of resolution, which is why locked installs need no version selection and are reproducible.
  • Hoisting places packages as high as conflicts allow, which saves space and creates phantom dependencies.
  • Audit and "why" are simple graph queries over the resolved tree.

Next: Project: A Monorepo Release Pipeline