From 4a917127de4f7fde8193ceb467667ee9ea268240 Mon Sep 17 00:00:00 2001 From: James Date: Mon, 3 Feb 2025 07:32:33 +0000 Subject: [PATCH 1/7] update isr support --- pages/cloudflare/caching.mdx | 53 ++++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) diff --git a/pages/cloudflare/caching.mdx b/pages/cloudflare/caching.mdx index 356af4f..3232375 100644 --- a/pages/cloudflare/caching.mdx +++ b/pages/cloudflare/caching.mdx @@ -70,3 +70,56 @@ const config: OpenNextConfig = { export default config; ``` + +#### On-Demand Revalidation + +The tag revalidation mechanism uses a [Cloudflare D1](https://developers.cloudflare.com/d1/) adapter as its backing store for information about tags, paths, and revalidation times. + +To use on-demand revalidation, you should also follow the ISR setup steps. + +##### 1. Create a D1 database + +The binding name used in your app's worker is `NEXT_CACHE_D1`. + +```jsonc +// wrangler.json +{ + // ... + "d1_databases": [ + { + "binding": "NEXT_CACHE_D1", + "database_id": "", + "database_name": "" + } + ] +} +``` + +##### 2. Create a table for tag revalidation + +The default table name is `tags`. This can be configured by setting the `NEXT_CACHE_D1` environment variable to a string. + +Wrangler can be used to create a table with it's [execute](https://developers.cloudflare.com/d1/wrangler-commands/#d1-execute) option. Ensure that you create a table for both your local dev database and your remote database. + +```sh +wrangler d1 execute NEXT_CACHE_D1 --command "CREATE TABLE IF NOT EXISTS tags (tag TEXT NOT NULL, path TEXT NOT NULL, revalidatedAt INTEGER NOT NULL, UNIQUE(tag, path) ON CONFLICT REPLACE)" +``` + +##### 3. Configure the cache + +In your project's OpenNext config, enable the KV cache and set up a queue. The `direct` queue will send a revalidation request to a page when needed, but it will not dedupe requests. + +```ts +// open-next.config.ts +import tagCache from "@opennextjs/cloudflare/d1-tag-cache"; + +const config: OpenNextConfig = { + default: { + override: { + // ... + tagCache: () => tagCache, + }, + }, + // ... +}; +``` From 4b1004c6a98b45091007773cc28dab694471ca21 Mon Sep 17 00:00:00 2001 From: James Date: Fri, 7 Feb 2025 14:21:28 +0000 Subject: [PATCH 2/7] add warnings about direct mode --- pages/cloudflare/caching.mdx | 5 +++++ pages/cloudflare/index.mdx | 4 +++- 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/pages/cloudflare/caching.mdx b/pages/cloudflare/caching.mdx index 3232375..84d8bcb 100644 --- a/pages/cloudflare/caching.mdx +++ b/pages/cloudflare/caching.mdx @@ -71,6 +71,11 @@ const config: OpenNextConfig = { export default config; ``` + + + The `direct` mode for the queue is intended for debugging purposes and is not recommended for use in production. We are actively working on a solution that will be suitable for production. + + #### On-Demand Revalidation The tag revalidation mechanism uses a [Cloudflare D1](https://developers.cloudflare.com/d1/) adapter as its backing store for information about tags, paths, and revalidation times. diff --git a/pages/cloudflare/index.mdx b/pages/cloudflare/index.mdx index 8cdbca7..85993f7 100644 --- a/pages/cloudflare/index.mdx +++ b/pages/cloudflare/index.mdx @@ -53,10 +53,12 @@ We will update the list as we progress towards releasing 1.0. - [x] [Image optimization](https://nextjs.org/docs/app/building-your-application/optimizing/images) (you can integrate Cloudflare Images with Next.js by following [this guide](https://developers.cloudflare.com/images/transform-images/integrate-with-frameworks/)) - [x] [Partial Prerendering (PPR)](https://nextjs.org/docs/app/building-your-application/rendering/partial-prerendering) - [x] [Pages Router](https://nextjs.org/docs/pages) -- [x] [Incremental Static Regeneration (ISR)](https://nextjs.org/docs/app/building-your-application/data-fetching/incremental-static-regeneration) +- [x] [Incremental Static Regeneration (ISR)](https://nextjs.org/docs/app/building-your-application/data-fetching/incremental-static-regeneration) 1 - [ ] [Support for after](https://nextjs.org/blog/next-15-rc#executing-code-after-a-response-with-nextafter-experimental) - [ ] [Composable Caching](https://nextjs.org/blog/composable-caching) (`'use cache'`) is a Next.js 15 feature and not supported yet. +1 Only the `direct` mode is supported at the moment, and is not suitable for production. + We welcome both contributions and feedback! ### Windows support From ebb881c984c27173bd306e8a7ad0e31b0b8c048d Mon Sep 17 00:00:00 2001 From: James Date: Tue, 18 Feb 2025 20:44:11 +0000 Subject: [PATCH 3/7] add initialising the cache --- pages/cloudflare/caching.mdx | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/pages/cloudflare/caching.mdx b/pages/cloudflare/caching.mdx index 84d8bcb..d315748 100644 --- a/pages/cloudflare/caching.mdx +++ b/pages/cloudflare/caching.mdx @@ -128,3 +128,15 @@ const config: OpenNextConfig = { // ... }; ``` + +##### 4. Initialise the cache during deployments + +In order for the cache to be properly initialised with the build-time revalidation data, you need to setup a command that runs as part of your deploy step. + +OpenNext will generate an SQL file during the build that can be used to setup your D1 database. + +```sh +wrangler d1 execute NEXT_CACHE_D1 --file .open-next/cache-assets-manifest.sql +``` + +This should be run as part of each deployment to ensure that the cache is being populated with each build's initial revalidation data. From cdc7e79ad4a6cdd53434a9de528584e1354765c6 Mon Sep 17 00:00:00 2001 From: James Date: Wed, 19 Feb 2025 08:58:07 +0000 Subject: [PATCH 4/7] add cloudflare directory --- pages/cloudflare/caching.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/cloudflare/caching.mdx b/pages/cloudflare/caching.mdx index d315748..774fd62 100644 --- a/pages/cloudflare/caching.mdx +++ b/pages/cloudflare/caching.mdx @@ -136,7 +136,7 @@ In order for the cache to be properly initialised with the build-time revalidati OpenNext will generate an SQL file during the build that can be used to setup your D1 database. ```sh -wrangler d1 execute NEXT_CACHE_D1 --file .open-next/cache-assets-manifest.sql +wrangler d1 execute NEXT_CACHE_D1 --file .open-next/cloudflare/cache-assets-manifest.sql ``` This should be run as part of each deployment to ensure that the cache is being populated with each build's initial revalidation data. From 8134fa2b1c7943a6d116647e0ddfa3a28d814dcd Mon Sep 17 00:00:00 2001 From: James Date: Wed, 19 Feb 2025 10:59:15 +0000 Subject: [PATCH 5/7] update for two tables --- pages/cloudflare/caching.mdx | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/pages/cloudflare/caching.mdx b/pages/cloudflare/caching.mdx index 774fd62..2612f42 100644 --- a/pages/cloudflare/caching.mdx +++ b/pages/cloudflare/caching.mdx @@ -100,14 +100,19 @@ The binding name used in your app's worker is `NEXT_CACHE_D1`. } ``` -##### 2. Create a table for tag revalidation +##### 2. Create tables for tag revalidations -The default table name is `tags`. This can be configured by setting the `NEXT_CACHE_D1` environment variable to a string. +The D1 tag cache requires two tables; one that keeps a record of the tag/path mappings, and another that tracks revalidation times. + +For the tag mappings, the default table name is `tags`, and can be configured by setting the `NEXT_CACHE_D1_TAGS_TABLE` environment variable to a string. + +For the revalidation times, the default table name is `revalidations` and can be configured by setting the `NEXT_CACHE_D1_REVALIDATIONS_TABLE` environment variable to a string. Wrangler can be used to create a table with it's [execute](https://developers.cloudflare.com/d1/wrangler-commands/#d1-execute) option. Ensure that you create a table for both your local dev database and your remote database. ```sh -wrangler d1 execute NEXT_CACHE_D1 --command "CREATE TABLE IF NOT EXISTS tags (tag TEXT NOT NULL, path TEXT NOT NULL, revalidatedAt INTEGER NOT NULL, UNIQUE(tag, path) ON CONFLICT REPLACE)" +wrangler d1 execute NEXT_CACHE_D1 --command "CREATE TABLE IF NOT EXISTS tags (tag TEXT NOT NULL, path TEXT NOT NULL, UNIQUE(tag, path) ON CONFLICT REPLACE)" +wrangler d1 execute NEXT_CACHE_D1 --command "CREATE TABLE IF NOT EXISTS revalidations (tag TEXT NOT NULL, revalidatedAt INTEGER NOT NULL, UNIQUE(tag) ON CONFLICT REPLACE)" ``` ##### 3. Configure the cache From 7800eaeb0c41b340660c1317929766daaa752113 Mon Sep 17 00:00:00 2001 From: James Date: Thu, 20 Feb 2025 10:07:12 +0000 Subject: [PATCH 6/7] add callout about apps that only use pages router --- pages/cloudflare/caching.mdx | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/pages/cloudflare/caching.mdx b/pages/cloudflare/caching.mdx index 2612f42..3af0590 100644 --- a/pages/cloudflare/caching.mdx +++ b/pages/cloudflare/caching.mdx @@ -82,6 +82,10 @@ The tag revalidation mechanism uses a [Cloudflare D1](https://developers.cloudfl To use on-demand revalidation, you should also follow the ISR setup steps. + + If your app **only** uses the pages router, it does not need to have a tag cache and should skip this step. + + ##### 1. Create a D1 database The binding name used in your app's worker is `NEXT_CACHE_D1`. From b5dd84984150a7ce58870223f7d953f9c48d415e Mon Sep 17 00:00:00 2001 From: James Date: Tue, 25 Feb 2025 20:27:22 +0000 Subject: [PATCH 7/7] suggestions --- pages/cloudflare/caching.mdx | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/pages/cloudflare/caching.mdx b/pages/cloudflare/caching.mdx index 3af0590..759cc3b 100644 --- a/pages/cloudflare/caching.mdx +++ b/pages/cloudflare/caching.mdx @@ -40,9 +40,9 @@ The binding name used in your app's worker is `NEXT_CACHE_WORKERS_KV`. "kv_namespaces": [ { "binding": "NEXT_CACHE_WORKERS_KV", - "id": "" - } - ] + "id": "", + }, + ], } ``` @@ -78,9 +78,9 @@ export default config; #### On-Demand Revalidation -The tag revalidation mechanism uses a [Cloudflare D1](https://developers.cloudflare.com/d1/) adapter as its backing store for information about tags, paths, and revalidation times. +The tag revalidation mechanism uses a [Cloudflare D1](https://developers.cloudflare.com/d1/) database as its backing store for information about tags, paths, and revalidation times. -To use on-demand revalidation, you should also follow the ISR setup steps. +To use on-demand revalidation, you should also follow the [ISR setup steps](#incremental-static-regeneration-isr). If your app **only** uses the pages router, it does not need to have a tag cache and should skip this step. @@ -98,9 +98,9 @@ The binding name used in your app's worker is `NEXT_CACHE_D1`. { "binding": "NEXT_CACHE_D1", "database_id": "", - "database_name": "" - } - ] + "database_name": "", + }, + ], } ``` @@ -121,16 +121,20 @@ wrangler d1 execute NEXT_CACHE_D1 --command "CREATE TABLE IF NOT EXISTS revalida ##### 3. Configure the cache -In your project's OpenNext config, enable the KV cache and set up a queue. The `direct` queue will send a revalidation request to a page when needed, but it will not dedupe requests. +In your project's OpenNext config, enable the KV cache and set up a queue. The queue will send a revalidation request to a page when needed, but it will not dedupe requests. ```ts // open-next.config.ts import tagCache from "@opennextjs/cloudflare/d1-tag-cache"; +import incrementalCache from "@opennextjs/cloudflare/kv-cache"; +import memoryQueue from "@opennextjs/cloudflare/memory-queue"; const config: OpenNextConfig = { default: { override: { // ... + incrementalCache: () => incrementalCache, + queue: () => memoryQueue, tagCache: () => tagCache, }, },