Configuration (17)·续2

  • name string required
  • The name of the binding used to refer to the Durable Object.
  • class_name string required
  • The exported class name of the Durable Object.
  • script_name string optional
  • The name of the Worker where the Durable Object is defined, if it is external to this Worker. This option can be used both in local and remote development. In local development, you must run the external Worker in a separate process (via wrangler dev). In remote development, the appropriate remote binding must be used.
  • environment string optional
  • The environment of the script_name to bind to.

Example:

{
    "durable_objects": {
        "bindings": [
            {
                "name": "<BINDING_NAME>",
                "class_name": "<CLASS_NAME>",
            },
        ],
    },
}

[[durable_objects.bindings]]
name = "<BINDING_NAME>"
class_name = "<CLASS_NAME>"

Exports

The exports field declares the Durable Object classes this Worker exports and their lifecycle state. Refer to Durable Object class exports.

Each entry in exports is keyed by Durable Object class name. The fields on each entry are:

  • type string required
  • For Durable Object class entries, set this to "durable-object".
  • state string optional
  • The lifecycle state. One of "created" (the default — a live class), "deleted", "renamed", "transferred", or "expecting-transfer".
  • storage string conditional
  • Required when state is "created" or "expecting-transfer". One of "sqlite" (recommended; required for new namespaces) or "legacy-kv" (only for existing key-value-backed namespaces).
  • renamed_to string conditional
  • Required when state is "renamed". The destination class name, which must also appear as a live entry in the same exports map.
  • transferred_to string conditional
  • Required when state is "transferred". The name of the target Worker that will receive the namespace.
  • transfer_from string conditional
  • Required when state is "expecting-transfer". The name of the source Worker the namespace is being transferred from.
  • container string optional
  • Attaches a Container to this Durable Object. Must match the name of an entry in the top-level containers array, and requires storage to be "sqlite". Only allowed when state is "created" or "expecting-transfer". Use this instead of setting class_name on the Container entry.

Example:

{
    "exports": {
        "MyDurableObject": {
            "type": "durable-object",
            "storage": "sqlite",
        },
        "OldClass": {
            "type": "durable-object",
            "state": "deleted",
        },
        "OldName": {
            "type": "durable-object",
            "state": "renamed",
            "renamed_to": "NewName",
        },
        "NewName": {
            "type": "durable-object",
            "storage": "sqlite",
        },
    },
}

[exports.MyDurableObject]
type = "durable-object"
storage = "sqlite"

[exports.OldClass]
type = "durable-object"
state = "deleted"

[exports.OldName]
type = "durable-object"
state = "renamed"
renamed_to = "NewName"

[exports.NewName]
type = "durable-object"
storage = "sqlite"

Migrations

Note

migrations is the legacy imperative configuration for managing Durable Object class lifecycle. For new Workers, prefer the declarative exports field. migrations and Durable Object entries in exports are mutually exclusive.

When making changes to your Durable Object classes on a Worker that uses the legacy migrations array, you must perform a migration. Refer to Durable Object class migrations (legacy).

  • tag string required
  • A unique identifier for this migration.
  • new_sqlite_classes string[] optional
  • New Durable Object classes being defined with the SQLite storage backend.
  • new_classes string[] optional
  • New Durable Object classes being defined with the legacy key-value storage backend.
  • renamed_classes {from: string, to: string}[] optional
  • The Durable Object classes being renamed.
  • deleted_classes string[] optional
  • The Durable Object classes being removed.
  • transferred_classes {from: string, from_script: string, to: string}[] optional
  • The Durable Object classes being transferred from another Worker.

Example:

{
    "migrations": [
        {
            "tag": "v1",
            "new_sqlite_classes": [
                // Array of new classes
                "DurableObjectExample",
            ],
        },
        {
            "tag": "v2", // Should be unique for each entry
            "renamed_classes": [
                // Array of rename directives
                {
                    "from": "DurableObjectExample",
                    "to": "UpdatedName",
                },
            ],
            "deleted_classes": [
                // Array of deleted class names
                "DeprecatedClass",
            ],
        },
    ],
}

[[migrations]]
tag = "v1"
new_sqlite_classes = [ "DurableObjectExample" ]

[[migrations]]
tag = "v2"
deleted_classes = [ "DeprecatedClass" ]

[[migrations.renamed_classes]]
  from = "DurableObjectExample"
  to = "UpdatedName"

Email bindings

You can send an email about your Worker's activity from your Worker to an email address verified on Email Routing. This is useful for when you want to know about certain types of events being triggered, for example.

Before you can bind an email address to your Worker, you need to enable Email Routing and have at least one verified email address. Then, assign an array to the object (send_email) with the type of email binding you need.

You can add one or more types of bindings to your Wrangler file. However, each attribute must be on its own line:

{
    "send_email": [
        {
            "name": "<NAME_FOR_BINDING1>"
        },
        {
            "name": "<NAME_FOR_BINDING2>",
            "destination_address": "<YOUR_EMAIL>@example.com"
        },
        {
            "name": "<NAME_FOR_BINDING3>",
            "allowed_destination_addresses": [
                "<YOUR_EMAIL>@example.com",
                "<YOUR_EMAIL2>@example.com"
            ]
        }
    ]
}

[[send_email]]
name = "<NAME_FOR_BINDING1>"

[[send_email]]
name = "<NAME_FOR_BINDING2>"
destination_address = "<YOUR_EMAIL>@example.com"

[[send_email]]
name = "<NAME_FOR_BINDING3>"
allowed_destination_addresses = [ "<YOUR_EMAIL>@example.com", "<YOUR_EMAIL2>@example.com" ]

Environment variables

Environment variables are a type of binding that allow you to attach text strings or JSON values to your Worker.

Example:

{
    "$schema": "./node_modules/wrangler/config-schema.json",
    "name": "my-worker-dev",
    "vars": {
        "API_HOST": "example.com",
        "API_ACCOUNT_ID": "example_user",
        "SERVICE_X_DATA": {
            "URL": "service-x-api.dev.example",
            "MY_ID": 123
        }
    }
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "my-worker-dev"

[vars]
API_HOST = "example.com"
API_ACCOUNT_ID = "example_user"

[vars.SERVICE_X_DATA]
  URL = "service-x-api.dev.example"
  MY_ID = 123

Hyperdrive

Hyperdrive bindings allow you to interact with and query any Postgres database from within a Worker.

  • binding string required
  • The binding name.
  • id string required
  • The ID of the Hyperdrive configuration.

Example:

{
    // required for database drivers to function
    "compatibility_flags": ["nodejs_compat_v2"],
    "hyperdrive": [
        {
            "binding": "<BINDING_NAME>",
            "id": "<ID>",
        },
    ],
}

compatibility_flags = [ "nodejs_compat_v2" ]

[[hyperdrive]]
binding = "<BINDING_NAME>"
id = "<ID>"

Images

Cloudflare Images lets you make transformation requests to optimize, resize, and manipulate images stored in remote sources.

To bind Images to your Worker, assign an array of the below object to the images key.

binding (required). The name of the binding used to refer to the Images API.

{
    "images": {
        "binding": "IMAGES", // i.e. available in your Worker on env.IMAGES
    },
}

[images]
binding = "IMAGES"

KV namespaces

Workers KV is a global, low-latency, key-value data store. It stores data in a small number of centralized data centers, then caches that data in Cloudflare’s data centers after access.

To bind KV namespaces to your Worker, assign an array of the below object to the kv_namespaces key.

  • binding string required
  • The binding name used to refer to the KV namespace.
  • id string required
  • The ID of the KV namespace.
  • preview_id string optional
  • The preview ID of this KV namespace. This option is required when using wrangler dev --remote to develop against remote resources (but is not required with remote bindings). If developing locally, this is an optional field. wrangler dev will use this ID for the KV namespace. Otherwise, wrangler dev will use id.

Note

When using Wrangler in the default local development mode, files will be written to local storage instead of the preview or production namespace. Refer to Local development for more details.

Example:

{
    "kv_namespaces": [
        {
            "binding": "<BINDING_NAME1>",
            "id": "<NAMESPACE_ID1>",
        },
        {
            "binding": "<BINDING_NAME2>",
            "id": "<NAMESPACE_ID2>",
        },
    ],
}

[[kv_namespaces]]
binding = "<BINDING_NAME1>"
id = "<NAMESPACE_ID1>"

[[kv_namespaces]]
binding = "<BINDING_NAME2>"
id = "<NAMESPACE_ID2>"

AI Search namespaces

AI Search is Cloudflare's managed search service. A namespace is a logical grouping of AI Search instances. The binding grants full access to all instances within the namespace.

To bind AI Search namespaces to your Worker, assign an array of the below object to the ai_search_namespaces key.

  • binding string required
  • The binding name used to refer to the AI Search namespace.
  • namespace string required
  • The name of the AI Search namespace. A default namespace is created automatically for every account. If the namespace does not exist, Wrangler creates it on deploy.

Example:

{
    "ai_search_namespaces": [
        {
            "binding": "<BINDING_NAME>",
            "namespace": "default",
        },
    ],
}

[[ai_search_namespaces]]
binding = "<BINDING_NAME>"
namespace = "default"

AI Search instances

To bind directly to a pre-existing AI Search instance in the default namespace, assign an array of the below object to the ai_search key. This binding does not support namespace-level operations like list(), create(), or delete().

  • binding string required
  • The binding name used to refer to the AI Search instance.
  • instance_name string required
  • The name of the AI Search instance. Must exist in the default namespace at deploy time.

Example:

{
    "ai_search": [
        {
            "binding": "<BINDING_NAME>",
            "instance_name": "<INSTANCE_NAME>",
        },
    ],
}

[[ai_search]]
binding = "<BINDING_NAME>"
instance_name = "<INSTANCE_NAME>"

Queues

Queues is Cloudflare's global message queueing service, providing guaranteed delivery and message batching. To interact with a queue with Workers, you need a producer Worker to send messages to the queue and a consumer Worker to pull batches of messages out of the Queue. A single Worker can produce to and consume from multiple Queues.

To bind Queues to your producer Worker, assign an array of the below object to the [[queues.producers]] key.

  • queue string required
  • The name of the queue, used on the Cloudflare dashboard.
  • binding string required
  • The binding name used to refer to the queue in your Worker. The binding must be a valid JavaScript variable name ↗︎. For example, binding = "MY_QUEUE" or binding = "productionQueue" would both be valid names for the binding.
  • delivery_delay number optional
  • The number of seconds to delay messages sent to a queue for by default. This can be overridden on a per-message or per-batch basis.

Example:

{
    "queues": {
        "producers": [
            {
                "binding": "<BINDING_NAME>",
                "queue": "<QUEUE_NAME>",
                "delivery_delay": 60, // Delay messages by 60 seconds before they are delivered to a consumer
            },
        ],
    },
}

[[queues.producers]]
binding = "<BINDING_NAME>"
queue = "<QUEUE_NAME>"
delivery_delay = 60

To bind Queues to your consumer Worker, assign an array of the below object to the [[queues.consumers]] key.

  • queue string required
  • The name of the queue, used on the Cloudflare dashboard.
  • max_batch_size number optional
  • The maximum number of messages allowed in each batch.
  • max_batch_timeout number optional
  • The maximum number of seconds to wait for messages to fill a batch before the batch is sent to the consumer Worker.
  • max_retries number optional
  • The maximum number of retries for a message, if it fails or retryAll() is invoked.
  • dead_letter_queue string optional
  • The name of another queue to send a message if it fails processing at least max_retries times.
  • If a dead_letter_queue is not defined, messages that repeatedly fail processing will be discarded.
  • If there is no queue with the specified name, it will be created automatically.
  • max_concurrency number optional
  • The maximum number of concurrent consumers allowed to run at once. Leaving this unset will mean that the number of invocations will scale to the currently supported maximum.
  • Refer to Consumer concurrency for more information on how consumers autoscale, particularly when messages are retried.
  • retry_delay number optional
  • The number of seconds to delay retried messages for by default, before they are re-delivered to the consumer. This can be overridden on a per-message or per-batch basis when retrying messages.

Example:

{
    "queues": {
        "consumers": [
            {
                "queue": "my-queue",
                "max_batch_size": 10,
                "max_batch_timeout": 30,
                "max_retries": 10,
                "dead_letter_queue": "my-queue-dlq",
                "max_concurrency": 5,
                "retry_delay": 120, // Delay retried messages by 2 minutes before re-attempting delivery
            },
        ],
    },
}

[[queues.consumers]]
queue = "my-queue"
max_batch_size = 10
max_batch_timeout = 30
max_retries = 10
dead_letter_queue = "my-queue-dlq"
max_concurrency = 5
retry_delay = 120

R2 buckets

Cloudflare R2 Storage allows developers to store large amounts of unstructured data without the costly egress bandwidth fees associated with typical cloud storage services.

To bind R2 buckets to your Worker, assign an array of the below object to the r2_buckets key.

  • binding string required
  • The binding name used to refer to the R2 bucket.
  • bucket_name string required
  • The name of this R2 bucket.
  • jurisdiction string optional
  • The jurisdiction where this R2 bucket is located, if a jurisdiction has been specified. Refer to Jurisdictional Restrictions.
  • preview_bucket_name string optional
  • The preview name of this R2 bucket. If provided, wrangler dev will use this name for the R2 bucket. Otherwise, it will use bucket_name. This option is required when using wrangler dev --remote (but is not required with remote bindings).