By Flavio Copes

How the Cloudflare Pages build cache speeds up deploys, which directories it restores for each framework, and how to keep your own caches between builds.

~~~

Every time you push, Cloudflare Pages runs a fresh build from scratch. Fresh means slow: it reinstalls your dependencies and rebuilds everything, every time.

The build cache fixes part of this. It saves some directories after a build and restores them on the next one.

It’s off by default. You turn it on in the dashboard, in your Pages project’s build settings.

What it actually caches

The build cache doesn’t save your whole project. It saves two specific things.

First, your package manager’s cache, so installs are faster:

• npm caches .npm
• pnpm caches .pnpm-store
• yarn caches .cache/yarn

Second, one cache directory per framework. Cloudflare detects your framework and restores its known cache folder:

• Astro: node_modules/.astro
• Next.js: .next/cache
• Gatsby: .cache and public
• Nuxt: node_modules/.cache/nuxt

That’s the important detail. It’s an allow-list. Cloudflare only restores those exact folders, and you can’t add your own.

The gotcha that caught me

I generate an Open Graph image for every post at build time. The tool caches each image so it doesn’t redraw the ones that didn’t change.

By default it cached them in node_modules/.astro-og-canvas. That folder isn’t on Cloudflare’s list, so it got thrown away after every build. Every deploy regenerated all 1800 images.

The fix

The fix is to cache inside a folder Cloudflare keeps. For Astro, that’s node_modules/.astro.

So I pointed the cache there:

getImageOptions: (path, page) => ({
  cacheDir: './node_modules/.astro/astro-og-canvas',
  title: page.title,
})

Now the cache rides along with Astro’s own cache. After the first deploy seeds it, only new and changed posts get regenerated.

My build went from redrawing everything to redrawing almost nothing. A cold build takes about 45 seconds. With the cache warm, about 12.

The takeaway

If a tool in your build writes a cache, check where it writes it. On Cloudflare Pages, put it inside your framework’s cache folder, or it won’t survive the next deploy.

~~~

Related posts about cloudflare: