# How the Cloudflare Pages build cache works

> 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.

Author: [Flavio Copes](https://flaviocopes.com/about/) | Published: 2026-07-08 | Topics: [Cloudflare](https://flaviocopes.com/tags/cloudflare/) | Canonical: https://flaviocopes.com/cloudflare-pages-build-cache/

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](https://flaviocopes.com/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](https://flaviocopes.com/astro-introduction/): `node_modules/.astro`
- [Next.js](https://flaviocopes.com/nextjs/): `.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](https://flaviocopes.com/generate-og-images-astro/) 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:

```ts
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.