Configuration (17)·续1

  • define Record<string, string> optional
  • A map of values to substitute when deploying your Worker.
  • If you're using the Cloudflare Vite plugin, define is replaced by Vite's define ↗︎.
  • vars object optional
  • A map of environment variables to set when deploying your Worker. Refer to Environment variables.
  • durable_objects object optional
  • A list of Durable Objects that your Worker should be bound to. Refer to Durable Objects.
  • kv_namespaces object optional
  • A list of KV namespaces that your Worker should be bound to. Refer to KV namespaces.
  • r2_buckets object optional
  • A list of R2 buckets that your Worker should be bound to. Refer to R2 buckets.
  • analytics object optional
  • An Analytics SQL binding. Refer to Analytics SQL.
  • ai_search_namespaces object optional
  • A list of AI Search namespaces that your Worker should be bound to. Refer to AI Search namespaces.
  • ai_search object optional
  • A list of AI Search instance bindings bound directly to pre-existing instances in the default namespace. Refer to AI Search instances.
  • vectorize object optional
  • A list of Vectorize indexes that your Worker should be bound to. Refer to Vectorize indexes.
  • services object optional
  • A list of service bindings that your Worker should be bound to. Refer to service bindings.
  • queues object optional
  • A list of Queue producers and consumers that your Worker should be bound to. Refer to Queues.
  • workflows object optional
  • A list of Workflows that your Worker should be bound to. Refer to Workflows.
  • tail_consumers object optional
  • A list of the Tail Workers your Worker sends data to. Refer to Tail Workers.
  • secrets object optional
  • Declares the secret names your Worker requires. Used for validation during local development and deploy, and as the source of truth for type generation. Refer to Secrets.
  • required string[] optional — A list of secret names that must be set to deploy your Worker.
  • secrets_store_secrets object optional
  • A list of Secrets Store bindings that your worker should be bound to. Refer to Secrets Store.

Types of routes

There are three types of routes: Custom Domains, routes, and workers.dev.

Custom Domains

Custom Domains allow you to connect your Worker to a domain or subdomain, without having to make changes to your DNS settings or perform any certificate management.

  • pattern string required
  • The pattern that your Worker should be run on, for example, "example.com".
  • custom_domain boolean optional
  • Whether the Worker should be on a Custom Domain as opposed to a route. Defaults to false.

Example:

{
    "routes": [
        {
            "pattern": "shop.example.com",
            "custom_domain": true,
        },
    ],
}

[[routes]]
pattern = "shop.example.com"
custom_domain = true

Routes

Routes allow users to map a URL pattern to a Worker. A route can be configured as a zone ID route, a zone name route, or a simple route.

Zone ID route

  • pattern string required
  • The pattern that your Worker can be run on, for example, "example.com/*".
  • zone_id string required
  • The ID of the zone that your pattern is associated with. Refer to Find zone and account IDs.

Example:

{
    "routes": [
        {
            "pattern": "subdomain.example.com/*",
            "zone_id": "<YOUR_ZONE_ID>",
        },
    ],
}

[[routes]]
pattern = "subdomain.example.com/*"
zone_id = "<YOUR_ZONE_ID>"

Zone name route

  • pattern string required
  • The pattern that your Worker should be run on, for example, "example.com/*".
  • zone_name string required
  • The name of the zone that your pattern is associated with. If you are using API tokens, this will require the Account scope.

Example:

{
    "routes": [
        {
            "pattern": "subdomain.example.com/*",
            "zone_name": "example.com",
        },
    ],
}

[[routes]]
pattern = "subdomain.example.com/*"
zone_name = "example.com"

Simple route

This is a simple route that only requires a pattern.

Example:

{
    "route": "example.com/*",
}

route = "example.com/*"

workers.dev

Cloudflare Workers accounts come with a workers.dev subdomain that is configurable in the Cloudflare dashboard.

  • workers_dev boolean optional
  • Whether the Worker runs on a custom workers.dev account subdomain. Defaults to true when the configuration has no route or routes, and false otherwise. To keep the workers.dev URL alongside routes, set workers_dev to true. For more information, refer to workers.dev.
{
    "workers_dev": false,
}

workers_dev = false

Triggers

Triggers allow you to define the cron expression to invoke your Worker's scheduled function. Refer to Supported cron expressions.

  • crons string[] required
  • An array of cron expressions.
  • To disable a Cron Trigger, set crons = []. Commenting out the crons key will not disable a Cron Trigger.

Example:

{
    "triggers": {
        "crons": ["* * * * *"],
    },
}

[triggers]
crons = [ "* * * * *" ]

Observability

The Observability setting allows you to automatically ingest, store, filter, and analyze logging data emitted from Cloudflare Workers directly from your Cloudflare Worker's dashboard.

  • enabled boolean optional
  • Shorthand for logs.enabled. When set to true on a Worker, logs for the Worker are persisted. Defaults to true for all new Workers.
  • logs.enabled boolean optional
  • Whether logs for the Worker are persisted.
  • head_sampling_rate number optional
  • A number between 0 and 1, where 0 indicates zero out of one hundred requests are logged, and 1 indicates every request is logged. If head_sampling_rate is unspecified, it is configured to a default value of 1 (100%). Read more about head-based sampling.

Example:

{
    "observability": {
        "enabled": true,
        "head_sampling_rate": 0.1, // 10% of requests are logged
    },
}

[observability]
enabled = true
head_sampling_rate = 0.1

Issues

Requires Wrangler 4.134.0 or later.

Set observability.issues.enabled to true to detect and group production failures for a Worker. Set it to false and deploy the Worker to stop detecting new failures. Refer to Workers Issues for supported signals, retention, and behavior.

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "observability": {
    "issues": {
      "enabled": true
    }
  }
}

[observability.issues]
enabled = true

Custom builds

Note

Not applicable if you're using the Cloudflare Vite plugin.

You can configure a custom build step that will be run before your Worker is deployed. Refer to Custom builds.

  • command string optional
  • The command used to build your Worker. On Linux and macOS, the command is executed in the sh shell and the cmd shell for Windows. The && and || shell operators may be used.
  • cwd string optional
  • The directory in which the command is executed.
  • watch_dir string | string[] optional
  • The directory to watch for changes while using wrangler dev. Defaults to the current working directory.

Example:

{
    "build": {
        "command": "npm run build",
        "cwd": "build_cwd",
        "watch_dir": "build_watch_dir",
    },
}

[build]
command = "npm run build"
cwd = "build_cwd"
watch_dir = "build_watch_dir"

Limits

You can impose limits on your Worker's behavior at runtime. Limits are only supported for the Standard Usage Model. Limits are only enforced when deployed to Cloudflare's network, not in local development. The CPU limit can be set to a maximum of 300,000 milliseconds (5 minutes).

Each isolate has some built-in flexibility to allow for cases where your Worker infrequently runs over the configured limit. If your Worker starts hitting the limit consistently, its execution will be terminated according to the limit configured.

  • cpu_ms number optional
  • The maximum CPU time allowed per invocation, in milliseconds.
  • subrequests number optional
  • The maximum number of subrequests allowed per invocation. This value defaults to 50 for free accounts and 10,000 for paid accounts. The free account maximum is 50 and the paid account maximum is 10,000,000. Refer to subrequest limits for more information.

Example:

{
    "limits": {
        "cpu_ms": 100,
        "subrequests": 150,
    },
}

[limits]
cpu_ms = 100
subrequests = 150

Bindings

Browser Run

The Workers Browser Run API allows developers to programmatically control and interact with a headless browser instance and create automation flows for their applications and products.

A browser binding will provide your Worker with an authenticated endpoint to interact with a dedicated Chromium browser instance.

  • binding string required
  • The binding name used to refer to the browser binding. The value (string) you set will be used to reference this headless browser in your Worker. The binding must be a valid JavaScript variable name ↗︎. For example, binding = "HEAD_LESS" or binding = "simulatedBrowser" would both be valid names for the binding.

Example:

{
    "browser": {
        "binding": "<BINDING_NAME>",
    },
}

[browser]
binding = "<BINDING_NAME>"

D1 databases

D1 is Cloudflare's serverless SQL database. A Worker can query a D1 database (or databases) by creating a binding to each database for D1 Workers Binding API.

To bind D1 databases to your Worker, assign an array of the below object to the [[d1_databases]] key.

  • binding string required
  • The binding name used to refer to the D1 database. The value (string) you set will be used to reference this database in your Worker. The binding must be a valid JavaScript variable name ↗︎. For example, binding = "MY_DB" or binding = "productionDB" would both be valid names for the binding.
  • database_name string required
  • The name of the database. This is a human-readable name that allows you to distinguish between different databases, and is set when you first create the database.
  • database_id string required
  • The ID of the database. The database ID is available when you first use wrangler d1 create or when you call wrangler d1 list, and uniquely identifies your database.
  • preview_database_id string optional
  • The preview ID of this D1 database. If provided, wrangler dev uses this ID. Otherwise, it uses database_id. This option is recommended when using wrangler dev --remote to avoid using your production database.
  • migrations_dir string optional
  • The migration directory containing the migration files. By default, wrangler d1 migrations create creates a folder named migrations. You can use migrations_dir to specify a different folder containing the migration files (for example, if you have a mono-repo setup, and want to use a single D1 instance across your apps/packages).
  • For more information, refer to D1 Wrangler migrations commands and D1 migrations.
  • migrations_pattern string optional
  • A glob pattern (relative to your Wrangler config file) used to discover migration files. Defaults to migrations/*.sql.
  • Use this to opt in to nested layouts produced by ORMs like Drizzle (for example, migrations/*/migration.sql).
  • When migrations_pattern is set, migrations_dir must also be set, and migrations_pattern must start with whatever migrations_dir is set to. Each migration is recorded in the migrations table as a path relative to migrations_dir.

Note

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

Example:

{
    "d1_databases": [
        {
            "binding": "<BINDING_NAME>",
            "database_name": "<DATABASE_NAME>",
            "database_id": "<DATABASE_ID>",
        },
    ],
}

[[d1_databases]]
binding = "<BINDING_NAME>"
database_name = "<DATABASE_NAME>"
database_id = "<DATABASE_ID>"

Dispatch namespace bindings (Workers for Platforms)

Dispatch namespace bindings allow for communication between a dynamic dispatch Worker and a dispatch namespace. Dispatch namespace bindings are used in Workers for Platforms. Workers for Platforms helps you deploy serverless functions programmatically on behalf of your customers.

  • binding string required
  • The binding name. The value (string) you set will be used to reference this database in your Worker. The binding must be a valid JavaScript variable name ↗︎. For example, binding = "MY_NAMESPACE" or binding = "productionNamespace" would both be valid names for the binding.
  • namespace string required
  • The name of the dispatch namespace.
  • outbound object optional
  • service string required The name of the outbound Worker to bind to.
  • parameters array optional A list of parameters to pass data from your dynamic dispatch Worker to the outbound Worker.
{
    "dispatch_namespaces": [
        {
            "binding": "<BINDING_NAME>",
            "namespace": "<NAMESPACE_NAME>",
            "outbound": {
                "service": "<WORKER_NAME>",
                "parameters": ["params_object"],
            },
        },
    ],
}

[[dispatch_namespaces]]
binding = "<BINDING_NAME>"
namespace = "<NAMESPACE_NAME>"

[dispatch_namespaces.outbound]
  service = "<WORKER_NAME>"
  parameters = [ "params_object" ]

Durable Objects

Durable Objects provide low-latency coordination and consistent storage for the Workers platform.

To bind Durable Objects to your Worker, assign an array of the below object to the durable_objects.bindings key.