Cloudflare Docs
Workers
Visit Workers on GitHub
Set theme to dark (⇧+D)

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.

  • name string required

    • The name of your Worker. Alphanumeric and dashes only.
  • main string required

    • The path to the entrypoint of your Worker that will be executed. For example: ./src/index.ts.
  • compatibility_date string required

    • 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.
  • account_id string optional

    • This is the ID of the account associated with your zone. You might have more than one account, so make sure to use the ID of the account associated with the zone/route you provide, if you provide one. It can also be specified through the CLOUDFLARE_ACCOUNT_ID environment variable.
  • compatibility_flags string[] optional

    • A list of flags that enable features from upcoming features of the Workers runtime, usually used together with compatibility_date. Refer to compatibility dates.
  • workers_dev boolean optional

    • Enables use of *.workers.dev subdomain to test and deploy your Worker. If you have a Worker that is only for scheduled events, you can set this to false. Defaults to true.
  • route Route optional

    • A route that your Worker should be published to. Only one of routes or route is required. Refer to types of routes.
  • routes Route[] optional

    • An array of routes that your Worker should be published to. Only one of routes or route is required. Refer to types of routes.
  • tsconfig string optional

    • Path to a custom tsconfig.
  • triggers object optional

    • Cron definitions to trigger a Worker’s scheduled function. Refer to triggers.
  • usage_model string optional

  • rules Rule optional

    • An ordered list of rules that define which modules to import, and what type to import them as. You will need to specify rules to use Text, Data and CompiledWasm modules, or when you wish to have a .js file be treated as an ESModule instead of CommonJS.
  • build Build optional

    • Configures a custom build step to be run by Wrangler when building your Worker. Refer to Custom builds.
  • no_bundle boolean optional

    • Skip internal build steps and directly publish your Worker script. You must have a plain JavaScript Worker with no dependencies.
  • minify boolean optional

    • Minify the Worker script before uploading.
  • node_compat boolean optional

  • send_metrics boolean optional

    • Whether Wrangler should send usage metrics to Cloudflare for this project.
  • keep_vars boolean optional

    • Whether Wrangler should keep variables configured in the dashboard on publish. Refer to source of truth.
  • logpush boolean optional

    • Enables Workers Trace Events Logpush for a Worker. Any scripts with this property will automatically get picked up by the Workers Logpush job configured for your account. Defaults to false.

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

  • define Record<string, string> optional

    • A map of values to substitute when deploying your Worker.
  • vars object optional

    • A map of environment variables to set when deploying your Worker.
  • 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.
  • services object optional

    • A list of service bindings that your Worker should be bound to. Refer to service bindings.

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

  • pattern string required

    • The pattern that your Worker can be run on, for example,"example.com/*".
  • zone_id string required

  • custom_domain boolean optional

    • Whether the Worker should be on a Custom Domain as opposed to a route. Defaults to false. Refer to Custom Domains.

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

​​ 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.
  • custom_domain boolean optional

    • Whether the Worker should be on a Custom Domain as opposed to a route. Defaults to false. Refer to Custom Domains.

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.

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

  • cron string[] required

    • An array of 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.

  • 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:

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.

  • 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 script where the Durable Object is defined, if it is external to this Worker.
  • environment string optional

    • The service environment of the script_name to bind to.

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.

  • tag string required

    • A unique identifier for this migration.
  • new_classes string[] optional

    • The new Durable Objects being defined.
  • renamed_classes {from: string, to: string}[] optional

    • The Durable Objects being renamed.
  • deleted_classes string[] optional

    • The Durable Objects being removed.

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.

  • 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 ID of the KV namespace used during wrangler dev.

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.

  • binding string required

    • The binding name used to refer to the R2 bucket.
  • bucket_name string required

    • The name of this R2 bucket.
  • preview_bucket_name string optional

    • The preview name of this R2 bucket used during wrangler dev.

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.

  • binding string required

    • The binding name used to refer to the bound service.
  • service string required

    • The name of the service.
  • environment string optional

    • The environment of the service (for example, production, staging, etc). Refer to Service Environments.

Example:

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

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

  • type string required

    • The type of asset. Must be one of: ESModule, CommonJS, CompiledWasm, Text or Data.
  • globs string[] required

  • fallthrough boolean optional

    • When set to true on a rule, this allows you to have multiple rules for the same Type.

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.

  • ip string optional

    • IP address for the local dev server to listen on. Defaults to localhost.
  • port number optional

    • Port for the local dev server to listen on. Defaults to 8787.
  • local_protocol string optional

    • Protocol that local dev server listens to requests on. Defaults to http.
  • upstream_protocol string optional

    • Protocol that the local dev server forwards requests on. Defaults to https.
  • host string optional

    • Host to forward requests to, defaults to the host of the first route of the Worker.

Example:

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

​​ Environmental variables

When developing locally, you can create a .dev.vars file in the project root which allows you 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 file should be formatted like a dotenv file, such as KEY=VALUE.

.dev.vars
SECRET_KEY = "value"

​​ Node compatibility

You can add experimental Node compatibility to your Worker by adding the node_compat key to your wrangler.toml or by passing the --node-compat flag to wrangler.

It is not possible to polyfill all Node APIs or behaviours, but it is possible to polyfill some of them. APIs such as fs cannot be replicated as Workers has no concept of a filesystem.

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

​​ Workers Sites

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

  • bucket string required

    • The directory containing your static assets. It must be a path relative to your wrangler.toml file.
  • include number optional

    • An exclusive list of .gitignore-style patterns that match file or directory names from your bucket location. Only matched items will be uploaded.
  • exclude string optional

    • A list of .gitignore-style patterns that match files or directories in your bucket that should be excluded from uploads.

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

It is a recommended best practice to treat wrangler.toml as a source of truth for your Worker configuration, and avoid making changes via the Cloudflare dashboard. This allows you to treat wrangler.toml as a form of Infrastructure as Code.

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. Currently, there is no way to disable this behaviour.

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