docs: prefer native Workers Caching over legacy cloudflareCache() by scottbuscemi · Pull Request #2277 · emdash-cms/emdash

scottbuscemi · 2026-07-29T21:00:06Z

What does this PR do?

Clears up a confusion trap: demos/cloudflare and cloudflareCache() from @emdash-cms/cloudflare looked like the canonical edge-cache setup, but they use the legacy Cache API + zone REST purge path (CF_ZONE_ID / CF_CACHE_PURGE_TOKEN). EmDash deploy docs already describe native Workers Caching ("cache": { "enabled": true }) as the preferred approach.

This PR aligns the demo and docs with that preferred path and marks the EmDash helper as legacy so agents/humans stop copying the wrong pattern.

Changes

demos/cloudflare: switch to cacheCloudflare() from @astrojs/cloudflare/cache; add "cache": { "enabled": true } to wrangler; README documents preferred vs legacy
Deploy docs (Workers Cache): full preferred setup (wrangler + cacheCloudflare + cache.purge()), comparison table vs legacy cloudflareCache(), note that object cache (kvCache) is a separate layer
cloudflareCache() JSDoc / export comment: @deprecated guidance pointing at native Workers Caching

No runtime behavior change for existing sites that already use cloudflareCache().

Closes #

Type of change

Checklist

I have read CONTRIBUTING.md
pnpm typecheck passes
pnpm lint passes
pnpm test passes (or targeted tests for my change)
pnpm format has been run
I have added/updated tests for my changes (if applicable)
User-visible strings in the admin UI are wrapped for translation (if applicable). Do not include messages.po changes except in translation PRs — a workflow extracts catalogs on merge to main.
I have added a changeset (if this PR changes a published package)
New features link to an approved Discussion: n/a (docs)

AI-generated code disclosure

This PR includes AI-generated code — model/tool: opencode + xAI grok-4.5

Screenshots / test output

n/a — docs + demo config comments only.

Try this PR

Open a fresh playground →

A full working EmDash site, deployed from this branch. Each visit gets its own session-scoped sandbox: no login needed and no shared state. Try the admin, edit content, hit the public site.

_{Tracks docs/clarify-workers-cache. Updated automatically when the playground redeploys.}

The Cloudflare demo and cloudflareCache() JSDoc pointed agents and humans at the Cache API + zone REST purge path (CF_ZONE_ID tokens). Point demos/cloudflare and deploy docs at wrangler cache.enabled + cacheCloudflare() / cache.purge() instead, and mark the EmDash helper as legacy.

changeset-bot · 2026-07-29T21:00:11Z

🦋 Changeset detected

Latest commit: 85973e6

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 17 packages

Name	Type
@emdash-cms/cloudflare	Patch
@emdash-cms/fixture-perf-site	Patch
@emdash-cms/perf-demo-site	Patch
@emdash-cms/cache-demo-site	Patch
@emdash-cms/do-demo-site	Patch
@emdash-cms/do-solo-demo-site	Patch
emdash	Patch
@emdash-cms/admin	Patch
@emdash-cms/auth	Patch
@emdash-cms/blocks	Patch
@emdash-cms/gutenberg-to-portable-text	Patch
@emdash-cms/x402	Patch
create-emdash	Patch
@emdash-cms/sandbox-workerd	Patch
@emdash-cms/plugin-mcp-smoke	Patch
@emdash-cms/auth-atproto	Patch
@emdash-cms/plugin-embeds	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

cloudflare-workers-and-pages · 2026-07-29T21:00:59Z

Deploying with Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Updated (UTC)
✅ Deployment successful! View logs	emdash-demo-cache	`85973e6`	Jul 29 2026, 09:08 PM

cloudflare-workers-and-pages · 2026-07-29T21:01:00Z

Deploying with Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Updated (UTC)
✅ Deployment successful! View logs	emdash-playground	`85973e6`	Jul 29 2026, 09:09 PM

@deprecated

JSDoc @deprecated alone is easy to miss; emit a one-time console.warn at config time pointing at cacheCloudflare() + wrangler cache.enabled.

pkg-pr-new · 2026-07-29T21:05:43Z

Open in StackBlitz

@emdash-cms/admin

npm i https://pkg.pr.new/@emdash-cms/admin@2277

@emdash-cms/auth

npm i https://pkg.pr.new/@emdash-cms/auth@2277

@emdash-cms/auth-atproto

npm i https://pkg.pr.new/@emdash-cms/auth-atproto@2277

@emdash-cms/blocks

npm i https://pkg.pr.new/@emdash-cms/blocks@2277

@emdash-cms/cloudflare

npm i https://pkg.pr.new/@emdash-cms/cloudflare@2277

@emdash-cms/contentful-to-portable-text

npm i https://pkg.pr.new/@emdash-cms/contentful-to-portable-text@2277

emdash

npm i https://pkg.pr.new/emdash@2277

create-emdash

npm i https://pkg.pr.new/create-emdash@2277

@emdash-cms/gutenberg-to-portable-text

npm i https://pkg.pr.new/@emdash-cms/gutenberg-to-portable-text@2277

@emdash-cms/plugin-cli

npm i https://pkg.pr.new/@emdash-cms/plugin-cli@2277

@emdash-cms/plugin-types

npm i https://pkg.pr.new/@emdash-cms/plugin-types@2277

@emdash-cms/registry-client

npm i https://pkg.pr.new/@emdash-cms/registry-client@2277

@emdash-cms/registry-lexicons

npm i https://pkg.pr.new/@emdash-cms/registry-lexicons@2277

@emdash-cms/registry-verification

npm i https://pkg.pr.new/@emdash-cms/registry-verification@2277

@emdash-cms/sandbox-workerd

npm i https://pkg.pr.new/@emdash-cms/sandbox-workerd@2277

@emdash-cms/x402

npm i https://pkg.pr.new/@emdash-cms/x402@2277

@emdash-cms/plugin-ai-moderation

npm i https://pkg.pr.new/@emdash-cms/plugin-ai-moderation@2277

@emdash-cms/plugin-atproto

npm i https://pkg.pr.new/@emdash-cms/plugin-atproto@2277

@emdash-cms/plugin-audit-log

npm i https://pkg.pr.new/@emdash-cms/plugin-audit-log@2277

@emdash-cms/plugin-color

npm i https://pkg.pr.new/@emdash-cms/plugin-color@2277

@emdash-cms/plugin-embeds

npm i https://pkg.pr.new/@emdash-cms/plugin-embeds@2277

@emdash-cms/plugin-field-kit

npm i https://pkg.pr.new/@emdash-cms/plugin-field-kit@2277

@emdash-cms/plugin-forms

npm i https://pkg.pr.new/@emdash-cms/plugin-forms@2277

@emdash-cms/plugin-webhook-notifier

npm i https://pkg.pr.new/@emdash-cms/plugin-webhook-notifier@2277

commit: 85973e6

cloudflare-workers-and-pages · 2026-07-29T21:05:51Z

Deploying with Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Updated (UTC)
✅ Deployment successful! View logs	emdash-demo-do	`85973e6`	Jul 29 2026, 09:13 PM

github-actions · 2026-07-31T00:51:56Z

Overlapping PRs

This PR modifies files that are also changed by other open PRs:

feat: AI Search plugin with indexing, search modal, and demo site #633 (3 shared files)

This may cause merge conflicts or duplicated work. A maintainer will coordinate.

emdashbot

The approach is right: redirecting new sites toward native Cloudflare Workers Caching and explicitly deprecating the legacy cloudflareCache() helper is the correct fix for the confusion trap described. The demo, deploy docs, and helper JSDoc/changeset are aligned with the existing infra/cache-demo setup, and the @astrojs/cloudflare catalog versions already support cacheCloudflare() and Astro 7.

I checked the diff against the checked-out files, AGENTS.md, and the repo conventions. The docs and demo config changes look correct. One AGENTS.md convention issue slipped into the code change: the one-time deprecation warning uses a module-scope let singleton instead of the repo’s globalThis + Symbol.for pattern for shared state. That can produce duplicate warnings if Vite duplicates the module across chunks.

One note: the PR description says “no runtime behavior change,” but the new console.warn in cloudflareCache() is a small config-time behavior change (the changeset correctly captures it). Not a code bug, but worth aligning the description.

emdashbot · 2026-07-31T16:40:35Z


 export type { CloudflareCacheConfig };

+let deprecationWarned = false;


[needs fixing] New module-scope mutable state is introduced to deduplicate the deprecation warning.

AGENTS.md requires module-scope singletons to live on globalThis via a Symbol.for key, because Vite/Astro can duplicate modules across SSR chunks, turning a plain let into multiple independent variables (see packages/core/src/request-cache.ts and packages/core/src/request-context.ts). The same risk applies here: if this module is evaluated more than once, existing sites can see the warning multiple times.

Store the flag on globalThis instead:

Suggested change

let deprecationWarned = false;

const DEPRECATION_WARNED_KEY = Symbol.for(

"@emdash-cms/cloudflare/cloudflareCache:deprecation-warned",

);

const globalStore = globalThis as Record<symbol, boolean | undefined>;

// eslint-disable-next-line typescript/no-unsafe-type-assertion -- globalThis

Then update the if (!deprecationWarned) { deprecationWarned = true; ... } block to test and set globalStore[DEPRECATION_WARNED_KEY]. That preserves the existing one-time behavior while following the repo’s singleton-state convention.

github-actions Bot added area/cloudflare area/docs size/M labels Jul 29, 2026

style: format

3791fec

github-actions Bot added the review/needs-review No maintainer or bot review yet label Jul 29, 2026

chore(cloudflare): warn once when cloudflareCache() is used

85973e6

JSDoc @deprecated alone is easy to miss; emit a one-time console.warn at config time pointing at cacheCloudflare() + wrangler cache.enabled.

This was referenced Jul 29, 2026

feat: cache purge API (object cache + native Workers Caching) #2275

Merged

feat: cache purge API (object cache + native Workers Caching) #2297

Open

github-actions Bot added the overlap label Jul 31, 2026

khoinguyenpham04 added the bot:review Trigger an emdashbot code review on this PR label Jul 31, 2026

emdashbot Bot reviewed Jul 31, 2026

View reviewed changes

emdashbot Bot removed the bot:review Trigger an emdashbot code review on this PR label Jul 31, 2026

github-actions Bot added review/awaiting-author Reviewed; waiting on the author to respond and removed review/needs-review No maintainer or bot review yet labels Jul 31, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs: prefer native Workers Caching over legacy cloudflareCache() - #2277

docs: prefer native Workers Caching over legacy cloudflareCache()#2277
scottbuscemi wants to merge 3 commits into
mainfrom
docs/clarify-workers-cache

scottbuscemi commented Jul 29, 2026 •

edited by github-actions Bot

Loading

Uh oh!

changeset-bot Bot commented Jul 29, 2026 •

edited

Loading

Uh oh!

cloudflare-workers-and-pages Bot commented Jul 29, 2026 •

edited

Loading

Uh oh!

cloudflare-workers-and-pages Bot commented Jul 29, 2026 •

edited

Loading

Uh oh!

pkg-pr-new Bot commented Jul 29, 2026

Uh oh!

cloudflare-workers-and-pages Bot commented Jul 29, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jul 31, 2026

Uh oh!

emdashbot Bot left a comment

Uh oh!

emdashbot Bot Jul 31, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants


		export type { CloudflareCacheConfig };

		let deprecationWarned = false;

-let deprecationWarned = false;
+const DEPRECATION_WARNED_KEY = Symbol.for(
+	"@emdash-cms/cloudflare/cloudflareCache:deprecation-warned",
+);
+const globalStore = globalThis as Record<symbol, boolean | undefined>;
+// eslint-disable-next-line typescript/no-unsafe-type-assertion -- globalThis

Uh oh!

Conversation

scottbuscemi commented Jul 29, 2026 • edited by github-actions Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What does this PR do?

Changes

Type of change

Checklist

AI-generated code disclosure

Screenshots / test output

Try this PR

Uh oh!

changeset-bot Bot commented Jul 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

cloudflare-workers-and-pages Bot commented Jul 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying with Cloudflare Workers

Uh oh!

cloudflare-workers-and-pages Bot commented Jul 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying with Cloudflare Workers

Uh oh!

pkg-pr-new Bot commented Jul 29, 2026

Uh oh!

cloudflare-workers-and-pages Bot commented Jul 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying with Cloudflare Workers

Uh oh!

github-actions Bot commented Jul 31, 2026

Overlapping PRs

Uh oh!

emdashbot Bot left a comment

Choose a reason for hiding this comment

Uh oh!

emdashbot Bot Jul 31, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

scottbuscemi commented Jul 29, 2026 •

edited by github-actions Bot

Loading

changeset-bot Bot commented Jul 29, 2026 •

edited

Loading

cloudflare-workers-and-pages Bot commented Jul 29, 2026 •

edited

Loading

cloudflare-workers-and-pages Bot commented Jul 29, 2026 •

edited

Loading

cloudflare-workers-and-pages Bot commented Jul 29, 2026 •

edited

Loading