Cache Hit vs. Stale Dependency Resolution: Balancing Build Speed and Security in Netlify Deployments

Direct Answers

Cache invalidation should trigger on any change to package-lock.json. Netlify's build cache keys off the lock file's content hash. A hash change forces a fresh npm ci, which re-resolves the exact versions recorded. Manual edits, dependency additions, or version bumps all change the hash and invalidate the cache automatically.

Relying on cache hits is safe for reproducibility. When the lock file hash matches, the restored node_modules tree is bit-for-bit identical to the prior build. Transitive dependency versions cannot drift without a lock file change because npm ci (which Netlify runs) refuses to mutate a satisfied lock file.

The security risk is a stale lock file, not the cache. If upstream publishes a patched version within your declared ranges, package-lock.json won't update until you run npm update or delete node_modules and reinstall. The cache simply restores whatever the lock file currently pins.

How Netlify's Cache Actually Works

Netlify stores ~/.npm and node_modules under a cache key derived from sha256(package-lock.json) (or yarn.lock). On each build:

1. Compute lock file hash.
2. If a cache entry exists for that hash, restore it (cache hit).
3. Run npm ci — which sees a complete node_modules matching the lock file and exits near-instantly.
4. If no entry exists, run full npm ci and save the result (cache miss).

The 1 GB LRU cache evicts least-recently-used entries. Frequent builds keep the cache warm but never alter resolved versions.

Verification Steps You Can Add Today

1. Confirm the cache key being used

# Add as a build command before npm ci
echo \"CACHE_KEY: $(cat package-lock.json | sha256sum | cut -d' ' -f1)\"

Compare this value across deploys in the build logs. Identical hashes = identical dependency trees.

2. Fail the deploy on new high/critical vulnerabilities

# Add as a build command after npm ci
npm audit --audit-level=high --json > audit-report.json || true
# Parse and fail if new high/critical findings since last known-good baseline
# (requires a small script or Netlify plugin to persist baseline)

This validates the lock file contents, not the cache mechanism.

3. Proactive weekly audit without cache

Create a Netlify build hook (Settings → Build & deploy → Build hooks) and schedule a weekly cron (GitHub Actions, GitLab CI, or cron-job.org) that triggers it with NETLIFY_CACHE_DISABLE=1:

curl -X POST \"https://api.netlify.com/build_hooks/YOUR_HOOK_ID\" \
  -H \"Content-Type: application/json\" \
  -d '{\"env\":{\"NETLIFY_CACHE_DISABLE\":\"1\"}}'\

This runs npm ci from scratch and surfaces advisories against the current lock file.

Assumptions and Edge Cases

• Node version pinned: Assumes .nvmrc or package.json#engines.node locks the runtime. Netlify's build image updates do not invalidate the cache; a Node bump can change resolution semantics.
• Single lock file: Monorepos with multiple workspaces need separate cache keys per lock file. Netlify's default single key may restore the wrong node_modules.
• Private registry tokens: If .npmrc contains tokens, they are cached. Expired tokens can cause silent fallback to the public registry and version drift. Rotate tokens and invalidate cache on rotation.
• Corrupted cache: Rare, but npm ci --prefer-offline with a damaged local tarball cache can restore stale artifacts. Netlify isolates cache per site, reducing risk.

One Missing Diagnostic Detail

Are you using a monorepo with multiple package-lock.json files (e.g., npm workspaces, pnpm, or Yarn workspaces)? If yes, the single cache key behavior changes the recommendation — you'll need a custom cache key strategy (e.g., hash all lock files together) or separate build steps per workspace.