Configure wrangler.toml

Wrangler optionally uses a wrangler.toml configuration file to customize the development and publishing setup for a Worker.

It is best practice to treat wrangler.toml as the source of truth for configuring a Worker.

​​ Sample wrangler.toml configuration

wrangler.toml
# Top-level configuration
name = "my-worker"
main = "src/index.js"
compatibility_date = "2022-07-12"

workers_dev = false
route = { pattern = "example.org/*", zone_name = "example.org" }

kv_namespaces = [
  { binding = "<MY_NAMESPACE>", id = "<KV_ID>" }
]

[env.staging]
name = "my-worker-staging"
route = { pattern = "staging.example.org/*", zone_name = "example.org" }

kv_namespaces = [
  { binding = "<MY_NAMESPACE>", id = "<STAGING_KV_ID>" }
]

​​ Environments

The configuration for a Worker can become complex when you define different environments, and each environment has its own configuration. There is a default (top-level) environment and named environments that provide environment-specific configuration.

These are defined under [env.name] keys, such as [env.staging] which you can then preview or publish with the -e / --env flag in the wrangler commands like wrangler publish --env staging.

The majority of keys are inheritable, meaning that top-level configuration can be used in environments. Bindings, such as vars or kv_namespaces, are not inheritable and need to be defined explicitly.

​​ Inheritable keys

Inheritable keys are configurable at the top-level, and can be inherited (or overridden) by environment-specific configuration.

​​ Non-inheritable keys

Non-inheritable keys are configurable at the top-level, but cannot be inherited by environments and must be specified for each environment.

​​ Types of routes

There are four types of routes.

​​ Simple route

This is a simple route that only requires a pattern.

Example: "example.com/*"

​​ Zone ID route

Example: { pattern = "example.com/*", zone_id = "foo" }

​​ Zone name route

Example: { pattern = "example.com/*", zone_name = "example.com" }

​​ Custom Domain route

This will use a Custom Domain as opposed to a route. Refer to Custom Domains.

Example:

wrangler.toml
route = { pattern = "example.com", custom_domain = true }

​​ Triggers

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

Example:

wrangler.toml
[triggers]
crons = ["* * * * *"]

​​ Custom builds

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

Example:

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

​​ Bindings

​​ 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.

Example:

wrangler.toml
durable_objects.bindings = [
  { name = "<TEST_OBJECT>", class_name = "<TEST_CLASS>" }
]

​​ Migrations

When making changes to your Durable Object classes, you must perform a migration. Refer to Configuring Durable Object classes with migrations.

Example:

wrangler.toml
[[migrations]]
tag = ""
new_classes = [""]
renamed_classes = [{from = "DurableObjectExample", to = "UpdatedName" }]
deleted_classes = ["DeprecatedClass"]

​​ 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.

Example:

wrangler.toml
kv_namespaces = [
  { binding = "<TEST_NAMESPACE>", id = "<TEST_ID>" }
]

​​ 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.

Example:

wrangler.toml
r2_buckets  = [
  { binding = "<TEST_BUCKET>", bucket_name = "<TEST_BUCKET>"}
]

​​ 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.

Example:

wrangler.toml
services = [
  { binding = "<TEST_BINDING>", service = "<TEST_WORKER>" }
]

​​ 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.

Example:

wrangler.toml
analytics_engine_datasets = [
    { binding = "<BINDING_NAME>", dataset = "<DATASET_NAME>" }
]

​​ 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.

Example of a wrangler.toml configuration that includes an mTLS certificate binding:

wrangler.toml
mtls_certificates = [
    { binding = "<BINDING_NAME>", certificate_id = "<CERTIFICATE_ID>" }
]

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

​​ 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.toml file. However, each attribute must be on its own line:

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

​​ Bundling

You can bundle assets into your Worker using the rules key, making these assets available to be imported when your Worker is invoked. The rules key will be an array of the below object.

Example:

wrangler.toml
rules = [
  { type = "Text", globs = ["**/*.md"], fallthrough = true }
]

​​ Importing assets within a Worker

You can import and refer to these assets within your Worker, like so:

index.js
import markdown from './example.md'

export default {
  async fetch() {
    return new Response(markdown)
  }
}

​​ Local development settings

You can configure various aspects of local development, such as the local protocol or port.

Example:

wrangler.toml
[dev]
ip = "192.168.1.1"
port = 8080
local_protocol = "http"

​​ Environmental variables

When developing your Worker or Pages Functions, create a .dev.vars file in the root of your project to define variables that will be used when running wrangler dev or wrangler pages dev, as opposed to using another environment and [vars] in wrangler.toml. This works both in the local and remote development modes.

This file should be formatted like a dotenv file, such as KEY=VALUE.

.dev.vars
SECRET_KEY=value

​​ Node compatibility

If you depend on Node.js APIs, either directly in your own code or via a library you depend on, you can either use a subset of Node.js APIs available directly in the Workers runtime, or add polyfills for a subset of node.js APIs to your own code.

​​ Use runtime APIs directly

A growing subset of Node.js APIs are available directly as Runtime APIs, with no need to add polyfills to your own code. To enable these APIs in your Worker, add the nodejs_compat compatibility flag to your wrangler.toml:

wrangler.toml
compatibility_flags = [ "nodejs_compat" ]

​​ Add polyfills using Wrangler

Add polyfills for subset of Node.js APIs to your Worker by adding the node_compat key to your wrangler.toml or by passing the --node-compat flag to wrangler.

wrangler.toml
node_compat = true

It is not possible to polyfill all Node APIs or behaviors, but it is possible to polyfill some of them.

This is currently powered by @esbuild-plugins/node-globals-polyfill which in itself is powered by rollup-plugin-node-polyfills Open external link .

​​ Workers Sites

Workers Sites allows you to host static websites, or dynamic websites using frameworks like Vue or React, on Workers.

Example:

wrangler.toml
[site]
bucket = "./public"
include = ["upload_dir"]
exclude = ["ignore_dir"]

​​ Proxy support

Corporate networks will often have proxies on their networks and this can sometimes cause connectivity issues. To configure Wrangler with the appropriate proxy details, use the below environmental variables:

• https_proxy
• HTTPS_PROXY
• http_proxy
• HTTP_PROXY

To configure this on macOS, add HTTP_PROXY=http://<YOUR_PROXY_HOST>:<YOUR_PROXY_PORT> before your Wrangler commands.

Example:

$ HTTP_PROXY=http://localhost:8080 wrangler dev

If your IT team has configured your computer’s proxy settings, be aware that the first non-empty environment variable in this list will be used when Wrangler makes outgoing requests.

For example, if both https_proxy and http_proxy are set, Wrangler will only use https_proxy for outgoing requests.

​​ Source of truth

We recommend treating your wrangler.toml file as the source of truth for your Worker configuration, and to avoid making changes to your Worker via the Cloudflare dashboard if you are using Wrangler.

If you need to make changes to your Worker from the Cloudflare dashboard, the dashboard will generate a TOML snippet for you to copy into your wrangler.toml file, which will help ensure your wrangler.toml file is always up to date.

If you change your environment variables in the Cloudflare dashboard, Wrangler will override them the next time you deploy. If you want to disable this behavior, add keep_vars = true to your wrangler.toml.

If you change your routes in the dashboard, Wrangler will override them in the next deploy with the routes you have set in your wrangler.toml. To manage routes via the Cloudflare dashboard only, remove any route and routes keys from your wrangler.toml file. Then add workers_dev = false to your wrangler.toml file. For more information, refer to the Wrangler v1 deprecation guide.

Note that Wrangler will not delete your secrets (encrypted environment variables) unless you run wrangler secret delete <key>.