Cloudflare.Cache reference

OriginCloudRegion

Source: src/Cloudflare/Cache/OriginCloudRegion.ts

An origin cloud-region mapping of a Cloudflare zone (/zones/{zone_id}/cache/origin_cloud_regions).

The mapping tells Cloudflare which public-cloud vendor region hosts a given origin IP, letting Tiered Cache pick an upper-tier data center close to the origin for better cache-fill performance.

A mapping’s identity is its origin IP within the zone — changing ip (or zoneId) triggers a replacement, while vendor and region are patched in place. Mappings carry no ownership markers: when there is no prior state, read reports an existing mapping for the same IP as Unowned, so the engine refuses to take it over unless --adopt (or adopt(true)) is set.

OriginCloudRegion: Mapping origins to cloud regions

Map an origin IP to an AWS region

const zone = yield* Cloudflare.Zone.Zone("Site", { name: "example.com" });

yield* Cloudflare.Cache.OriginCloudRegion("ApiOrigin", {
  zoneId: zone.zoneId,
  ip: "192.0.2.10",
  vendor: "aws",
  region: "us-east-1",
});

Map several origins of the same zone

// One resource per origin IP — the IP is the mapping's identity.
yield* Cloudflare.Cache.OriginCloudRegion("UsOrigin", {
  zoneId: zone.zoneId,
  ip: "192.0.2.10",
  vendor: "gcp",
  region: "us-central1",
});
yield* Cloudflare.Cache.OriginCloudRegion("EuOrigin", {
  zoneId: zone.zoneId,
  ip: "192.0.2.20",
  vendor: "gcp",
  region: "europe-west1",
});

RegionalTieredCache

Source: src/Cloudflare/Cache/RegionalTieredCache.ts

The Regional Tiered Cache setting of a Cloudflare zone (/zones/{zone_id}/cache/regional_tiered_cache).

Regional Tiered Cache adds a regional layer between Cloudflare’s lower tiers and the upper-tier data center, so cache misses in a region only travel to the regional hub instead of crossing the globe. The setting is a zone singleton — it always exists on entitled zones (default off), so this resource never creates or deletes anything physical. Reconcile patches the setting when the observed value differs from the desired one; destroy restores the value the setting had before Alchemy first managed it (captured as initialValue).

Plan-gated: Regional Tiered Cache requires an Enterprise zone. On lower plans both reads and writes fail with Cloudflare error code 1135 (“this zone setting is not available for your plan type”), surfaced as the typed SettingUnavailableForPlan error.

Only one RegionalTieredCache resource per zone makes sense — two instances managing the same zone would fight over the singleton.

RegionalTieredCache: Managing Regional Tiered Cache

Enable Regional Tiered Cache on an Enterprise zone

const zone = yield* Cloudflare.Zone.Zone("Site", { name: "example.com" });

yield* Cloudflare.Cache.RegionalTieredCache("RegionalCache", {
  zoneId: zone.zoneId,
});

Explicitly disable Regional Tiered Cache

yield* Cloudflare.Cache.RegionalTieredCache("RegionalCache", {
  zoneId: zone.zoneId,
  enabled: false,
});

Reserve

Source: src/Cloudflare/Cache/Reserve.ts

The Cache Reserve setting of a Cloudflare zone (/zones/{zone_id}/cache/cache_reserve).

Cache Reserve is a large, persistent data store backed by R2 that serves as the ultimate upper-tier cache, dramatically reducing origin egress for cacheable content. The setting is a zone singleton — it always exists on entitled zones (default off), so this resource never creates or deletes anything physical. Reconcile patches the setting when the observed value differs from the desired one; destroy restores the value the setting had before Alchemy first managed it (captured as initialValue).

Entitlement-gated: Cache Reserve is a usage-billed add-on that must be purchased/enabled on the account. On zones without the subscription both reads and writes fail with the typed SettingUnavailableForPlan error (“this zone setting is not available for your plan type”).

Disabling Cache Reserve does not purge data already in reserve — set clearOnDelete: true to run the asynchronous Cache Reserve Clear operation on destroy (the provider polls until the clear completes).

Only one Reserve resource per zone makes sense — two instances managing the same zone would fight over the singleton.

Reserve: Managing Cache Reserve

Enable Cache Reserve on a zone

const zone = yield* Cloudflare.Zone.Zone("Site", { name: "example.com" });

yield* Cloudflare.Cache.Reserve("Reserve", {
  zoneId: zone.zoneId,
});

Clear stored data when the resource is destroyed

yield* Cloudflare.Cache.Reserve("Reserve", {
  zoneId: zone.zoneId,
  clearOnDelete: true,
});

SmartTieredCache

Source: src/Cloudflare/Cache/SmartTieredCache.ts

The Smart Tiered Cache setting of a Cloudflare zone (/zones/{zone_id}/cache/tiered_cache_smart_topology_enable).

Smart Tiered Cache dynamically selects the single best upper-tier data center for each origin, reducing requests that reach the origin. The setting is a zone singleton — it always exists on every zone (default off), so this resource never creates or deletes anything physical. Reconcile patches the setting when the observed value differs from the desired one; destroy restores the value the setting had before Alchemy first managed it (captured as initialValue).

Only one SmartTieredCache resource per zone makes sense — two instances managing the same zone would fight over the singleton.

SmartTieredCache: Managing Smart Tiered Cache

Enable Smart Tiered Cache on a zone

const zone = yield* Cloudflare.Zone.Zone("Site", { name: "example.com" });

yield* Cloudflare.Cache.SmartTieredCache("SmartCache", {
  zoneId: zone.zoneId,
});

Explicitly disable Smart Tiered Cache

yield* Cloudflare.Cache.SmartTieredCache("SmartCache", {
  zoneId: zone.zoneId,
  enabled: false,
});

Variants

Source: src/Cloudflare/Cache/Variants.ts

The Variants cache setting of a Cloudflare zone (/zones/{zone_id}/cache/variants).

Variants lets a zone cache and serve multiple content types for the same URL — e.g. serve image/webp to browsers that accept it for a .jpeg URL — which is the setting behind “Serve WebP/AVIF to supported clients” workflows (typically combined with an image-resizing origin or worker).

Unlike most zone cache settings, Variants has true create/delete semantics: the setting does not exist until it is first written (reads return a typed VariantsNotConfigured error), and DELETE removes it entirely, restoring the zone’s default behavior. This resource therefore creates the setting on first deploy and deletes it on destroy.

Only one Variants resource per zone makes sense — the setting is a zone singleton, and two instances managing the same zone would fight over it.

Variants: Managing Variants

Serve WebP for JPEG URLs

const zone = yield* Cloudflare.Zone.Zone("Site", { name: "example.com" });

yield* Cloudflare.Cache.Variants("ImageVariants", {
  zoneId: zone.zoneId,
  jpeg: ["image/webp"],
  jpg: ["image/webp"],
});

Allow WebP and AVIF for all common image extensions

yield* Cloudflare.Cache.Variants("ImageVariants", {
  zoneId: zone.zoneId,
  jpeg: ["image/webp", "image/avif"],
  jpg: ["image/webp", "image/avif"],
  png: ["image/webp", "image/avif"],
  gif: ["image/webp", "image/avif"],
});