Caching

Next.js offers multiple ways to improve an application's performance by caching (opens in a new tab) routes and network requests. An application will try to pre-render and cache as much data as possible during build-time to reduce the amount of work required when serving a response to a user.

The cache data are updated using revalidation, either peridiocally or on-demand:

• "Time-based revalidation (opens in a new tab)" updates the cache data after the revalidation delay specified by the applications expires
• "On-demand revalidation (opens in a new tab)" allows to invalid cache entries with a specific tag (via revalidateTag) or at a given path (via revalidatePath). You can also use res.revalidate in Pages router API route.

The @opennextjs/cloudflare caching supports rely on 3 components:

• An Incremental Cache to store the cache data
• A Queue to synchronize and deduplicate time-based revalidations
• A Tag Cache for On-demand revalidations via revalidateTag (opens in a new tab) and revalidatePath (opens in a new tab).

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.

Guidelines

Small site using revalidation

You should use the following implementation for a small site:

• Incremental Cache: use R2 to store the data
• Queue: use a Queue backed by Durable Objects
• Tag Cache: D1NextModeTagCache

{
  "name": "<WORKER_NAME>",
  // ...
 
  "services": [
    {
      "binding": "WORKER_SELF_REFERENCE",
      "service": "<WORKER_NAME>",
    },
  ],
 
  // R2 incremental cache
  "r2_buckets": [
    {
      "binding": "NEXT_INC_CACHE_R2_BUCKET",
      "bucket_name": "<BUCKET_NAME>",
    },
  ],
 
  // DO Queue
  "durable_objects": {
    "bindings": [
      {
        "name": "NEXT_CACHE_DO_QUEUE",
        "class_name": "DOQueueHandler",
      },
    ],
  },
  "migrations": [
    {
      "tag": "v1",
      "new_sqlite_classes": ["DOQueueHandler"],
    },
  ],
 
  // D1 Tag Cache (Next mode)
  // This is only required if you use On-demand revalidation
  "d1_databases": [
    {
      "binding": "NEXT_TAG_CACHE_D1",
      "database_id": "<DATABASE_ID>",
      "database_name": "<DATABASE_NAME>",
    },
  ],
}

Large site using revalidation

For a larger site, you should use the ShardedDOTagCache that can handle a higher load than the D1NextModeTagCache:

{
  "name": "<WORKER_NAME>",
  // ...
 
  "services": [
    {
      "binding": "WORKER_SELF_REFERENCE",
      "service": "<WORKER_NAME>",
    },
  ],
 
  // R2 incremental cache
  "r2_buckets": [
    {
      "binding": "NEXT_INC_CACHE_R2_BUCKET",
      "bucket_name": "<BUCKET_NAME>",
    },
  ],
 
  // DO Queue and DO Sharded Tag Cache
  "durable_objects": {
    "bindings": [
      {
        "name": "NEXT_CACHE_DO_QUEUE",
        "class_name": "DOQueueHandler",
      },
      // This is only required if you use On-demand revalidation
      {
        "name": "NEXT_TAG_CACHE_DO_SHARDED",
        "class_name": "DOShardedTagCache",
      },
    ],
  },
  "migrations": [
    {
      "tag": "v1",
      "new_sqlite_classes": [
        "DOQueueHandler",
        // This is only required if you use On-demand revalidation
        "DOShardedTagCache",
      ],
    },
  ],
}

SSG site

If your site is static, you do not need a Queue nor a Tag Cache. You can use a read-only Workers Static Assets-based incremental cache for the prerendered routes.

import { defineCloudflareConfig } from "@opennextjs/cloudflare";
import staticAssetsIncrementalCache from "@opennextjs/cloudflare/overrides/incremental-cache/static-assets-incremental-cache";
 
export default defineCloudflareConfig({
  incrementalCache: staticAssetsIncrementalCache,
});

Staging

For staging, when your site receives low traffic from a single IP, you can replace the DO queue with a memory queue.

References

Incremental Static Regeneration (ISR)

There are 3 storage options for the incremental cache:

• R2 Object Storage: A cost-effective (opens in a new tab) S3-compatible object storage option for large amounts of unstructured data. Data is stored in a single region, meaning cache interactions may be slower - this can be mitigated with a regional cache.
• Workers KV: A fast (opens in a new tab) key value store, it uses Cloudflare's Tiered Cache (opens in a new tab) to increase cache hit rates. When you write cached data to Workers KV, you write to storage that can be read by any Cloudflare location. This means your app can fetch data, cache it in KV, and then subsequent requests anywhere around the world can read from this cache.
• Workers Static Assets: A read-only store for the incremental cache, serving build-time values from Workers Static Assets (opens in a new tab). Revalidation is not supported with this cache.

npx wrangler@latest r2 bucket create <YOUR_BUCKET_NAME>

// wrangler.jsonc
{
  // ...
  "name": "<WORKER_NAME>",
  "r2_buckets": [
    {
      "binding": "NEXT_INC_CACHE_R2_BUCKET",
      "bucket_name": "<BUCKET_NAME>",
    },
  ],
  "services": [
    {
      "binding": "WORKER_SELF_REFERENCE",
      "service": "<WORKER_NAME>",
    },
  ],
}

// open-next.config.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";
// ...
 
// With regional cache enabled:
export default defineCloudflareConfig({
  incrementalCache: withRegionalCache(r2IncrementalCache, {
    mode: "long-lived",
    shouldLazilyUpdateOnCacheHit: true,
  }),
  // ...
});
 
// Without regional cache:
export default defineCloudflareConfig({
  incrementalCache: r2IncrementalCache,
  // ...
});

Queue

A queue must be setup for projects using revalidation (either Time based or On-demand).

Configure the queue

In your project's OpenNext config, enable the cache and set up a queue.

The Durable Object Queue will send revalidation requests to a page when needed, and offers support for de-duplicating requests. By default there will be a maximum of 10 instance of the Durables Object Queue and they can each process up to 5 requests in parallel, for up to 50 concurrent ISR revalidations.

// open-next.config.ts
import { defineCloudflareConfig } from "@opennextjs/cloudflare";
// ...
import r2IncrementalCache from "@opennextjs/cloudflare/overrides/incremental-cache/r2-incremental-cache";
import doQueue from "@opennextjs/cloudflare/overrides/queue/do-queue";
 
export default defineCloudflareConfig({
  // ...
  incrementalCache: r2IncrementalCache,
  queue: doQueue,
});

You will also need to add some binding to your wrangler.jsonc file.

"durable_objects": {
    "bindings": [
      {
        "name": "NEXT_CACHE_DO_QUEUE",
        "class_name": "DOQueueHandler"
      }
    ]
  },
  "migrations": [
    {
      "tag": "v1",
      "new_sqlite_classes": ["DOQueueHandler"]
    }
  ],

You can customize the behaviors of the queue with environment variables:

• The max number of revalidations that can be processed by an instance of durable object at the same time (NEXT_CACHE_DO_QUEUE_MAX_RETRIES)
• The max time in milliseconds that a revalidation can take before being considered as failed (NEXT_CACHE_DO_QUEUE_REVALIDATION_TIMEOUT_MS)
• 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)
• The maximum number of attempts that can be made to revalidate a path (NEXT_CACHE_DO_QUEUE_MAX_RETRIES)
• 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)

Tag Cache for On-Demand Revalidation

The tag revalidation mechanism can use either a Cloudflare D1 (opens in a new tab) database or Durable Objects (opens in a new tab) with SqliteStorage 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.

There are 2 different options to choose from for the tag cache: d1NextTagCache, doShardedTagCache. Which one to choose should be based on two key factors:

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

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

// wrangler.jsonc
{
  // ...
  "d1_databases": [
    {
      "binding": "NEXT_TAG_CACHE_D1",
      "database_id": "<DATABASE_ID>",
      "database_name": "<DATABASE_NAME>",
    },
  ],
  "services": [
    {
      "binding": "WORKER_SELF_REFERENCE",
      "service": "<WORKER_NAME>",
    },
  ],
}

// open-next.config.ts
import { defineCloudflareConfig } from "@opennextjs/cloudflare";
import r2IncrementalCache from "@opennextjs/cloudflare/overrides/incremental-cache/r2-incremental-cache";
import doQueue from "@opennextjs/cloudflare/overrides/queue/do-queue";
import d1NextTagCache from "@opennextjs/cloudflare/overrides/tag-cache/d1-next-tag-cache";
 
export default defineCloudflareConfig({
  incrementalCache: r2IncrementalCache,
  queue: doQueue,
  tagCache: d1NextTagCache,
});

# Populate remote and deploy the worker immediately.
opennextjs-cloudflare deploy
 
# Populate remote and upload a new version of the worker.
opennextjs-cloudflare upload
 
# Populate local and start dev server.
opennextjs-cloudflare preview

# The target is passed as an option, either `local` or `remote`.
opennextjs-cloudflare populateCache local