Edge Caching Strategies: From CDN to Workers Cache for Global SaaS

// wrangler.jsonc — configure caching rules
{
  "name": "tanstack-ship",
  "routes": [{ "pattern": "tanstackship.com/*", "zone_id": "YOUR_ZONE" }],
  "assets": {
    "bucket": "./dist/public",
    "browser_ttl": 31536000, // 1 year for assets
    "serve_single_page_app": false
  }
}

// Set cache-control headers from server functions
export const getPublicProduct = createServerFn({ method: "GET" }).handler(
  async ({ data, context }) => {
    const product = await context.env.DB.prepare(
      "SELECT * FROM products WHERE id = ? AND published = 1"
    ).bind(data.id).first()

    // Cache public product data for 5 minutes on the edge
    context.response.headers.set("Cache-Control", "public, s-maxage=300, max-age=60")

    return product
  }
)

// server/middleware/cache.ts
interface CacheOptions {
  ttl: number           // Time to live in seconds
  key: string           // Custom cache key
}

export async function withWorkerCache<T>(
  handler: () => Promise<T>,
  options: CacheOptions,
  request: Request
): Promise<T> {
  const cacheKey = new Request(`https://cache.tanstackship.com/${options.key}`, request)
  const cache = caches.default

  // Try cache first
  const cachedResponse = await cache.match(cacheKey)
  if (cachedResponse) {
    const data = await cachedResponse.json()
    console.log(`Cache HIT for ${options.key}`)
    return data as T
  }

  console.log(`Cache MISS for ${options.key}`)

  // Execute the handler
  const data = await handler()

  // Store in cache
  const response = new Response(JSON.stringify(data), {
    headers: {
      "Content-Type": "application/json",
      "Cache-Control": `public, max-age=${options.ttl}`,
    },
  })

  // Wait for cache storage (don't block the response)
  request.waitUntil?.(cache.put(cacheKey, response))

  return data
}

// Cache frequently accessed data
export const getDashboardStats = createServerFn({ method: "GET" }).handler(
  async ({}, { context }) => {
    return withWorkerCache(
      async () => {
        // Expensive query — only runs on cache miss
        const [users, revenue, subscriptions] = await Promise.all([
          context.env.DB.prepare("SELECT COUNT(*) as count FROM users").first(),
          context.env.DB.prepare("SELECT SUM(mrr) as total FROM subscriptions WHERE status = 'active'").first(),
          context.env.DB.prepare("SELECT status, COUNT(*) as count FROM subscriptions GROUP BY status").all(),
        ])
        return { users, revenue, subscriptions: subscriptions.results }
      },
      { ttl: 300, key: "dashboard/stats" },
      context.request
    )
  }
)

// Store pricing configuration in KV
await context.env.KV.put("pricing:starter", JSON.stringify({
  monthlyPrice: 29,
  features: ["basic_analytics", "email_support"],
}))

// Read from any Worker globally with ~10ms latency
const pricing = JSON.parse(
  await context.env.KV.get("pricing:starter") ?? "{}"
)

export const getAnalyticsData = createServerFn({ method: "GET" }).handler(
  async ({ data, context }: { data: { timeframe: string } }) => {
    // Serve from cache, then refresh in background
    context.response.headers.set(
      "Cache-Control",
      "public, s-maxage=60, stale-while-revalidate=86400, stale-if-error=604800"
    )

    // User sees cached data instantly
    // Worker refreshes cache in background
    const result = await context.env.DB.prepare(`
      SELECT date, pageviews, unique_visitors
      FROM analytics_summary
      WHERE date >= datetime('now', ?)
    `).bind(
      data.timeframe === "7d" ? "-7 days" : "-30 days"
    ).all()

    return result.results
  }
)

// server/admin/cache.ts
export const purgePageCache = createServerFn({ method: "POST" }).handler(
  async ({ data, context }: { data: { url: string } }) => {
    // Purge specific URL from CDN cache
    const formData = new FormData()
    formData.append("files", data.url)

    const response = await fetch(
      `https://api.cloudflare.com/client/v4/zones/${context.env.CLOUDFLARE_ZONE}/purge_cache`,
      {
        method: "POST",
        headers: {
          "Authorization": `Bearer ${context.env.CLOUDFLARE_API_TOKEN}`,
        },
        body: JSON.stringify({ files: [data.url] }),
      }
    )

    return response.ok ? { purged: true } : { purged: false }
  }
)

// Tag cache entries for granular invalidation
context.response.headers.set(
  "Cache-Tag",
  `user-${userId},org-${orgId},page-dashboard`
)

// Purge all cache entries with a specific tag
// POST /api/purge?tags=user-123

Is the data user-specific?
├── YES → Do not cache at CDN level
│   ├── Use Workers Cache API with user-specific key
│   └── TTL: 30s-5min depending on staleness tolerance
└── NO → Can benefit from CDN cache
    ├── How often does it change?
    │   ├── Never (static assets) → CDN cache 1 year
    │   ├── Rarely (pricing, config) → CDN cache 1 hour + purge on update
    │   └── Frequently (dashboard data) → CDN cache 1-5min
    └── Is stale data acceptable?
        ├── YES → stale-while-revalidate for best performance
        └── NO → Short TTL with Workers Cache API fallback

// Log and monitor cache performance
export const getCacheMetrics = createServerFn({ method: "GET" }).handler(
  async ({}, { context }) => {
    const metrics = await context.env.ANALYTICS.query({
      sql: `
        SELECT
          blob1 as cache_status,
          count() as count,
          avg(double1) as avg_latency
        FROM analytics_cache
        WHERE timestamp > now() - INTERVAL '1' HOUR
        GROUP BY blob1
      `,
    })

    return metrics.rows
  }
)