Advanced Setup

With the basic setup of Next-Cloudflare-Turbo done, this section covers more advanced configurations that see the implementation of separate staging and production environments, as well as configuring caching for use with Next.js revalidation and caching.

The caching system uses:

• D1: Stores cache tags for on-demand revalidation
• R2: Stores incremental cache data (pages, API responses)
• Durable Objects: Manages cache invalidation queues

Resources

Before continuing, it may be helpful to refer to the below documentation from Cloudflare and OpenNext, as they provide much more detailed information:

• Caching
• Environment variables
• Wrangler configuration
• Cloudflare Environments
• Wrangler commands
• Create R2 buckets
• Create D1 database/wrangler commands

Wrangler configuration

The below is the advanced configuration of the wrangler.jsonc - this is saved locally under wrangler-advanced-config.json in the app folder.

The advanced configuration can seem daunting, but it's quite simple and more repetitive than anything else.

The configuration essentially boils down to configuring default top-level settings, and then environment specific overrides.

{
  "name": "next-cloudflare-turbo", // top-level config
  "services":[],
  "d1_databases":[],
  "r2_buckets":[],
  "migrations": [],
  "env": { // environment-level config
    "staging": {
      "name": "next-cloudflare-turbo-staging",
      "d1_databases":[],
      "r2_buckets":[],
      "durable_objects": {}
    },
    "production": {
      "name": "next-cloudflare-turbo",
      "routes": [],
      "d1_databases":[],
      "r2_buckets":[],
      "durable_objects": {}
    },
  }
}

Creating databases

The manual setup will guide you through creating D1 databases. The process is the same for R2. In this instance, you will need to create four D1 databases, and two R2 buckets. The commands would be

D1 databases for application data:

npx wrangler d1 create your-database-name
npx wrangler d1 create your-database-name-staging

D1 databases for tags caches:

npx wrangler d1 create your-database-name-tag
npx wrangler d1 create your-database-name-tag-staging

R2 buckets for incremental cache:

npx wrangler r2 bucket create your-bucket-name
npx wrangler r2 bucket create your-bucket-name-staging

Creating environments

When you create an environment, Cloudflare effectively creates a new Worker with the name top-level-name-environment-name. For example, a Worker project named my-worker with an environment staging would deploy as a Worker named my-worker-staging.

Creating environments is as simple as adding the environment to the env key in your wrangler.jsonc:

  "env": {
    "staging": {}
  }

Working with environments

In the manual setup page, you can see how we use wrangler commands to create D1 databases, apply migrations, and seed data.

To change between environments, you simply pass a --env key to the CLI command, followed by the environment name.

For example:

npx wrangler d1 migrations apply YOUR_DATABASE_NAME_STAGING --env staging --remote

This command would apply migrations to your remote staging database.

Configuring caches

The advanced wrangler configuration should work out-the-box, however you will also need to modify the open-next.config.ts in the apps/app folder.

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"

/**
 * Cloudflare config implementing caching
 * See: https://opennext.js.org/cloudflare/caching
 */
export default defineCloudflareConfig({
// Incremental cache using R2
incrementalCache: r2IncrementalCache,
queue: doQueue,

// This is used for on-demand revalidation, i.e. revalidatePath/revalidateTag
tagCache: d1NextTagCache,

// Disable this if you want to use PPR
// See: https://nextjs.org/docs/app/getting-started/partial-prerendering
enableCacheInterception: true,
})

Configuring package.json

The package-advanced.json contains a modified package.json which includes convenience scripts scoped to the relevant local/staging/production environments.

Simply modify the various scripts to include your database names, and it should work out-the-box.

Deploying to environments

If you're using the package-advanced.json, you can simply use the convenience scripts to deploy to staging or production:

npm run deploy:staging
npm run deploy

These are wrapping the following commands:

npx opennextjs-cloudflare build && opennextjs-cloudflare deploy --env staging
npx opennextjs-cloudflare build && opennextjs-cloudflare deploy --env production

FAQ