CDN Caching Strategies Framework

Comprehensive CDN caching architecture guide covering cache invalidation strategies, multi-tier caching, cache key design, stale-while-revalidate patterns, and edge caching for high-performance web delivery.

When to Use This Skill

Choose CDN Caching Strategies when:

• Designing caching architecture for high-traffic web applications
• Implementing cache invalidation strategies for dynamic content
• Configuring Cache-Control headers for optimal browser and CDN caching
• Setting up multi-tier caching (browser → CDN edge → origin shield → origin)
• Reducing origin server load while serving fresh content

Consider alternatives when:

• Need application-level caching — use Redis or Memcached
• Need database query caching — use query-level cache layers
• Need real-time data — consider WebSockets or Server-Sent Events

Quick Start

Copy
# Activate CDN caching
claude skill activate complete-cdn-caching-strategies-framework

# Design caching architecture
claude "Design a CDN caching strategy for our e-commerce product pages"

Example: Cache-Control Strategy

Copy
// Cache-Control header strategies by content type
const cacheStrategies: Record<string, string> = {
  // Static assets (immutable with hash in filename)
  'static-hashed': 'public, max-age=31536000, immutable',

  // HTML pages (revalidate on every request)
  'html': 'public, max-age=0, s-maxage=60, stale-while-revalidate=300',

  // API responses (short cache, background revalidation)
  'api-public': 'public, s-maxage=30, stale-while-revalidate=60',

  // User-specific data (private, no CDN)
  'api-private': 'private, no-cache, no-store',

  // Images (long cache, revalidate occasionally)
  'images': 'public, max-age=86400, s-maxage=604800, stale-while-revalidate=86400',

  // Fonts (very long cache)
  'fonts': 'public, max-age=31536000, immutable',
};

function setCacheHeaders(res: Response, strategy: string): Response {
  const headers = new Headers(res.headers);
  headers.set('Cache-Control', cacheStrategies[strategy] || 'no-cache');
  headers.set('CDN-Cache-Control', cacheStrategies[strategy] || 'no-cache');
  headers.set('Vary', 'Accept-Encoding');
  return new Response(res.body, { status: res.status, headers });
}

Core Concepts

Caching Tiers

Tier	Location	TTL	Purpose
Browser Cache	User's device	Varies	Eliminate network requests
CDN Edge	Edge PoPs (300+)	30s-24h	Reduce origin requests
Origin Shield	Single PoP near origin	1-24h	Collapse cache misses
Application Cache	Origin server (Redis)	1-60min	Fast origin response
Database Cache	Query cache	5-15min	Reduce DB queries

Cache-Control Directives

Directive	Scope	Description
public	CDN + Browser	Cacheable by any cache
private	Browser only	Only browser can cache (user-specific data)
max-age=N	Browser	Browser cache duration (seconds)
s-maxage=N	CDN only	CDN cache duration (overrides max-age for CDN)
no-cache	Both	Must revalidate before using cached copy
no-store	Both	Never cache (sensitive data)
immutable	Both	Content will never change (hashed assets)
stale-while-revalidate=N	Both	Serve stale while fetching fresh in background
stale-if-error=N	Both	Serve stale if origin errors

Cache Invalidation Patterns

Pattern	When to Use	Mechanism
Purge by URL	Specific resource changed	CDN API purge call
Purge by Tag	Related resources changed	Surrogate-Key header + tag purge
Purge All	Major deployment or data migration	Full CDN cache flush
Versioned URLs	Static assets with content hash	/assets/main.a1b2c3.js
Short TTL + SWR	Frequently changing content	s-maxage=30, stale-while-revalidate=300

Configuration

Parameter	Description	Default
cdn_provider	CDN: cloudflare, fastly, cloudfront, vercel	cloudflare
default_ttl	Default CDN cache TTL	60s
browser_ttl	Default browser cache TTL	0 (revalidate)
origin_shield	Enable origin shield	true
vary_headers	Headers to vary cache on	["Accept-Encoding"]
cache_tags	Enable surrogate key tagging	true
stale_while_revalidate	SWR duration	300s

Best Practices

1. Use s-maxage to control CDN and max-age to control browser caching independently — Set short or zero max-age for browsers (ensuring fresh content on reload) while using longer s-maxage for CDN edge caching. This gives you CDN performance with browser freshness.

2. Always use stale-while-revalidate for non-critical content — SWR serves the cached version immediately while fetching a fresh copy in the background. Users get instant responses, and the cache stays fresh. This eliminates the latency penalty of cache misses for most requests.

3. Use content-hash URLs for all static assets — Files named main.a1b2c3.js can be cached with immutable (forever). When content changes, the filename changes, causing browsers to fetch the new version. Never use cache-busting query strings (?v=123) — some CDNs ignore query strings.

4. Implement surrogate key tagging for surgical cache invalidation — Add Surrogate-Key: product-123 category-shoes headers. When product 123 changes, purge all cached responses tagged with product-123 without flushing unrelated content.

5. Always set the Vary header correctly — If responses differ by Accept-Encoding, Accept-Language, or cookies, include those in Vary. Missing Vary headers cause CDNs to serve wrong content. Over-specifying Vary reduces cache hit rates.

Common Issues

CDN serves stale content after content updates. Implement active cache purging on content changes. Use webhook-triggered purge APIs after CMS updates. For emergencies, use Cache-Control: no-cache on the origin to force revalidation. Design the system assuming cache invalidation is eventually consistent (30-60s propagation).

Cache hit ratio is low despite proper Cache-Control headers. Check Vary header — too many vary dimensions fragment the cache. Verify query string sorting (CDNs may treat ?a=1&b=2 and ?b=2&a=1 as different URLs). Consolidate URL variations and use CDN-level URL normalization.

User-specific content leaks to other users through the CDN. Never set public on responses that contain user-specific data. Use private, no-store for authenticated API responses. Implement Vary: Cookie or Vary: Authorization if responses depend on auth state, but prefer private to avoid cache complexity.