Caching Strategies
Get the most from Edge CDN: how caching flows from origin to edge to user, configure cache rules, and optimise hit rates.
How CDN caching works
When a user requests content, the flow is: origin → edge → user. Your origin server (VM, storage bucket, or external host) delivers the response. Edge CDN nodes sit in 2,200+ locations worldwide and cache responses closer to your users. On a cache hit, the edge serves the content directly without hitting your origin — reducing latency and offloading traffic.
The first request for a given URL triggers a fetch from origin. Subsequent requests for that URL (within the cache TTL) are served from the edge. Understanding this flow helps you tune cache behaviour for performance and cost.
Cache-Control headers and Edge
Your origin can send standard Cache-Control headers
to influence caching. Edge respects max-age,
s-maxage, and
private/no-store.
For example, Cache-Control: max-age=3600, s-maxage=86400
tells the edge to cache for 24 hours (s-maxage) even if the browser honours 1 hour (max-age).
If your origin omits or sends conflicting headers, Edge applies a default TTL. You can also override origin directives via the control panel or API — useful when you want consistent behaviour across deployments without changing application code.
Default TTLs and path-based rules
Set a default TTL for your CDN deployment in the control panel under Configuration → Caching. This applies when the origin does not send cache directives.
Path-based cache rules let you fine-tune behaviour by URL pattern. A common strategy:
- Long TTL for static assets — e.g.
/assets/*or*.js,*.css,*.woff2— 7–30 days or more - Short TTL for HTML — e.g.
/*or/*.html— 0–5 minutes for dynamic pages - No cache for dynamic content — API paths, user-specific pages — bypass cache entirely
In the control panel, add rules under Configuration → Cache Rules. The Edge CLI also supports
configuring rules — run edge cdn cache-rules --help
for syntax.
Cache bypass for dynamic content
For user dashboards, API responses, or personalised content, caching is usually wrong. Two approaches:
- Origin headers — Set
Cache-Control: no-storeorprivateon those responses. Edge will not cache them. - Path-based bypass — Add a cache rule that matches the path (e.g.
/api/*) and sets TTL to 0 or "bypass".
Use bypass sparingly — every uncached request hits your origin and increases load. Keep dynamic paths limited to what truly needs freshness.
Cache purging: when and how
Purge invalidates cached content before its TTL expires. Use it when you update a file, redeploy, or fix a mistake and need users to see the new version immediately.
When to purge: After deploying static site updates, changing assets (JS/CSS), uploading new images, or fixing incorrect content. Avoid purging entire deployments routinely — it defeats caching.
How to purge: In the control panel, go to your CDN deployment → Purging. You can purge
by URL, path prefix, or (for deployments that support it) by tag. Via CLI:
edge cdn purge <deployment-id> --url "https://yoursite.com/page".
Purging propagates across the edge network within seconds. There is no charge for purge operations within reasonable limits.
Image optimisation cache behaviour
Edge's image optimisation (resize, format conversion, quality) generates derived images on demand.
These derived images are cached separately. Each unique URL (including query params like
?w=800) is cached independently.
Set a long TTL for image paths — optimised images do not change unless the source changes. When you replace the source image, purge the relevant URLs or path to invalidate cached variants.
Monitoring cache hit rates
The control panel provides cache metrics per deployment: hit rate, miss rate, and bandwidth served from cache vs origin. High hit rates (e.g. 90%+) mean your origin is protected and users get fast responses.
Low hit rates often mean: TTLs are too short, paths are bypassing cache, or traffic is spread across many unique URLs. Review your cache rules and consider longer TTLs for static content. Use the Edge CLI or API to pull analytics for deeper analysis.