Build Caching on Netlify and Vercel

When Netlify or Vercel builds a static site, much of the build time is spent redoing work from the previous build: installing the same dependencies, re-processing the same images, re-parsing the same content. Both platforms cache some of this automatically, and it is easy to assume they cache all of it. They do not. Dependency caches are restored reliably; framework caches depend on whether the platform recognizes the generator and where the generator keeps its cache; custom caches — processed images, content stores, compiled MDX — are often thrown away on every build unless configured.

This guide finds out what each platform actually caches for an Astro site and a Hugo site, configures the missing caches, verifies cache hits in build logs, and measures the savings. It is part of Incremental Builds and Build Caching for SSGs. The comparison of the platforms themselves is in Netlify vs Vercel Deployment Strategies.

Prerequisites

• A site building on Netlify or Vercel with its Git integration.
• Knowledge of where the generator stores its caches (Astro: node_modules/.astro; Hugo: resources/_gen and the cache directory; Eleventy: .cache).
• Build logs with timestamps to measure each phase.

Step 1: Find Out What Is Cached

Both platforms log cache activity near the start and end of each build. A text-only change to the Astro travel blog on Netlify showed:

3:12:04 PM: Started restoring cached node modules
3:12:09 PM: Finished restoring cached node modules
3:12:09 PM: Started restoring cached build plugins
…
3:17:51 PM: Started saving node modules

No mention of node_modules/.astro, where Astro keeps its processed images and content store — it lived inside node_modules, so on Netlify it was actually restored with the node modules cache. On Vercel, the same directory was also restored, because Vercel caches node_modules including .cache-style subdirectories. The Hugo site was different: its resources/_gen directory was not cached on either platform by default, although Netlify's build image has special handling for some Hugo setups.

Step 2: Cache Hugo's Resources on Netlify

For the Hugo site, netlify-plugin-cache persists resources and Hugo's module cache between builds:

# netlify.toml
[build]
  command = "hugo --gc --minify"
  publish = "public"
[build.environment]
  HUGO_VERSION = "0.134.3"
  HUGO_CACHEDIR = "/opt/build/cache/hugo_cache"

[[plugins]]
  package = "netlify-plugin-cache"
  [plugins.inputs]
    paths = ["resources", "/opt/build/cache/hugo_cache"]

With the image cache restored, a text-only build fell from 3 min 5 s to 24 s. --gc keeps the cached directory limited to variants the current build uses, the same concern as in Hugo Image Processing Cache in CI.

Step 3: Cache Eleventy and Hugo on Vercel

Vercel has no general setting for extra cache paths, but it restores node_modules — including anything inside it. Pointing generator caches into node_modules/.cache makes them part of the restored cache:

// eleventy.config.js
const IMG_CACHE = 'node_modules/.cache/eleventy-img';
// eleventy-img outputDir and eleventy-fetch directory point here, then passthrough-copy to _site

For Hugo on Vercel, set HUGO_CACHEDIR=node_modules/.cache/hugo in the project's environment variables and configure the images cache to use :cacheDir. It feels like a workaround — and it is one — but it is the reliable way to persist arbitrary build caches on Vercel.

Step 4: Verify Cache Hits

A cache that is configured but not hit looks exactly like a missing cache. Add a line to the build output that reports what the generator reused — Astro logs how many images it generated versus reused; for Hugo, count files in resources/_gen/images before and after the build; for Eleventy Image, log cache hits in the shortcode. Keep the numbers in the build log so a regression is visible:

# before hugo runs
echo "image variants cached before build: $(find resources/_gen/images -type f 2>/dev/null | wc -l)"
hugo --gc --minify
echo "image variants after build: $(find resources/_gen/images -type f | wc -l)"

On Netlify, the first build after adding the plugin reported 0 cached variants, as expected; the second reported 5,102, and only processed the new ones.

Step 5: Know When to Clear

Caches occasionally go wrong: a generator upgrade that changes cache formats, a corrupted file, a cache that still contains output from a removed feature. Symptoms are builds that behave differently on the platform than locally. Netlify's "Clear cache and deploy site" and Vercel's redeploy without build cache give a clean build to compare. On both sites, the team added a scheduled weekly build without cache — a cron-triggered build hook on Netlify, VERCEL_FORCE_NO_BUILD_CACHE=1 on a scheduled redeploy on Vercel — which proves cold builds still work and resets any drift.

Deciding Whether to Build on the Platform at All

Configuring platform caches is worth it when the platform's Git integration is the simplest option for the team. For heavier sites, another option is to build in GitHub Actions — where caching is fully under your control with actions/cache — and upload the finished output to Netlify or Vercel with their CLIs (netlify deploy --dir, vercel deploy --prebuilt). Previews, custom domains, headers and redirects all keep working, because they are properties of the deployment, not of where it was built. The Eleventy site eventually moved to that model when its build needed a larger machine than the platform's default build image offered; the change cut its build from 44 seconds to 31 on a larger runner and removed the need for the node_modules/.cache workaround. Sites with modest builds stayed on platform builds with configured caches, which remained the least effort to operate.

Whichever model a site uses, write it down in the repository's README — where the build runs, which caches it restores, and how to clear them — so the next person debugging a slow or odd build starts from facts.

Measured Impact

Median build time for a text-only change, ten builds each:

The Astro result is worth noting: nothing needed configuring because Astro keeps its cache inside node_modules. The generators whose caches live elsewhere were the ones paying for cold builds on every deploy.

Pitfalls & Rollback

• Assuming the platform caches your generator. Check the logs and time a build with and without changes.
• Caches without garbage collection. They grow until restoring them is slow; use --gc or pruning.
• Different generator versions reading an old cache. Clear the cache after major upgrades.
• Caches that hide cold-build breakage. Run a scheduled build without cache.
• Rollback: remove the plugin or the cache path settings; builds become slower but produce the same output.

Conclusion

Netlify and Vercel restore dependencies reliably, but generator caches outside node_modules are often discarded on every build. Check the logs, persist Hugo's resources and Eleventy's cache with a Netlify plugin or by moving them under node_modules/.cache on Vercel, log how much each build reuses, and run a weekly cold build. On these sites that cut build times by 80–85% for everything except the Astro site, which was already cached by accident of where it keeps its files.

FAQ

What do Netlify and Vercel cache between builds by default?

Both restore dependency caches such as node_modules and package manager stores when the lockfile has not changed, and each caches certain framework directories they recognize. Other generator caches, such as processed images or content stores, are only cached if they live in a recognized location or are configured explicitly.

How do I cache an extra directory on Netlify?

Use a build plugin such as netlify-plugin-cache with the directories listed in netlify.toml, or the utils.cache API in a custom plugin. The directories are restored before the build and saved after it.

How do I cache an extra directory on Vercel?

Vercel caches node_modules and framework-specific directories automatically. For other directories, place the cache under node_modules/.cache, which is included in the restored cache, since Vercel has no general-purpose cache configuration for arbitrary paths.

How do I clear a bad cache?

On Netlify, trigger a deploy with Clear cache and deploy site. On Vercel, redeploy with the Use existing Build Cache option unchecked, or set the environment variable VERCEL_FORCE_NO_BUILD_CACHE to 1.

Related

• Parent: Incremental Builds and Build Caching for SSGs — caching strategy overall.
• Caching Hugo Builds in GitHub Actions — the same caches when building in Actions.
• Caching Processed Images Between Builds — the image cache in detail.
• Configuring Vercel for Hugo and Eleventy — the Vercel project setup.
• Netlify Build Hooks for Content Updates — the builds that caching speeds up.