Astro Incremental Builds: Configure cacheKey Without Serving Stale Pages

Enable the flag only for cacheable static routes#

Start with the smallest configuration change:

1
import { defineConfig } from 'astro/config';
2

3
export default defineConfig({
4
  experimental: {
5
    incrementalBuild: true,
6
  },
7
});

The feature applies to static pages returned from getStaticPaths(). Give each entry a key that represents the data used to render that page:

1
export async function getStaticPaths() {
2
  const posts = await fetchPosts();
3

4
  return posts.map((post) => ({
5
    params: { slug: post.slug },
6
    props: { post },
7
    cacheKey: `${post.slug}:${post.updatedAt}`,
8
  }));
9
}

The exact key is application-specific. A content digest, source revision, or updated timestamp works only if it changes whenever the rendered result should change. A key based only on the slug tells Astro that a post is unchanged even when its title, body, or related data has changed.

For content collections, Astro documents the loader-provided digest as a convenient key:

1
const entries = await getCollection('docs');
2

3
return entries.map((entry) => ({
4
  params: { slug: entry.id },
5
  props: { entry },
6
  cacheKey: String(entry.digest),
7
}));

Persist the cache between builds#

Astro stores the incremental cache in cacheDir, which defaults to node_modules/.astro/. The output directory is cleared at the start of a build, then skipped pages are restored from that cache. A clean CI runner that does not restore the directory will still produce a correct build, but it will render every page again.

Restore the project’s .astro cache before astro build, and save it after a successful build. Scope the CI cache to the project and its dependency/configuration identity; reusing a cache from an unrelated checkout makes the result harder to explain. The cache is an optimization, not a replacement for the source files or lockfile.

The practical sequence is:

1. Restore node_modules/.astro/ before the build.
2. Run the same Astro version and configuration used by the previous build.
3. Build and inspect the output for a changed page and an unchanged page.
4. Save the cache only after the build passes.

Know what invalidates a page#

Astro hashes the page’s module dependency graph, including layouts, components, and imported files. A code change in one of those dependencies can invalidate the affected pages even when their cacheKey is unchanged. A change to Astro configuration or project dependencies invalidates the entire cache.

Middleware needs special care: the current documentation notes that middleware changes do not invalidate cached pages. If middleware can change prerendered HTML, force a full rebuild after changing it:

1
pnpm exec astro build --force

The same command is useful when you suspect the cache itself rather than the key. Do not delete all of node_modules to test a rendering cache; --force gives you a narrower comparison.

Check the limitations before enabling it in CI#

The feature is experimental and has explicit boundaries:

• build.concurrency greater than 1 disables the incremental cache and Astro renders every page.
• Server-island pages are re-rendered unless their generated key is stable; the documented ASTRO_KEY setting controls that key.
• Pages removed from getStaticPaths() have their previous output cleaned up automatically.
• Pages without a matching cacheKey are rendered on every build.

For a large content site, measure a full build and an incremental build with the same cache state. The goal is not to make the build appear faster in one local run; it is to confirm that the saved cache is restored in the deployment environment and that changed content invalidates the pages it should.

The safe mental model is a content-addressed shortcut: cacheKey describes the page data, Astro hashes the code path, and the persisted cache supplies the previous HTML. If any input is outside those boundaries, use astro build --force or include that input in the key before trusting the result.

The existing Astro content collection storage guide covers a different large-site boundary: splitting the generated data store when one file is too large. Storage size and incremental rendering are separate decisions.

FAQ#