Configuration (17)·续3

Configuration (17)·续3

Note

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

Example:

{
    "r2_buckets": [
        {
            "binding": "<BINDING_NAME1>",
            "bucket_name": "<BUCKET_NAME1>",
        },
        {
            "binding": "<BINDING_NAME2>",
            "bucket_name": "<BUCKET_NAME2>",
        },
    ],
}

[[r2_buckets]]
binding = "<BINDING_NAME1>"
bucket_name = "<BUCKET_NAME1>"

[[r2_buckets]]
binding = "<BINDING_NAME2>"
bucket_name = "<BUCKET_NAME2>"

Vectorize indexes

A Vectorize index allows you to insert and query vector embeddings for semantic search, classification and other vector search use-cases.

To bind Vectorize indexes to your Worker, assign an array of the below object to the vectorize key.

binding string required
The binding name used to refer to the bound index from your Worker code.
index_name string required
The name of the index to bind.

Example:

{
    "vectorize": [
        {
            "binding": "<BINDING_NAME>",
            "index_name": "<INDEX_NAME>",
        },
    ],
}

[[vectorize]]
binding = "<BINDING_NAME>"
index_name = "<INDEX_NAME>"

Service bindings

A service binding allows you to send HTTP requests to another Worker without those requests going over the Internet. The request immediately invokes the downstream Worker, reducing latency as compared to a request to a third-party service. Refer to About Service Bindings.

To bind other Workers to your Worker, assign an array of the below object to the services key.

binding string required
The binding name used to refer to the bound Worker.
service string required
The name of the Worker.
To bind to a Worker in a specific environment, you need to append the environment name to the Worker name. This should be in the format <worker-name>-<environment-name>. For example, to bind to a Worker called worker-name in its staging environment, service should be set to worker-name-staging.
entrypoint string optional
The name of the entrypoint to bind to. If you do not specify an entrypoint, the default export of the Worker will be used.

Example:

{
    "services": [
        {
            "binding": "<BINDING_NAME>",
            "service": "<WORKER_NAME>",
            "entrypoint": "<ENTRYPOINT_NAME>",
        },
    ],
}

[[services]]
binding = "<BINDING_NAME>"
service = "<WORKER_NAME>"
entrypoint = "<ENTRYPOINT_NAME>"

Static assets

Refer to Assets.

Analytics Engine Datasets

Workers Analytics Engine provides analytics, observability and data logging from Workers. Write data points to your Worker binding then query the data using the SQL API.

To bind Analytics Engine datasets to your Worker, assign an array of the below object to the analytics_engine_datasets key.

binding string required
The binding name used to refer to the dataset.
dataset string optional
The dataset name to write to. This will default to the same name as the binding if it is not supplied.

Example:

{
    "analytics_engine_datasets": [
        {
            "binding": "<BINDING_NAME>",
            "dataset": "<DATASET_NAME>",
        },
    ],
}

[[analytics_engine_datasets]]
binding = "<BINDING_NAME>"
dataset = "<DATASET_NAME>"

Analytics SQL

The Analytics SQL binding queries analytics datasets without an API token. It requires Wrangler 4.145.0 or later. Assign an object with the following fields to the analytics key:

binding string required
The binding name used to query Analytics SQL from your Worker.
remote boolean optional
Set to true to acknowledge that local development connects to the remote service and suppress the remote resource warning. Analytics SQL has no local implementation and always uses the remote service.

Example:

{
    "analytics": {
        "binding": "ANALYTICS_SQL"
    }
}

[analytics]
binding = "ANALYTICS_SQL"

mTLS Certificates

To communicate with origins that require client authentication, a Worker can present a certificate for mTLS in subrequests. Wrangler provides the mtls-certificate command to upload and manage these certificates.

To create a binding to an mTLS certificate for your Worker, assign an array of objects with the following shape to the mtls_certificates key.

binding string required
The binding name used to refer to the certificate.
certificate_id string required
The ID of the certificate. Wrangler displays this via the mtls-certificate upload and mtls-certificate list commands.

Example of a Wrangler configuration file that includes an mTLS certificate binding:

{
    "mtls_certificates": [
        {
            "binding": "<BINDING_NAME1>",
            "certificate_id": "<CERTIFICATE_ID1>",
        },
        {
            "binding": "<BINDING_NAME2>",
            "certificate_id": "<CERTIFICATE_ID2>",
        },
    ],
}

[[mtls_certificates]]
binding = "<BINDING_NAME1>"
certificate_id = "<CERTIFICATE_ID1>"

[[mtls_certificates]]
binding = "<BINDING_NAME2>"
certificate_id = "<CERTIFICATE_ID2>"

mTLS certificate bindings can then be used at runtime to communicate with secured origins via their fetch method.

Workers AI

Workers AI allows you to run machine learning models, on the Cloudflare network, from your own code – whether that be from Workers, Pages, or anywhere via REST API.

Workers AI local development usage charges

Using Workers AI always accesses your Cloudflare account in order to run AI models and will incur usage charges even in local development.

Unlike other bindings, this binding is limited to one AI binding per Worker project.

binding string required
The binding name.

Example:

{
    "ai": {
        "binding": "AI", // available in your Worker code on `env.AI`
    },
}

[ai]
binding = "AI"

Workflows

Workflows allow you to build durable, multi-step applications using the Workers platform. A Workflow binding enables your Worker to create and manage Workflow instances programmatically.

To bind Workflows to your Worker, assign an array of the below object to the workflows key.

binding string required
The binding name used to refer to the Workflow in your Worker. The binding must be a valid JavaScript variable name ↗︎. For example, binding = "MY_WORKFLOW" would be a valid name for the binding.
name string required
The name of the Workflow.
class_name string required
The name of the exported Workflow class. The class_name must match the name of the Workflow class exported from your Worker code.
script_name string optional
The name of the Worker script where the Workflow class is defined. Only required if the Workflow is defined in a different Worker than the one the binding is configured on.
schedules string[] optional
A list of cron schedules that create new instances of this Workflow automatically.
Use this when you want to run a Workflow on a recurring interval without defining top-level triggers.crons and a separate scheduled handler.
Use a Wrangler release that supports Workflow schedules. If your local schema does not recognize schedules, update Wrangler first.
default_retention object optional
How long to retain the state of instances of this Workflow after they finish. Applied to instances that do not set their own retention when they are created.
success_retention string | number optional — How long to retain instances that complete successfully or are terminated, as a duration string such as "3 days" or a whole number of milliseconds.
error_retention string | number optional — How long to retain instances that end in an errored state, as a duration string such as "7 days" or a whole number of milliseconds.
Retention is capped at the retention limit for your account.

Example:

{
    "workflows": [
        {
            "binding": "<BINDING_NAME>",
            "name": "<WORKFLOW_NAME>",
            "class_name": "<CLASS_NAME>",
        },
    ],
}

[[workflows]]
binding = "<BINDING_NAME>"
name = "<WORKFLOW_NAME>"
class_name = "<CLASS_NAME>"

Workflow exports

Note

Requires Wrangler 4.139.0 or above.

The exports field declares the Workflows this Worker defines, without a binding. Refer to Declare Workflows in exports.

Each Workflow entry in exports is keyed by the name of a class that extends WorkflowEntrypoint. The fields on each entry are:

type string required
For Workflow entries, set this to "workflow".
name string required
The name of the Workflow. Two entries in exports cannot use the same name.
limits object optional
steps number optional — The maximum number of steps a Workflow instance can run. Refer to Workflow step limits.
schedules string | string[] optional
One or more cron schedules that create new instances of this Workflow automatically. Refer to Schedule a Workflow directly.
default_retention object optional
How long to retain the state of instances of this Workflow after they finish. Accepts the same success_retention and error_retention fields as the workflows binding.

A Workflow can be declared both as a workflows binding and as an export. Both declarations must use the same class, and cannot set the same field to different values.

A workflows binding to a Workflow in another Worker cannot use the same name as a Workflow export in this Worker. Workflow names are unique per account.

Example:

{
    "exports": {
        "MyWorkflow": {
            "type": "workflow",
            "name": "my-workflow",
            "limits": {
                "steps": 25000,
            },
            "schedules": ["0 * * * *"],
        },
    },
}

[exports.MyWorkflow]
type = "workflow"
name = "my-workflow"
schedules = [ "0 * * * *" ]

[exports.MyWorkflow.limits]
  steps = 25_000

The Worker calls each Workflow declared in exports through ctx.exports, keyed by class name.

Assets

Static assets allows developers to run front-end websites on Workers. You can configure the directory of assets, an optional runtime binding, and routing configuration options.

You can only configure one collection of assets per Worker.

The following options are available under the assets key.

directory string optional
Folder of static assets to be served.
Not required if you're using the Cloudflare Vite plugin, which will automatically point to the client build output.
binding string optional
The binding name used to refer to the assets. Optional, and only useful when a Worker script is set with main.
run_worker_first boolean | string[] optional, defaults to false
Controls whether static assets are fetched directly, or a Worker script is invoked. Can be a boolean ( true/ false) or an array of route pattern strings with support for glob patterns ( *) and exception patterns ( ! prefix). Patterns must begin with / or !/. Supports at most 100 entries (duplicates count toward the limit). Learn more about fetching assets when using run_worker_first.
html_handling: "auto-trailing-slash" | "force-trailing-slash" | "drop-trailing-slash" | "none" optional, defaults to "auto-trailing-slash"
Determines the redirects and rewrites of requests for HTML content. Learn more about the various options in assets routing.
not_found_handling: "single-page-application" | "404-page" | "none" optional, defaults to "none"
Determines the handling of requests that do not map to an asset. Learn more about the various options for routing behavior.

Example:

{
    "assets": {
        "directory": "./public",
        "binding": "ASSETS",
        "html_handling": "force-trailing-slash",
        "not_found_handling": "404-page",
    },
}

[assets]
directory = "./public"
binding = "ASSETS"
html_handling = "force-trailing-slash"
not_found_handling = "404-page"

You can also configure run_worker_first with an array of route patterns:

{
    "assets": {
        "directory": "./public",
        "binding": "ASSETS",
        "run_worker_first": [
            "/api/*", // API calls go to Worker first
            "!/api/docs/*", // EXCEPTION: For /api/docs/*, try static assets first
        ],
    },
}

[assets]
directory = "./public"
binding = "ASSETS"
run_worker_first = [ "/api/*", "!/api/docs/*" ]

Containers

You can define Containers to run alongside your Worker using the containers field.

Each Container application has a scheduling policy that determines whether image and instance configuration is managed centrally or supplied by Durable Object code at runtime. The policy is immutable after the application is created.

Note

Each Container application must link to a Durable Object defined in the same Worker. Set class_name on the Container entry, or set name and reference that name from exports.<Class>.container. Configure exactly one of these linkage directions.

`default` scheduling policy

The default policy stores the image and instance configuration on the Container application and manages deployments as rollouts. It is used when scheduling_policy is omitted or set to "default".

The following options are available:

Configuration (17)·续3

Configuration (17)·续3

Vectorize indexes

Service bindings

Static assets

Analytics Engine Datasets

Analytics SQL

mTLS Certificates

Workers AI

Workflows

Workflow exports

Assets

Containers

default scheduling policy

`default` scheduling policy