Cloudflare Pages Edge Caching Setup

Implementing a Production-Ready Deployment & CI/CD Workflows strategy requires precise edge cache configuration. This guide details the step-by-step process for configuring Cloudflare Pages edge caching. It covers integrating cache purging into CI/CD pipelines and validating measurable performance gains. Documentation teams and frontend developers can apply these workflows immediately.

Key implementation objectives:

Define granular cache-control headers via the _headers file.
Automate cache invalidation during CI/CD deployments.
Validate cf-cache-status and TTFB metrics post-deploy.
Align caching rules with SSG asset fingerprinting.

Configure `_headers` for Static Assets

Establish deterministic caching rules that differentiate between immutable hashed assets and frequently updated HTML routes. This configuration directly impacts TTFB and origin load reduction. Apply Cache-Control: public, max-age=31536000, immutable to fingerprinted JS, CSS, and images. Set max-age=0, s-maxage=300, stale-while-revalidate=86400 for HTML routes. Use wildcard paths for framework-specific directories.

Create a _headers file in your project root. Cloudflare Pages automatically processes this file during deployment.

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

/*.html
 Cache-Control: public, max-age=0, s-maxage=300, stale-while-revalidate=86400

/*
 Cache-Control: public, max-age=86400

This syntax defines long-term immutable caching for hashed assets. It applies short TTL with background refresh for HTML. It also sets default caching for remaining files. Ensure your build process outputs fingerprinted filenames to leverage the immutable directive safely.

CI/CD Pipeline Integration & Cache Invalidation

Automate cache purging and header validation within deployment workflows. Integrating these steps into GitHub Actions for Automated SSG Builds ensures consistent cache states across environments. Trigger the Cloudflare Purge Cache API on successful production builds. Validate _headers syntax before deployment to prevent 403/500 errors. Implement conditional purging based on changed file hashes when possible.

Use the following GitHub Actions step to trigger a full zone cache purge after a successful merge to main.

- name: Purge Cloudflare Cache
 if: github.ref == 'refs/heads/main'
 run: |
 curl -X POST "https://api.cloudflare.com/client/v4/zones/${{ secrets.CF_ZONE_ID }}/purge_cache" \
 -H "Authorization: Bearer ${{ secrets.CF_API_TOKEN }}" \
 -H "Content-Type: application/json" \
 --data '{"purge_everything": true}'

Store CF_ZONE_ID and CF_API_TOKEN securely in your repository secrets. Restrict the API token to Zone Cache Purge permissions only. For granular control, replace purge_everything with a files array containing updated asset URLs.

Performance Validation & Metrics

Quantify caching efficiency using Cloudflare Analytics and HTTP header inspection. Benchmarking against Netlify vs Vercel Deployment Strategies provides context for edge network performance. Monitor cf-cache-status: HIT versus MISS ratios in the Cloudflare dashboard. Measure TTFB improvements using WebPageTest or Lighthouse CI. Track bandwidth savings and origin request reduction over rolling 30-day windows.

Verify cache headers and status directly from your terminal after deployment.

curl -s -I https://example.com/index.html | grep -E '(cf-cache-status|cache-control|age)'

A successful configuration returns cf-cache-status: HIT on subsequent requests. The age header increments until it matches your configured s-maxage or max-age value. Use the Cloudflare GraphQL Analytics API to automate TTFB and cache hit ratio reporting in your CI pipeline.

SSG-Specific Cache Alignment

Tailor caching directives to framework output structures. This ensures dynamic routes and fallback pages behave predictably across Astro, Eleventy, Hugo, and Jekyll. Map SSG output directories to cache rules. Handle client-side routing fallbacks with _redirects equivalents. Exclude build artifacts and .git from public cache. Reference Automating Eleventy deployments with Cloudflare Pages for framework-specific routing patterns.

Framework-specific considerations:

Astro: Output to dist/. Use astro build to generate fingerprinted assets. Configure _redirects for SPA fallbacks if using client-side routing.
Eleventy: Default output is _site/. Ensure HTML templates emit correct cache headers via _headers.
Hugo: Outputs to public/. Enable minify in config.toml to ensure deterministic asset hashing.
Jekyll: Outputs to _site/. Use jekyll-assets or manual fingerprinting to align with immutable caching rules.

Always deploy a _redirects file alongside _headers to handle 404 fallbacks without bypassing edge caching.

Common Pitfalls

Over-caching HTML pages with long max-age: Causes stale content delivery and forces users to hard-refresh. HTML should use short s-maxage with stale-while-revalidate.
Missing Vary: Accept-Encoding header: Prevents proper gzip/brotli compression caching. This leads to cache fragmentation and increased bandwidth usage.
Purging cache on every commit regardless of environment: Increases origin load and triggers cache warming delays. Limit purges to production merges to maintain optimal TTFB.

Frequently Asked Questions

How do I verify if Cloudflare Pages is serving cached content? Check the cf-cache-status response header. HIT indicates edge cache delivery, while MISS or DYNAMIC means the request hit the origin.

What is the recommended TTL for SSG HTML files? Set max-age=0 with s-maxage=300 and stale-while-revalidate=86400 to ensure fresh content while maintaining edge performance.

Does Cloudflare Pages automatically cache static assets? Yes, but default caching is conservative. Custom _headers files are required to implement immutable caching for fingerprinted assets and optimize TTFB.

How do I invalidate specific paths without purging the entire zone? Use the Cloudflare Purge Cache API with a files array containing exact URLs, or deploy a new build which automatically invalidates matching paths.