Skew protection
The Cloudflare adapter has experimental support for skew protection based on the preview URLs (opens in a new tab).
Preview URLs are disabled for Workers that implement a Durable Object (opens in a new tab). If your app uses Durable Objects, they will need to be implemented in a separate Worker.
How to enable the skew protection
OpenNext config
Set cloudflare.skewProtection.enabled to true to enable skew protection:
export default {
// ...
cloudflare: {
skewProtection: {
enabled: true,
// Maximum number of previous versions to use.
// Optional, default to 20.
maxNumberOfVersions: 20,
// Age of the oldest version to use (from the last deployment date)
// Optional, default to 7 days.
maxVersionAgeDays: 7,
},
},
} satisfies OpenNextConfig;Wrangler configuration
The Worker needs to serve the correct version of the app assets. For that it need be be executed before incoming requests are matched against the assets. Set run_worker_first (opens in a new tab) to true in your wrangler configuration to enable this behavior. html_handling and not_found_handling must then be set as below (see Workers Static Assets):
{
"name": "my-app",
// ...
"assets": {
"directory": ".open-next/assets",
"binding": "ASSETS",
"run_worker_first": true,
// Serve public files at their exact path only, like Next.js
"html_handling": "none",
// "404-page" is also allowed
"not_found_handling": "none",
},
// ...
}Environment variables
The following environment variables should be set when the skew protection is used:
CF_WORKER_NAMEshould be set to the name of the worker, i.e.my-appgiven the config above. If you're using environment, the name of the app should contain your env, i.e.my-app-<env>CF_PREVIEW_DOMAINis the the subdomain ofworkers.devwhere the previews are deployed, i.e.<version>-<worker_name>.<domain>.workers.devCF_WORKERS_SCRIPTS_API_TOKENis an API token with theWorkers Scripts:ReadpermissionCF_ACCOUNT_IDis the Cloudflare account id where the app is deployed.
Those variables are used to retrieve the past deployments of your application.
Note that in this context, environment variables include both your local Cloudflare environment variables (opens in a new tab) and the process' environment variables. If a variable is set in both places, the process environment variable will take precedence.
Next config
You must set a different deploymentId in your next config each time your app is deployed. You will get an error if the deploymentId has already been used by a previous deployment.
The cloudflare adapter exports a getDeploymentId() function that can be used to generate a unique deployment id.
import type { NextConfig } from "next";
import { getDeploymentId } from "@opennextjs/cloudflare";
const nextConfig: NextConfig = {
// ...
deploymentId: getDeploymentId(),
};Using Durable Objects with skew protection
Cloudflare does not allow a worker with preview_urls: true to export Durable Object classes. The solution is to move all DO classes into a separate DO worker and reference them from the main worker using script_name bindings. The main worker continues to use opennextjs-cloudflare deploy and skew protection as normal.
DO worker
Create a separate entry point that re-exports the DO classes from the OpenNext build output:
export { DOQueueHandler } from "./.open-next/.build/durable-objects/queue.js";
export { DOShardedTagCache } from "./.open-next/.build/durable-objects/sharded-tag-cache.js";
export { BucketCachePurge } from "./.open-next/.build/durable-objects/bucket-cache-purge.js";
export default {
async fetch() {
return new Response(null, { status: 404 });
},
};Wrangler configurations
The main worker references the DO classes via script_name. The DO worker holds the implementations and calls back to the main worker via WORKER_SELF_REFERENCE for ISR revalidation:
{
"name": "my-app",
"preview_urls": true,
"services": [{ "binding": "WORKER_SELF_REFERENCE", "service": "my-app" }],
"durable_objects": {
"bindings": [
{ "name": "NEXT_TAG_CACHE_DO_SHARDED", "class_name": "DOShardedTagCache", "script_name": "my-app-do" },
{ "name": "NEXT_CACHE_DO_QUEUE", "class_name": "DOQueueHandler", "script_name": "my-app-do" },
{ "name": "NEXT_CACHE_DO_PURGE", "class_name": "BucketCachePurge", "script_name": "my-app-do" },
],
},
// ...
}{
"main": "do-worker.js",
"name": "my-app-do",
// The DO worker is only accessed through bindings
"workers_dev": false,
"services": [{ "binding": "WORKER_SELF_REFERENCE", "service": "my-app" }],
"durable_objects": {
"bindings": [
{ "name": "NEXT_TAG_CACHE_DO_SHARDED", "class_name": "DOShardedTagCache" },
{ "name": "NEXT_CACHE_DO_QUEUE", "class_name": "DOQueueHandler" },
{ "name": "NEXT_CACHE_DO_PURGE", "class_name": "BucketCachePurge" },
],
},
"migrations": [
{ "tag": "v1", "new_sqlite_classes": ["DOQueueHandler", "DOShardedTagCache", "BucketCachePurge"] },
],
}First deployment: circular dependency
On a new environment neither worker exists yet. Cloudflare validates script_name references and service bindings at deploy time, so deploying either worker first will fail. A bootstrap config for the DO worker without WORKER_SELF_REFERENCE breaks the deadlock:
{
"main": "do-worker.js",
"name": "my-app-do",
// The DO worker is only accessed through bindings
"workers_dev": false,
// no services section
"durable_objects": {
"bindings": [
{ "name": "NEXT_TAG_CACHE_DO_SHARDED", "class_name": "DOShardedTagCache" },
{ "name": "NEXT_CACHE_DO_QUEUE", "class_name": "DOQueueHandler" },
{ "name": "NEXT_CACHE_DO_PURGE", "class_name": "BucketCachePurge" },
],
},
"migrations": [
{ "tag": "v1", "new_sqlite_classes": ["DOQueueHandler", "DOShardedTagCache", "BucketCachePurge"] },
],
}Deploy sequence for a new environment:
opennextjs-cloudflare build- builds the app, including the DO classes imported bydo-worker.jswrangler deploy --config wrangler.do.bootstrap.jsonc- deploys the DO worker withoutWORKER_SELF_REFERENCEopennextjs-cloudflare deploy- deploys the main worker (DO worker now exists,script_nameresolves)wrangler deploy --config wrangler.do.jsonc- redeploys the DO worker withWORKER_SELF_REFERENCE
DOQueueHandler handles a missing WORKER_SELF_REFERENCE gracefully, so ISR revalidation is only briefly unavailable between steps 3 and 4. Subsequent deployments to an existing environment can skip step 2. The DO worker should be deployed after each build so that it uses the DO classes of the same version of the adapter.
What you should know
- Because the Worker is configured to run in front of the assets Worker (
run_worker_first), requesting an asset will count as a request to your Worker - Requesting an older deployment will generate 2 requests: the request to the latest version and the request to the older version
- It is not currently possible to delete a deployment
- Requests to an older deployment will be a few milli-seconds slower than requests to the latest version of the app
- Request to a deployment older than the
maxNumberOfVersionsor older thanmaxVersionAgeDayswill fallback to the current deployment