Skip to content
Tutorials Center
My learning

Topics

Lesson 31 of 36 ยท Performance and Alternatives

Speeding Up Installs and Caching

Make installs fast: understand the package cache, offline and prefer-offline modes, CI cache keys, registry mirrors, and settings that cut install time and noise.

A slow install costs more than the minutes it takes. Developers wait on it after every branch switch, and CI pays for it on every push. Most of that time is not computation: it is network (fetching metadata and tarballs) and disk (unpacking thousands of small files). So speeding up installs means doing less of both. This lesson covers the caches each manager keeps, how to cache them in CI, offline modes, and the settings worth changing.

Commands are read-only snippets here. Two runnable stand-ins show how cache keys and content-addressed caches decide between "download" and "reuse".

Where time goes

What an install really does

Resolve Pick versions
Fetch Download tarballs
Link or extract Write files
Run scripts Native builds
1 / 2

The caches

Manager Cache location (default) Command
npm ~/.npm/_cacache (Windows: %LocalAppData%\npm-cache) npm cache verify, npm cache clean --force
Yarn Berry Per-project .yarn/cache or a global cache (enableGlobalCache) yarn cache clean
pnpm Content-addressable store, e.g. ~/.local/share/pnpm/store pnpm store path, pnpm store prune

npm's cache is itself content-addressable: entries are keyed by the integrity hash, so a tarball whose hash is already cached is never downloaded again, and a corrupted file fails its check and is refetched. The cache stores packuments (metadata) and tarballs. Because of that integrity check, npm cache clean --force is rarely the answer to a problem; npm cache verify is the gentler diagnostic.

Offline and prefer-offline

Terminal
npm ci --prefer-offline      # use the cache when possible, go online only for misses
npm ci --offline             # never touch the network; fail if something is missing
pnpm install --offline
pnpm install --prefer-offline
yarn install --immutable --immutable-cache   # Berry: fail if the cache would change

--prefer-offline is a safe default on CI after restoring a cache, because a lockfile already pinned every version and integrity: the network is needed only for entries that are absent.

Caching in CI

CI machines start empty, so restore the package cache between runs. The key should change when dependencies change and not otherwise, which means: derive it from the lockfile. A GitHub Actions example (read-only):

YAML
- uses: actions/cache@v4
  with:
    path: ~/.npm
    key: npm-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
    restore-keys: |
      npm-${{ runner.os }}-
- run: npm ci --prefer-offline

Other CI services have the same idea; actions/setup-node can also do this for you with its cache: npm (or yarn, pnpm) option. The restore-keys prefix means that when the exact key is not found, the most recent older cache is restored and only the changed packages are downloaded.

What to cache: the package manager's cache, not node_modules. Restoring node_modules directly skips linking but can reuse a stale tree, breaks across Node versions and operating systems, and is slow to compress for huge trees. (pnpm and Yarn PnP with committed cache are the exceptions: their cache is the install.)

Node.js Stand-in: derive a CI cache key and pick the restore path

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.

Content-addressed caching in a nutshell

The important idea behind all three caches is the same: name a file by the hash of its content. Then "do I have it?" is a dictionary lookup, and a cached file can never be stale or wrong. This stand-in counts how many bytes would be downloaded for a series of installs.

Node.js Stand-in: a content-addressed cache saves bytes

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.

Settings that help

  • Skip what you do not need. npm ci --omit=dev for production images; --ignore-scripts when your packages do not need native builds (and is a security win too).
  • Turn down noise: --no-audit --no-fund (or audit=false, fund=false in .npmrc) removes extra network requests on each install. Run audit as a separate CI step instead.
  • Use a nearer registry: a mirror or pull-through cache (Verdaccio, Artifactory, a cloud provider's registry) inside your network is faster than the public one and survives upstream outages.
  • Prebuilt binaries: packages with native code (sharp, esbuild, better-sqlite3) ship prebuilt downloads for common platforms. Matching your Node version and OS avoids compiling from source, which can take minutes.
  • Docker layer caching: copy package.json and the lockfile first, install, then copy the source, so the install layer is reused until dependencies change.
DOCKERFILE
COPY package.json package-lock.json ./
RUN npm ci --omit=dev
COPY . .
  • Fewer dependencies: the fastest package is the one you did not install. Check what your tree costs with npm ls --all | wc -l or the "why" commands (npm explain, yarn why, pnpm why).
  • Choose the layout: pnpm's store and links (previous lesson) are usually the fastest on repeat installs, and workspace-aware task caching (task orchestration) saves build time as well.

Measure before and after. Run the install three times (cold, warm cache, warm cache with a changed lockfile) and keep the numbers in the pull request that changes your setup.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What should a CI cache key for npm be derived from?

    The lockfile changes exactly when the dependency set changes, so hashing it gives a key that invalidates only when needed.
  2. 2. What does --prefer-offline do?

    It prefers cached data, unlike --offline which fails when something is missing.
  3. 3. Why is caching the package cache usually better than caching node_modules in CI?

    Hash-addressed cache entries are safe to reuse, while a restored node_modules may not match the lockfile or platform.
  4. 4. In a Dockerfile, why copy package.json and the lockfile before the rest of the source?

    Docker caches layers by their inputs. Source edits then do not invalidate the expensive install layer.

Summary

  • Install time is mostly network and disk; shortcuts exist for resolving (lockfile), fetching (cache), writing (store and links) and building (prebuilt binaries).
  • npm, Yarn and pnpm all keep content-addressed caches; use --prefer-offline after restoring one.
  • In CI, key the cache on the lockfile hash and cache the package cache, not node_modules.
  • Skip audit, funding messages and scripts during installs when you can; run them as separate steps.
  • Use registry mirrors, Docker layer ordering and fewer dependencies for the largest wins, and always measure.

Next: Corepack, Bun and Other Alternatives