Wrangler

The wrangler.jsonc file is the configuration for Wrangler should be treated as the single source of truth for configuring your Worker.

Cloudflare recommend only making configuration changes in your wrangler.jsonc instead of using the Cloudflare dashboard. If you change environment variables or routes in the Cloudflare dashboard, Wrangler will automatically override them on your next deplyment unless configured otherwise using flags like --keep-vars. This is explained in greater detail in the environment variables section.

Working with keys

Workers have the concept of top-level only keys, inheritable keys, and non-inheritable keys.

It is recommended you get familiar with keys as you develop your wrangler.jsonc configuration. This becomes especially necessary as you move towards the advanced configuration.

Basic wrangler.jsonc

/**
 * For more details on how to configure Wrangler, refer to:
 * https://developers.cloudflare.com/workers/wrangler/configuration/
 */ {
  // The monorepo hoists wrangler to the root dir; if not using a monorepo, you would omit the "../../"
  "$schema": "../../node_modules/wrangler/config-schema.json",
  "name": "next-cloudflare-turbo",
  "main": ".open-next/worker.js",
  // https://opennext.js.org/cloudflare/howtos/keep_names
  "keep_names": false,
  "compatibility_date": "2025-03-01",
  "compatibility_flags": ["nodejs_compat", "global_fetch_strictly_public"],
  "assets": {
    "binding": "ASSETS",
    "directory": ".open-next/assets"
  },
  "observability": {
    "enabled": true
  },
  "dev": {
    "port": 8787
  },
  // Delete the routes key - this is a custom domain for next-cloudflare-turbo only, left here as an example
  "routes": [
    {
      "pattern": "app.cording.dev",
      "custom_domain": true
    }
  ],
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "next-cloudflare-turbo",
      "database_id": "04bb2f8f-076a-4e72-8baf-c4b533ad3ef8",
      "migrations_dir": "../../packages/db/drizzle/migrations"
    }
  ]
}

Required configuration

The below are required for all wrangler.jsonc configurations

name

"name": "next-cloudflare-turbo",

The name of your Worker. This is how it will appear in your Cloudflare Dashboard - it has no bearing on your application (i.e. end-users won't see it).

main

"main": ".open-next/worker.js",

The path to the entrypoint of your Worker that will be executed. This should remain unchanged unless your are building custom Workers.

compatibility_date

"compatibility_date": "2025-03-01",
"compatibility_flags": ["nodejs_compat", "global_fetch_strictly_public"],

A date in the form yyyy-mm-dd, which will be used to determine which version of the Workers runtime is used. Refer to Compatibility dates.

compatibility_flags

"compatibility_flags": ["nodejs_compat", "global_fetch_strictly_public"],

"compatibility_date": "2025-03-01", A list of flags that enable features from upcoming features of the Workers runtime, usually used together with compatibility_date. Refer to Compatibility dates.

assets

"assets": {
    "binding": "ASSETS",
    "directory": ".open-next/assets"
},

OpenNext will create a .open-next/assets folder containing the hashed and un-hashed files. Files in .open-next/assets should be served from the root of your website. For example, the file .open-next/assets/favicon.ico should be served from /favicon.ico.

d1_databases

  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "next-cloudflare-turbo",
      "database_id": "04bb2f8f-076a-4e72-8baf-c4b533ad3ef8",
      "migrations_dir": "../../packages/db/drizzle/migrations"
    }
  ]

The configuration for the D1 database:

• binding: The name we'll refer to the database as in code. See accessing environment bindings for more information.
• database_name: The name you configured for the database when creating it
• database_id: The database ID, given when creating the database. Can also be found on the Cloudflare Dashboard.
• migrations_dir: The directory where your database migrations are - the @nct/db package.

Optional configuration

The below are optional configurations for wrangler.jsonc files

keep_names

"keep_names": false,

Can be helpful when debugging certain libraries (e.g. next-themes) that convert scripts to strings. If not specified, defaults to true.

This is done to fix errors in the console that reads:

Uncaught ReferenceError: __name is not defined

For more information, see ___name issues.

observability

"observability": {
    "enabled": true
},

Allows you to automatically ingest, store, filter, and analyse logging data emitted from Cloudflare Workers. For more information, see Observability

dev

"dev": {
    "port": 8787
},

Local development setting to force using port 8787 when running wrangler dev. Useful if you are running wrangler dev on more than one Worker at the same time to prevent them from trying to use the same port.

routes

  "routes": [
    {
      "pattern": "app.cording.dev",
      "custom_domain": true
    }
  ],

Allows the use of Custom Domains for your Worker. You will need to delete this when publishing your own Worker (or use your own domain).

Advanced configuration

The advanced configuration of the wrangler.jsonc is what you will likely end up with over time, in particular the configurations for caching.

This advanced configuration further includes environment based configurations, creating separate staging and production environments. For more information, refer to the advanced setup instructions.

Inherited keys

The keys specified at the top-level of the wrangler.jsonc configuration, i.e. not environment specific, can mostly be inherited by the separatley configured environments.

Because of this inheritance, some keys are also redefined within each environment configuration.

services

  "services": [
    {
      // Self-reference binding required for Next.js revalidation
      "binding": "WORKER_SELF_REFERENCE",
      // Service name must match the worker name (the "name" value at the top of this file)
      "service": "next-cloudflare-turbo"
    }
  ]

The services configuration creates a self-reference binding that Next.js uses for revalidation. The service name must match the worker name for each environment.

r2_buckets

"r2_buckets": [
  {
    "binding": "NEXT_INC_CACHE_R2_BUCKET",
    "bucket_name": "next-cloudflare-turbo-cache-staging"
  }
],

Similar to D1 databases, but for storing Next.js incremental cache data. Each environment has its own R2 bucket for cache isolation.

migrations

"migrations": [
  {
    "tag": "v1",
    "new_sqlite_classes": ["DOQueueHandler"]
  }
],

Global configuration for Durable Objects. The DOQueueHandler class is used for managing cache invalidation queues across all environments.

env

  "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": {}
    },
  }

Where we override the top-level configurations with environment specific configurations. Within this, you would specify your different resources via their respective bindings, e.g. d1-staging and d1-production.