Skip to content

Commit e133dbb

Browse files
vicbconico974james-elicx
authored
[Cloudflare] Update docs for 1.0.0-beta.0 (#118)
Co-authored-by: conico974 <nicodorseuil@yahoo.fr> Co-authored-by: James <james@eli.cx>
1 parent 68337d8 commit e133dbb

File tree

11 files changed

+861
-152
lines changed

11 files changed

+861
-152
lines changed

‎pages/cloudflare/_meta.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,6 @@
77
"examples": "",
88
"community": "Community projects",
99
"troubleshooting": "",
10-
"migrate-from-0.5-to-0.6": "Migrate from 0.5 to 0.6",
10+
"migrate-from-0.6-to-1.0.0-beta": "Migrate from 0.6 to 1.0.0-beta",
1111
"former-releases": "Former releases"
1212
}

‎pages/cloudflare/caching.mdx‎

Lines changed: 83 additions & 141 deletions
Original file line numberDiff line numberDiff line change
@@ -21,28 +21,30 @@ There are two storage options to use for the incremental cache.
2121
reflected globally, when using the default TTL of 60 seconds.
2222
</Callout>
2323

24-
<Tabs items={["Workers KV", "R2 Object Storage"]}>
24+
<Tabs items={["R2 Object Storage", "Workers KV"]}>
2525
<Tabs.Tab>
26-
##### 1. Create a KV namespace
26+
27+
##### 1. Create an R2 Bucket
2728

2829
```
29-
npx wrangler@latest kv namespace create <YOUR_NAMESPACE_NAME>
30+
npx wrangler@latest r2 bucket create <YOUR_BUCKET_NAME>
3031
```
3132

32-
##### 2. Add the KV namespace and Service Binding to your Worker
33+
##### 2. Add the R2 Bucket and Service Binding to your Worker
3334

34-
The binding name used in your app's worker is `NEXT_INC_CACHE_KV`.
35-
The `WORKER_SELF_REFERENCE` service binding should be a self reference to your worker where `<WORKER_NAME>` is the name in your wrangler configuration file.
35+
The binding name used in your app's worker is `NEXT_INC_CACHE_R2_BUCKET`. The service binding should be a self reference to your worker where `<WORKER_NAME>` is the name in your wrangler configuration file.
36+
37+
The prefix used by the R2 bucket can be configured with the `NEXT_INC_CACHE_R2_PREFIX` environment variable, and defaults to `incremental-cache`.
3638

3739
```jsonc
3840
// wrangler.jsonc
3941
{
4042
// ...
4143
"name": "<WORKER_NAME>",
42-
"kv_namespaces": [
44+
"r2_buckets": [
4345
{
44-
"binding": "NEXT_INC_CACHE_KV",
45-
"id": "<BINDING_ID>",
46+
"binding": "NEXT_INC_CACHE_R2_BUCKET",
47+
"bucket_name": "<BUCKET_NAME>",
4648
},
4749
],
4850
"services": [
@@ -56,46 +58,62 @@ The `WORKER_SELF_REFERENCE` service binding should be a self reference to your w
5658

5759
##### 3. Configure the cache
5860

59-
In your project's OpenNext config, enable the KV cache.
61+
In your project's OpenNext config, enable the R2 cache.
62+
63+
You can optionally setup a regional cache to use with the R2 incremental cache. This will enable faster retrieval of cache entries and reduce the amount of requests being sent to object storage.
64+
65+
The regional cache has two modes:
66+
67+
- `short-lived`: Responses are re-used for up to a minute.
68+
- `long-lived`: Fetch responses are re-used until revalidated, and ISR/SSG responses are re-used for up to 30 minutes.
69+
70+
Additionally, lazy updating of the regional cache can be enabled with the `shouldLazilyUpdateOnCacheHit` option. When requesting data from the cache, it sends a background request to the R2 bucket to get the latest entry. This is enabled by default for the `long-lived` mode.
6071

6172
```ts
6273
// open-next.config.ts
6374
import { defineCloudflareConfig } from "@opennextjs/cloudflare";
64-
import kvIncrementalCache from "@opennextjs/cloudflare/overrides/incremental-cache/kv-incremental-cache";
75+
import r2IncrementalCache from "@opennextjs/cloudflare/overrides/incremental-cache/r2-incremental-cache";
76+
import { withRegionalCache } from "@opennextjs/cloudflare/overrides/incremental-cache/regional-cache";
6577
// ...
6678

79+
// With regional cache enabled:
6780
export default defineCloudflareConfig({
68-
incrementalCache: kvIncrementalCache,
81+
incrementalCache: withRegionalCache(r2IncrementalCache, {
82+
mode: "long-lived",
83+
shouldLazilyUpdateOnCacheHit: true,
84+
}),
85+
// ...
86+
});
87+
88+
// Without regional cache:
89+
export default defineCloudflareConfig({
90+
incrementalCache: r2IncrementalCache,
6991
// ...
7092
});
7193
```
7294

7395
</Tabs.Tab>
74-
7596
<Tabs.Tab>
76-
77-
##### 1. Create an R2 Bucket
97+
##### 1. Create a KV namespace
7898

7999
```
80-
npx wrangler@latest r2 bucket create <YOUR_BUCKET_NAME>
100+
npx wrangler@latest kv namespace create <YOUR_NAMESPACE_NAME>
81101
```
82102

83-
##### 2. Add the R2 Bucket and Service Binding to your Worker
84-
85-
The binding name used in your app's worker is `NEXT_INC_CACHE_R2_BUCKET`. The service binding should be a self reference to your worker where `<WORKER_NAME>` is the name in your wrangler configuration file.
103+
##### 2. Add the KV namespace and Service Binding to your Worker
86104

87-
The prefix used by the R2 bucket can be configured with the `NEXT_INC_CACHE_R2_PREFIX` environment variable, and defaults to `incremental-cache`.
105+
The binding name used in your app's worker is `NEXT_INC_CACHE_KV`.
106+
The `WORKER_SELF_REFERENCE` service binding should be a self reference to your worker where `<WORKER_NAME>` is the name in your wrangler configuration file.
88107

89108
```jsonc
90109
// wrangler.jsonc
91110
{
92111
// ...
93112
"name": "<WORKER_NAME>",
94-
"r2_buckets": [
113+
"kv_namespaces": [
95114
{
96-
"binding": "NEXT_INC_CACHE_R2_BUCKET",
97-
"bucket_name": "<BUCKET_NAME>",
98-
"preview_bucket_name": "<PREVIEW_BUCKET_NAME>",
115+
"binding": "NEXT_INC_CACHE_KV",
116+
"id": "<BINDING_ID>",
99117
},
100118
],
101119
"services": [
@@ -109,36 +127,16 @@ The prefix used by the R2 bucket can be configured with the `NEXT_INC_CACHE_R2_P
109127

110128
##### 3. Configure the cache
111129

112-
In your project's OpenNext config, enable the R2 cache.
113-
114-
You can optionally setup a regional cache to use with the R2 incremental cache. This will enable faster retrieval of cache entries and reduce the amount of requests being sent to object storage.
115-
116-
The regional cache has two modes:
117-
118-
- `short-lived`: Responses are re-used for up to a minute.
119-
- `long-lived`: Fetch responses are re-used until revalidated, and ISR/SSG responses are re-used for up to 30 minutes.
120-
121-
Additionally, lazy updating of the regional cache can be enabled with the `shouldLazilyUpdateOnCacheHit` option. When requesting data from the cache, it sends a background request to the R2 bucket to get the latest entry. This is enabled by default for the `long-lived` mode.
130+
In your project's OpenNext config, enable the KV cache.
122131

123132
```ts
124133
// open-next.config.ts
125134
import { defineCloudflareConfig } from "@opennextjs/cloudflare";
126-
import r2IncrementalCache from "@opennextjs/cloudflare/overrides/incremental-cache/r2-incremental-cache";
127-
import { withRegionalCache } from "@opennextjs/cloudflare/overrides/incremental-cache/regional-cache";
135+
import kvIncrementalCache from "@opennextjs/cloudflare/overrides/incremental-cache/kv-incremental-cache";
128136
// ...
129137

130-
// With regional cache enabled:
131138
export default defineCloudflareConfig({
132-
incrementalCache: withRegionalCache(r2IncrementalCache, {
133-
mode: "long-lived",
134-
shouldLazilyUpdateOnCacheHit: true,
135-
}),
136-
// ...
137-
});
138-
139-
// Without regional cache:
140-
export default defineCloudflareConfig({
141-
incrementalCache: r2IncrementalCache,
139+
incrementalCache: kvIncrementalCache,
142140
// ...
143141
});
144142
```
@@ -172,14 +170,14 @@ You will also need to add some binding to your `wrangler.jsonc` file.
172170
"bindings": [
173171
{
174172
"name": "NEXT_CACHE_DO_QUEUE",
175-
"class_name": "DurableObjectQueueHandler"
173+
"class_name": "DOQueueHandler"
176174
}
177175
]
178176
},
179177
"migrations": [
180178
{
181179
"tag": "v1",
182-
"new_sqlite_classes": ["DurableObjectQueueHandler"]
180+
"new_sqlite_classes": ["DOQueueHandler"]
183181
}
184182
],
185183
```
@@ -189,7 +187,7 @@ You can customize the behaviors of the queue with environment variables:
189187
- The max number of revalidations that can be processed by an instance of durable object at the same time (`NEXT_CACHE_DO_QUEUE_MAX_REVALIDATION`)
190188
- The max time in milliseconds that a revalidation can take before being considered as failed (`NEXT_CACHE_DO_QUEUE_REVALIDATION_TIMEOUT_MS`)
191189
- The amount of time after which a revalidation will be attempted again if it failed. If it fails again it will exponentially back off until it reaches the max retry interval (`NEXT_CACHE_DO_QUEUE_RETRY_INTERVAL_MS`)
192-
- The maximum number of attempts that can be made to revalidate a path (`NEXT_CACHE_DO_QUEUE_MAX_NUM_REVALIDATIONS`)
190+
- The maximum number of attempts that can be made to revalidate a path (`NEXT_CACHE_DO_QUEUE_MAX_RETRIES`)
193191
- Disable SQLite for this durable object. It should only be used if your incremental cache is not eventually consistent (`NEXT_CACHE_DO_QUEUE_DISABLE_SQLITE`)
194192

195193
<Callout>
@@ -216,15 +214,15 @@ To use on-demand revalidation, you should also follow the [ISR setup steps](#inc
216214
You can also skip this step if your app doesn't to use `revalidateTag` nor `revalidatePath`.
217215
</Callout>
218216

219-
There are 3 different options to choose from for the tag cache: `d1NextTagCache`, `doShardedTagCache` and `d1TagCache`.
217+
There are 2 different options to choose from for the tag cache: `d1NextTagCache`, `doShardedTagCache`.
220218
Which one to choose should be based on two key factors:
221219

222220
1. **Expected Load**: Consider the volume of traffic or data you anticipate.
223221
2. **Usage of** `revalidateTag` / `revalidatePath`: Evaluate how frequently these features will be utilized.
224222

225223
If either of these factors is significant, opting for a sharded database is recommended. Additionally, incorporating a regional cache can further enhance performance.
226224

227-
<Tabs items={["D1NextTagCache", "doShardedTagCache", "D1TagCache"]}>
225+
<Tabs items={["D1NextTagCache", "doShardedTagCache"]}>
228226
<Tabs.Tab>
229227
##### 1. Create a D1 database and Service Binding
230228

@@ -256,22 +254,43 @@ The D1 tag cache requires a `revalidations` table that tracks On-Demand revalida
256254

257255
##### 3. Configure the cache
258256

259-
In your project's OpenNext config, enable the KV cache and set up a queue (see above). The queue will send a revalidation request to a page when needed, but it will not dedupe requests.
257+
In your project's OpenNext config, enable the R2 cache and set up a queue (see above). The queue will send a revalidation request to a page when needed, but it will not dedupe requests.
260258

261259
```ts
262260
// open-next.config.ts
263261
import { defineCloudflareConfig } from "@opennextjs/cloudflare";
264-
import kvIncrementalCache from "@opennextjs/cloudflare/kv-cache";
265-
import d1NextTagCache from "@opennextjs/cloudflare/d1-next-tag-cache";
266-
import memoryQueue from "@opennextjs/cloudflare/memory-queue";
262+
import r2IncrementalCache from "@opennextjs/cloudflare/overrides/incremental-cache/r2-incremental-cache";
263+
import d1NextTagCache from "@opennextjs/cloudflare/overrides/tag-cache/d1-next-tag-cache";
264+
import doQueue from "@opennextjs/cloudflare/overrides/queue/do-queue";
267265

268266
export default defineCloudflareConfig({
269-
incrementalCache: kvIncrementalCache,
267+
incrementalCache: r2IncrementalCache,
270268
tagCache: d1NextTagCache,
271-
queue: memoryQueue,
269+
queue: doQueue,
272270
});
273271
```
274272

273+
##### 4. Initialise the cache during deployments
274+
275+
In order for the cache to be properly initialised with the build-time revalidation data, you need to run a command as part of your deploy step. This should be run as part of each deployment to ensure that the cache is being populated with each build's data.
276+
277+
To populate remote bindings and deploy your application at the same time, you can use the `deploy` command. Similarly, the `preview` command will populate your local bindings and start a Wrangler dev server.
278+
279+
```sh
280+
# Populate remote and deploy.
281+
opennextjs-cloudflare deploy
282+
283+
# Populate local and start dev server.
284+
opennextjs-cloudflare preview
285+
```
286+
287+
It is possible to only populate the cache without any other steps with the `populateCache` command.
288+
289+
```sh
290+
# The target is passed as an option, either `local` or `remote`.
291+
opennextjs-cloudflare populateCache local
292+
```
293+
275294
</Tabs.Tab>
276295

277296
<Tabs.Tab>
@@ -286,18 +305,18 @@ The service binding should be a self reference to your worker where `<WORKER_NAM
286305
"bindings": [
287306
{
288307
"name": "NEXT_CACHE_DO_QUEUE",
289-
"class_name": "DurableObjectQueueHandler",
308+
"class_name": "DOQueueHandler",
290309
},
291310
{
292-
"name": "NEXT_CACHE_DO_SHARDED",
311+
"name": "NEXT_TAG_CACHE_DO_SHARDED",
293312
"class_name": "DOShardedTagCache",
294313
},
295314
],
296315
},
297316
"migrations": [
298317
{
299318
"tag": "v1",
300-
"new_sqlite_classes": ["DurableObjectQueueHandler", "DOShardedTagCache"],
319+
"new_sqlite_classes": ["DOQueueHandler", "DOShardedTagCache"],
301320
},
302321
],
303322
"services": [
@@ -332,87 +351,10 @@ doShardedTagCache tahes the following options:
332351
- `baseShardSize` - The number of shards to use for the cache. The more shards you have, the more evenly the cache will be distributed across the shards. The default is 4. Soft (internal next tags used for `revalidatePath`) and hard tags (the one you define in your app) will be split in different shards
333352
- `regionalCache` - Whether to use regional cache for the cache. The default is false. This option is useful when you want to reduce the stress on the durable object
334353
- `regionalCacheTtlSec` - The TTL for the regional cache. The default is 5 seconds. Increasing this value will increase the time it takes for the cache to be invalidated across regions
335-
- `enableShardReplication`: Enable replicating the Shard. Shard replication will duplicate each shards into replicas to spread the load even more
336-
- `shardReplicationOptions.numberOfSoftReplicas`: Number of replicas for the soft tag shards
337-
- `shardReplicationOptions.numberOfHardReplicas`: Number of replicas for the hard tag shards
354+
- `shardReplication`: Enable replicating the Shard. Shard replication will duplicate each shards into replicas to spread the load even more
355+
- `shardReplication.numberOfSoftReplicas`: Number of replicas for the soft tag shards
356+
- `shardReplication.numberOfHardReplicas`: Number of replicas for the hard tag shards
338357
- `maxWriteRetries`: The number of retries to perform when writing tags
339358

340-
</Tabs.Tab>
341-
342-
<Tabs.Tab>
343-
344-
<Callout>
345-
The `d1TagCache` is not recommended for production use, as it does not scale well with the number of tags.
346-
</Callout>
347-
348-
##### 1. Create a D1 database and Service Binding
349-
350-
The binding name used in your app's worker is `NEXT_TAG_CACHE_D1`. The service binding should be a self reference to your worker where `<WORKER_NAME>` is the name in your wrangler configuration file.
351-
352-
```jsonc
353-
// wrangler.jsonc
354-
{
355-
// ...
356-
"name": "<WORKER_NAME>",
357-
"d1_databases": [
358-
{
359-
"binding": "NEXT_TAG_CACHE_D1",
360-
"database_id": "<DATABASE_ID>",
361-
"database_name": "<DATABASE_NAME>",
362-
},
363-
],
364-
"services": [
365-
{
366-
"binding": "WORKER_SELF_REFERENCE",
367-
"service": "<WORKER_NAME>",
368-
},
369-
],
370-
}
371-
```
372-
373-
The D1 database uses two tables, created when initialising the cache:
374-
375-
- the "tags" table keeps a record of the tag/path mappings
376-
- the "revalidations" table tracks revalidation times
377-
378-
##### 2. Configure the cache
379-
380-
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.
381-
382-
```ts
383-
// open-next.config.ts
384-
import { defineCloudflareConfig } from "@opennextjs/cloudflare";
385-
import kvIncrementalCache from "@opennextjs/cloudflare/overrides/incremental-cache/kv-incremental-cache";
386-
import d1TagCache from "@opennextjs/cloudflare/overrides/tag-cache/d1-tag-cache";
387-
import memoryQueue from "@opennextjs/cloudflare/overrides/queue/memory-queue";
388-
389-
export default defineCloudflareConfig({
390-
incrementalCache: kvIncrementalCache,
391-
tagCache: d1TagCache,
392-
queue: memoryQueue,
393-
});
394-
```
395-
396-
##### 3. Initialise the cache during deployments
397-
398-
In order for the cache to be properly initialised with the build-time revalidation data, you need to run a command as part of your deploy step. This should be run as part of each deployment to ensure that the cache is being populated with each build's data.
399-
400-
To populate remote bindings and deploy your application at the same time, you can use the `deploy` command. Similarly, the `preview` command will populate your local bindings and start a Wrangler dev server.
401-
402-
```sh
403-
# Populate remote and deploy.
404-
opennextjs-cloudflare deploy
405-
406-
# Populate local and start dev server.
407-
opennextjs-cloudflare preview
408-
```
409-
410-
It is possible to only populate the cache without any other steps with the `populateCache` command.
411-
412-
```sh
413-
# The target is passed as an option, either `local` or `remote`.
414-
opennextjs-cloudflare populateCache local
415-
```
416-
417359
</Tabs.Tab>
418360
</Tabs>

‎pages/cloudflare/former-releases/0.6/_meta.json‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
{
2+
"index": "Overview",
3+
"get-started": "",
4+
"bindings": "",
5+
"caching": "",
6+
"examples": ""
7+
}

0 commit comments

Comments
 (0)