Cloudflare Workers Cache

npm install -D wrangler@latest
npx wrangler --version   # 4.69.0 or newer

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "my-app",
  // instead of ".open-next/worker.js": the wrapper sets the cache headers
  "main": "./worker-entry.mjs",
  "compatibility_date": "2026-07-01",
  "compatibility_flags": ["nodejs_compat"],
  "assets": { "directory": ".open-next/assets", "binding": "ASSETS" },

  // Workers Cache: Cloudflare answers from the cache before the worker runs
  "cache": { "enabled": true },

  // The cache key has no host: *.workers.dev would share (and fill) the same cache
  "workers_dev": false
}

// worker-entry.mjs - cache policy for Workers Cache in front of an OpenNext (Next.js) worker.
// Workers Cache answers BEFORE this code runs. This file only decides, through response
// headers, what the edge may store. Anything not explicitly allowed gets no-store.
import openNextWorker from "./.open-next/worker.js";
// export { DOQueueHandler } from "./.open-next/worker.js"; // only if you use the DO queue

const SITE_HOST = "www.example.com"; // the only host whose pages may be stored
const NEVER_CACHE = ["/api/"];        // path prefixes that are never stored

// Edge: 7 days fresh, then 1 more day stale-while-revalidate / stale-if-error.
// Use max-age, not s-maxage: s-maxage and must-revalidate switch stale-while-revalidate off.
const EDGE_PAGE_CC = "max-age=604800, stale-while-revalidate=86400, stale-if-error=86400";
// Browser: 10 minutes. The edge copy can be purged at any time, the browser copy cannot.
const CLIENT_PAGE_CC = "public, max-age=600";
const NO_STORE = "no-store";

// Edge-only header: highest precedence, stripped before the response reaches the browser.
const EDGE_CC = "Cloudflare-CDN-Cache-Control";

// Headers the Next.js router sends with RSC requests (client-side navigation, prefetch).
const ROUTER_HEADERS = ["rsc", "next-router-state-tree", "next-router-prefetch", "next-router-segment-prefetch", "next-url"];

/* ---------- canonical variant guard ----------
 * The cache key is path + query only. If an RSC payload is ever stored under a page URL,
 * every visitor gets raw RSC instead of HTML until the entry expires. So only the response
 * a normal visitor expects under that URL may be stored:
 *   HTML: no _rsc parameter and no router headers,
 *   RSC:  "RSC: 1" and _rsc equal to the hash Next.js derives from the router headers
 *         (next/dist/shared/lib/router/utils/cache-busting-search-param.js).
 * If Next.js ever changes the formula, RSC simply stops being cached (fail-safe).
 */
function djb2(str) {
  let hash = 5381;
  for (let i = 0; i < str.length; i++) hash = ((hash << 5) + hash + str.charCodeAt(i)) & 0xffffffff;
  return hash >>> 0;
}

function expectedRscParam(req) {
  const h = req.headers;
  const p = h.get("next-router-prefetch");
  const prefetch = p === "1" || p === "2" ? p : undefined;
  const segment = h.get("next-router-segment-prefetch") || undefined;
  const tree = h.get("next-router-state-tree") ?? undefined;
  const nextUrl = h.get("next-url") ?? undefined;
  if ([prefetch, segment, tree, nextUrl].every((v) => v === undefined)) return "";
  return djb2([prefetch || "0", segment || "0", tree || "0", nextUrl || "0"].join(",")).toString(36).slice(0, 5);
}

function isCanonicalPage(req, url, type) {
  const rsc = url.searchParams.get("_rsc"); // null = parameter missing
  if (type.startsWith("text/html")) {
    return rsc === null && !ROUTER_HEADERS.some((name) => req.headers.has(name));
  }
  if (type.startsWith("text/x-component")) {
    return req.headers.get("rsc") === "1" && rsc !== null && rsc === expectedRscParam(req);
  }
  return false;
}

/* ---------- request passed to Next.js on a MISS ----------
 * The cache key ignores cookies and Authorization, so always render the anonymous variant.
 * Conditional headers are dropped so the origin returns a full 200 for the edge to store
 * (the edge answers If-None-Match with 304 by itself). Router headers stay: Next.js needs
 * them to build the right RSC payload.
 */
function upstreamRequest(request, url) {
  if (request.method !== "GET" || NEVER_CACHE.some((p) => url.pathname.startsWith(p))) return request;
  const h = new Headers(request.headers);
  for (const name of ["Cookie", "Authorization", "If-None-Match", "If-Modified-Since"]) h.delete(name);
  return new Request(request, { headers: h });
}

/* ---------- response headers = cache policy ---------- */

function noStore(h) {
  h.set(EDGE_CC, NO_STORE);
  h.set("Cache-Control", NO_STORE); // also stops other shared caches from keeping Next's s-maxage
}

// Next.js on Workers returns uncompressed bodies and Cloudflare compresses at the edge,
// so Vary: Accept-Encoding would only split the cache into identical variants.
function dropAcceptEncodingVary(h) {
  if (h.has("Content-Encoding")) return;
  const vary = (h.get("Vary") || "")
    .split(",")
    .map((v) => v.trim())
    .filter((v) => v && v.toLowerCase() !== "accept-encoding");
  if (vary.length) h.set("Vary", vary.join(", "));
  else h.delete("Vary");
}

function applyCachePolicy(request, url, resp) {
  const out = new Response(resp.body, resp); // mutable copy
  const h = out.headers;
  const type = (h.get("Content-Type") || "").toLowerCase();
  const isPage = type.startsWith("text/html") || type.startsWith("text/x-component");
  const cacheableRequest =
    request.method === "GET" &&
    url.hostname === SITE_HOST &&
    !NEVER_CACHE.some((p) => url.pathname.startsWith(p));

  if (isPage) {
    const originCc = (h.get("Cache-Control") || "").toLowerCase();
    const store =
      cacheableRequest &&
      out.status === 200 &&
      !h.has("Set-Cookie") &&
      !originCc.includes("private") &&
      !originCc.includes("no-store") &&
      isCanonicalPage(request, url, type);

    if (!store) {
      noStore(h);
      return out;
    }
    h.set(EDGE_CC, EDGE_PAGE_CC);
    h.set("Cache-Control", CLIENT_PAGE_CC);
    h.set("Cache-Tag", type.startsWith("text/html") ? "html" : "rsc"); // for targeted purge, not sent to the browser
    dropAcceptEncodingVary(h);
    return out;
  }

  // Everything else (API, sitemaps, redirects, errors). Without an explicit Cache-Control,
  // Workers Cache applies heuristic TTLs (200 for 2 h, 301 for 20 min, 404 for 3 min).
  if (!cacheableRequest || out.status >= 400 || !h.has("Cache-Control")) noStore(h);
  return out;
}

/* ---------- POST /__cache-purge (token in CACHE_PURGE_TOKEN) ---------- */

async function sha256(text) {
  return new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(text)));
}

async function tokenMatches(request, expected) {
  const auth = request.headers.get("Authorization") || "";
  const given = auth.startsWith("Bearer ") ? auth.slice(7) : "";
  // Hash both sides first: equal lengths, so the comparison runs in constant time.
  const [a, b] = await Promise.all([sha256(given), sha256(expected)]);
  return crypto.subtle.timingSafeEqual(a, b);
}

async function handlePurge(request, env, ctx) {
  const headers = { "Cache-Control": NO_STORE, [EDGE_CC]: NO_STORE };
  if (!env.CACHE_PURGE_TOKEN || request.method !== "POST") return new Response("Not Found", { status: 404, headers });
  if (!(await tokenMatches(request, env.CACHE_PURGE_TOKEN))) return new Response("Unauthorized", { status: 401, headers });

  const body = await request.json().catch(() => ({}));
  const scope = {};
  if (Array.isArray(body.tags) && body.tags.length) scope.tags = body.tags;
  if (Array.isArray(body.pathPrefixes) && body.pathPrefixes.length) scope.pathPrefixes = body.pathPrefixes;

  const result = await ctx.cache.purge(Object.keys(scope).length ? scope : { purgeEverything: true });
  return Response.json(result, { status: result.success ? 200 : 500, headers });
}

/* ---------- entry ---------- */

export default {
  async fetch(request, env, ctx) {
    const url = new URL(request.url);
    if (url.pathname === "/__cache-purge") return handlePurge(request, env, ctx);

    const resp = await openNextWorker.fetch(upstreamRequest(request, url), env, ctx);
    return applyCachePolicy(request, url, resp);
  },
};

# generate a random token into .env (.env must be in .gitignore)
echo "CACHE_PURGE_TOKEN=$(openssl rand -hex 32)" >> .env

# store the same value as a worker secret
grep '^CACHE_PURGE_TOKEN=' .env | cut -d= -f2 | npx wrangler secret put CACHE_PURGE_TOKEN

npx opennextjs-cloudflare build
npx opennextjs-cloudflare deploy