CDN Caching Rules for SSGs

Static Site Generators (SSGs) like Astro, Eleventy, Hugo, and Jekyll produce deterministic outputs. These outputs benefit from aggressive edge caching. Proper configuration reduces origin load and improves Time to First Byte (TTFB). It also stabilizes Core Web Vitals across global networks.

This guide details header strategies, CI/CD purge automation, and validation workflows. Align your deployment pipeline with Performance Optimization & Core Web Vitals for SSGs to establish measurable performance baselines.

Cache-Control Header Architecture

Deterministic caching requires separating HTML entry points from hashed static assets. Apply public, max-age=31536000, immutable to fingerprinted files. Use public, max-age=0, must-revalidate or stale-while-revalidate for HTML routes. This prevents stale content delivery while maximizing edge hit ratios.

For detailed fingerprinting mechanics, review Configuring cache-control headers for immutable assets. Asset coordination directly impacts render performance. Coordinate delivery with Image Optimization Pipelines in Astro and Font Loading Strategies for Static Sites to ensure critical resources bypass render-blocking delays.

Map your SSG output directory to the CDN configuration. Astro uses /dist/, Eleventy and Jekyll use _site/, and Hugo uses public/. Route these paths correctly to apply long-lived headers.

/assets/*
 Cache-Control: public, max-age=31536000, immutable

/*
 Cache-Control: public, max-age=0, must-revalidate

Netlify _headers configuration. Separates long-lived caching for versioned assets from short-lived validation for HTML pages.

CI/CD Cache Invalidation Workflows

Automated deployments require synchronized cache purges. Trigger CDN invalidation immediately after successful builds. Prefer tag-based or path-based invalidation over full purges. This preserves cache efficiency for unchanged routes.

Platform-specific hooks vary by provider. Consult Setting up proper cache headers on Netlify for native deployment integrations. Implement the following step in your pipeline to automate the process.

- name: Purge CDN Cache
 run: |
 curl -X POST https://api.cloudflare.com/client/v4/zones/${{ secrets.CF_ZONE }}/purge_cache \
 -H "Authorization: Bearer ${{ secrets.CF_API_TOKEN }}" \
 -H "Content-Type: application/json" \
 --data '{"purge_everything": true}'

GitHub Actions workflow. Executes a full cache purge after successful deployment to ensure fresh content delivery. Replace purge_everything with files or tags arrays for granular control in production.

Edge Caching & TTFB Optimization

Route static requests to the nearest edge node to minimize latency. Implement edge-side includes or prerendering fallbacks for dynamic personalization. When origin latency impacts delivery, leverage serverless edge functions.

Refer to Reducing TTFB with Cloudflare Workers for static assets for worker script implementations. Platform routing files also enforce cache directives at the network layer.

{
 "headers": [
 {
 "source": "/_next/static/(.*)",
 "headers": [
 { "key": "Cache-Control", "value": "public, max-age=31536000, immutable" }
 ]
 }
 ]
}

Vercel vercel.json configuration. Defines framework-specific static asset caching rules at the platform level. Adjust the source pattern to match your SSG's output directory (e.g., /assets/, /static/, or /public/).

Performance Validation & Metrics

Measure cache efficiency using response headers and synthetic monitoring. Inspect x-cache, cf-cache-status, and age values to verify edge hits. Track Largest Contentful Paint (LCP) and First Contentful Paint (FCP) improvements post-implementation.

Integrate Lighthouse CI or WebPageTest into your pipeline. Run continuous regression testing to catch cache misconfigurations early. Correlate header changes with real-user monitoring data to validate production impact.

Common Pitfalls

Over-caching HTML pages: Applying immutable headers to HTML prevents search engines and users from receiving updated content without manual cache busting.
Missing stale-while-revalidate: Omitting SWR causes synchronous cache misses, increasing TTFB during revalidation spikes.
Ignoring query parameter normalization: CDNs treat different query strings as unique URLs, fragmenting cache hit ratios and increasing origin load.

FAQ

Should HTML pages from SSGs be cached? Yes, but with short max-age and must-revalidate or stale-while-revalidate to balance freshness and performance.

How do I handle cache invalidation for incremental SSG builds? Use tag-based or path-based CDN purging triggered by CI/CD deployment hooks to invalidate only changed routes.

What is the recommended max-age for hashed static assets? 31,536,000 seconds (1 year) with the immutable directive, as content hashes guarantee uniqueness.

How can I verify if my CDN is serving cached content? Inspect response headers for x-cache: HIT, cf-cache-status: HIT, or age values greater than zero.