From 8efdd55e0bdee42c04d35ef684e545e7b870c78d Mon Sep 17 00:00:00 2001 From: conico974 Date: Fri, 9 May 2025 20:30:11 +0200 Subject: [PATCH] docs for #655 --- pages/cloudflare/caching.mdx | 72 +++++++++++++++++++++++++++++++++++- 1 file changed, 71 insertions(+), 1 deletion(-) diff --git a/pages/cloudflare/caching.mdx b/pages/cloudflare/caching.mdx index 6ffd02c..79b0315 100644 --- a/pages/cloudflare/caching.mdx +++ b/pages/cloudflare/caching.mdx @@ -19,6 +19,9 @@ The `@opennextjs/cloudflare` caching supports rely on 3 components: You can also enable cache interception, to avoid calling the `NextServer` and thus loading the javascript associated with the page. It can slightly improve cold start performance for ISR/SSG route on cached routes. As of now, cache interception does not work with PPR and is not enabled by default. +Additionally some components uses the [Cache Api](https://developers.cloudflare.com/workers/runtime-apis/cache/) to improve the performance of these different components. +If you're planning on using On-Demand revalidation, you should also use the [Cache Purge component](#automatic-cache-purge) to automatically purge the cache when a page is revalidated. + The adapter provides several implementations for each of those components configured in `open-next.config.ts`. This guide provides guidelines for common use cases before detailing all the configuration options. @@ -156,6 +159,10 @@ For a larger site, you should use the `ShardedDOTagCache` that can handle a high "name": "NEXT_TAG_CACHE_DO_SHARDED", "class_name": "DOShardedTagCache", }, + { + "name": "NEXT_CACHE_DO_PURGE", + "class_name": "BucketCachePurge", + }, ], }, "migrations": [ @@ -165,6 +172,7 @@ For a larger site, you should use the `ShardedDOTagCache` that can handle a high "DOQueueHandler", // This is only required if you use On-demand revalidation "DOShardedTagCache", + "BucketCachePurge", ], }, ], @@ -180,14 +188,17 @@ import r2IncrementalCache from "@opennextjs/cloudflare/overrides/incremental-cac import { withRegionalCache } from "@opennextjs/cloudflare/overrides/incremental-cache/regional-cache"; import doShardedTagCache from "@opennextjs/cloudflare/overrides/tag-cache/do-sharded-tag-cache"; import doQueue from "@opennextjs/cloudflare/overrides/queue/do-queue"; +import { cachePurge } from "@opennextjs/cloudflare/overrides/cache-purge/index"; export default defineCloudflareConfig({ - incrementalCache: withRegionalCache(r2IncrementalCache, { mode: "short-lived" }), + incrementalCache: withRegionalCache(r2IncrementalCache, { mode: "long-lived" }), queue: doQueue, // This is only required if you use On-demand revalidation tagCache: doShardedTagCache({ baseShardSize: 12 }), // Disable this if you want to use PPR enableCacheInterception: true, + // you can also use the `durableObject` option to use a durable object as a cache purge + cachePurge: purgeCache({ type: "direct" }), }); ``` @@ -651,3 +662,62 @@ You can also create your own custom filter function. This function must return a + +#### Automatic Cache Purge + + + +You can only enable cache purge functionality on a zone (e.g., when using a custom domain). + + + +The cache purge component automatically clears the cache when a page is revalidated. It is only necessary if you use On-Demand revalidation along with one of the cache components that leverage the Cache API. + +This component can either call the Cache API's purge function directly or route the purge request through an intermediate durable object. Using a durable object helps buffer requests and avoid reaching API rate limits (see https://developers.cloudflare.com/cache/how-to/purge-cache/#hostname-tag-prefix-url-and-purge-everything-limits for more details). + +Cache purge are only called when you call `revalidateTag`, `revalidatePath` or `res.revalidate` in the pages router. It is not called for ISR revalidation. + +Below is an example configuration for integrating the cache purge component in your open-next.config.ts: + +```ts +import { defineCloudflareConfig } from "@opennextjs/cloudflare"; +import r2IncrementalCache from "@opennextjs/cloudflare/overrides/incremental-cache/r2-incremental-cache"; +import { withRegionalCache } from "@opennextjs/cloudflare/overrides/incremental-cache/regional-cache"; +import doShardedTagCache from "@opennextjs/cloudflare/overrides/tag-cache/do-sharded-tag-cache"; +import doQueue from "@opennextjs/cloudflare/overrides/queue/do-queue"; +import { cachePurge } from "@opennextjs/cloudflare/overrides/cache-purge/index"; + +export default defineCloudflareConfig({ + incrementalCache: withRegionalCache(r2IncrementalCache, { mode: "long-lived" }), + queue: doQueue, + // This is only required if you use On-demand revalidation + tagCache: doShardedTagCache({ baseShardSize: 12 }), + // Disable this if you want to use PPR + enableCacheInterception: true, + // you can also use the `durableObject` option to use a durable object as a cache purge + cachePurge: purgeCache({ type: "direct" }), +}); +``` + +If you want to use the durable object option, you will need to add the following binding to your `wrangler.jsonc` file: + +```jsonc +{ + "durable_objects": { + "bindings": [ + { + "name": "NEXT_CACHE_DO_PURGE", + "class_name": "BucketCachePurge", + }, + ], + }, + "migrations": [ + { + "tag": "v1", + "new_sqlite_classes": ["BucketCachePurge"], + }, + ], +} +``` + +You can customize the duration of the cache purge buffering with the `NEXT_CACHE_DO_PURGE_BUFFER_TIME_IN_SECONDS` environment variable. The default is 5 seconds. It works by buffering the purge requests for a given amount of time and then sending them all at once. This is useful to avoid hitting the API rate limits.