Skip to content
Cloudflare Docs
Workers
Cloudflare Docs
Workers
Search icon (depiction of a magnifying glass)
GitHub icon
Visit Workers on GitHub
Set theme to dark (⇧+D)

Configuration

Background

Your project will need some configuration before you can publish your worker. These values are stored in a wrangler.toml file. You will need to manually edit this file to add these values before you can publish.

Environments

Top level configuration: the configuration values you specify at the top of your wrangler.toml will be applied to all environments if not otherwise specified in the environment.

Environment configuration (optional): the configuration values you specify under an [env.name] in your wrangler.toml

Environments is a feature that allows you to deploy the same project to multiple places under multiple names. These environments are utilized with the --env or -e flag on the commands that are deploying live Worker scripts:

  • build
  • preview
  • publish

Some environment properties can be inherited from the top level configuration, but values in an environment will always override those at the top level.

Keys

Keys to configure per project in your wrangler.toml.

Top level only: required to be configured at the top level of your wrangler.toml only; multiple environments on the same project must share this property

Inherited: Can be configured at the top level and/or environment. If the property is defined only at the top level, the environment will use the property value from the top level. If the property is defined in the environment, the environment value will override the top level value.

Not inherited: Must be defined for every environment individually.

  • name inherited required

    • The name of your Worker script. If inherited, your environment name with be appended to the top level.

  • type top level required

    • Specifies how wrangler build will build your project. There are currently three options (webpack, javascript, and rust).

  • zone_id inherited optional

    • This is the ID of the "zone" or domain you want to run your script on. It can also be specified through the CF_ZONE_ID environment variable. This key is optional if you are using only a workers.dev subdomain.

  • account_id inherited required

    • 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_id you provide, if you provide one. It can also be specified through the CF_ACCOUNT_ID environment variable.

  • workers_dev inherited optional

  • route not inherited optional

    • A route, specified by URL pattern, on your zone that you would like to run your Worker on.
      route = "http://example.com/*". A route OR routes key is only required if you are not using a workers.dev subdomain.

  • routes not inherited optional

    • A list of routes you’d like to use your worker on. These follow exactly the same rules a route, but you can specify a list of them.
      routes = ["http://example.com/hello", "http://example.com/goodbye"]. A route OR routes key is only required if you are not using a workers.dev subdomain.

  • webpack_config inherited optional

    • This is the path to a custom webpack configuration file for your worker. You must specify this field to use a custom webpack configuration, otherwise Wrangler will use a default configuration for you. Visit the Wrangler webpack page for more information.

  • vars not inherited optional

    • An object containing text variables that can be directly accessed in a Worker script.

  • kv_namespaces not inherited optional

    • These specify any Workers KV Namespaces you want to access from inside your Worker.

  • site inherited optional

    • Determines the local folder to upload and serve from a Worker

  • dev not inherited optional

    • Arguments for wrangler dev, configure local server

  • triggers inherited optional

    • Configures cron triggers for executing a Worker on a schedule

vars

Values to use in your Worker script as a text environment variables.

Usage:

vars = { FOO = "some value", BAR = "some other string" }

  • FOO

    • The variable to access in your Worker script

  • "some value"

    • The string value the variable resolves to

kv_namespaces

KV namespaces bind to your Worker and reference in your script.

Usage:

kv_namespaces = [  { binding = "FOO", id = "0f2ac74b498b48028cb68387c421e279", preview_id = "6a1ddb03f3ec250963f0a1e46820076f" },  { binding = "BAR", id = "068c101e168d03c65bddf4ba75150fb0", preview_id = "fb69528dbc7336525313f2e8c3b17db0" }]

  • binding required

    • After you’ve created a namespace, you must bind it to your Worker so it is accessible from within the Worker script via a variable name you specify.

  • id required

    • The ID of the namespace you wish to bind to the Worker’s global scope when it is deployed. Required for wrangler publish.

  • preview_id required

    • The ID of the namespace you wish to bind to the Worker’s global scope when it is previewed . Required for wrangler dev and wrangler preview.

site

A Workers Site generated with wrangler generate --site or wrangler init --site.

Usage:

[site]bucket = "./public"entry-point = "workers-site"

  • bucket required

    • The directory containing your static assets, path relative to your wrangler.toml. Example: bucket = "./public"

  • entry-point optional

    • The location of your Worker script, default is workers-site. Example: entry-point = "./workers-site"

  • include optional

    • A list of gitignore-style patterns for files or directories in bucket you exclusively want to upload. Example: include = ["upload_dir"]

  • exclude optional

    • A list of gitignore-style patterns for files or directories in bucket you want to exclude from uploads. Example: exclude = ["ignore_dir"]

To learn more about the optional include and exclude fields, visit Ignoring Subsets of Static Assets.

You can also define your site using alternative TOML syntax.

Storage Limits

For very exceptionally large pages, Workers Sites might not work for you. There is a 10MB limit per page or file. Additionally, Wrangler will create an asset manifest for your files that will count towards your script’s size limit. If you have too many files, you may not be able to use Workers Sites.

Ignoring Subsets of Static Assets

Workers Sites require Wrangler — make sure to be on the latest version — and the Workers Bundled plan.

There are cases where users may not want to upload certain static assets to their Workers Sites. In this case, Workers Sites can also be configured to ignore certain files or directories using logic similar to Cargo’s optional include and exclude fields. This means that we use gitignore semantics when declaring which directory entries to include or ignore in uploads.

Exclusively including files/directories

If you want to include only a certain set of files or directories in your bucket, you can add an include field to your [site] section of wrangler.toml:

[site]bucket = "./public"entry-point = "workers-site"include = ["included_dir"] # must be an array.

Wrangler will only upload files or directories matching the patterns in the include array.

Excluding files/directories

If you want to exclude files or directories in your bucket, you can add an exclude field to your [site] section of wrangler.toml:

[site]bucket = "./public"entry-point = "workers-site"exclude = ["excluded_dir"] # must be an array.

Wrangler will ignore files or directories matching the patterns in the exclude array when uploading assets to Workers KV.

Include > Exclude

If you provide both include and exclude fields, the include field will be used and the exclude field will be ignored.

Default ignored entries

Wrangler will always ignore:

  • node_modules
  • Hidden files and directories
  • Symlinks

More about include/exclude patterns

You can learn more about the standard patterns used for include and exclude in the gitignore documentation.

Customizing your Build

Workers Sites projects use webpack by default. You can bring your own webpack config, however it is important to be cognizant of your entry and context settings.

triggers

A set of cron triggers used to call a Worker on a schedule.

Usage:

[triggers]crons = ["0 0 * JAN-JUN FRI", "0 0 LW JUL-DEC *"]
  • crons optional
    • A set of cron expressions, where each expression is a separate schedule to run the Worker on.

dev

Arguments for wrangler dev can be configured here so you don't have to repeatedly pass them.

Usage:

[dev]port=9000local_protocol="https"

  • ip optional

    • Ip for local wrangler dev server to listen on, defaults to 127.0.0.1

  • port optional

    • Port for local wrangler dev server to listen on, defaults to 8787

  • local_protocol optional

    • Protocol that local wrangler dev server listen to requests on, defaults to http

  • upstream_protocol optional

    • Protocol that wrangler dev forwards requests on, defaults to https

Example

To illustrate how these levels are applied, here is a wrangler.toml using multiple environments:

wrangler.toml# top level configurationtype = "webpack"name = "my-worker-dev"account_id = "12345678901234567890"zone_id = "09876543210987654321"route = "dev.example.com/*"kv_namespaces = [  { binding = "FOO", id = "b941aabb520e61dcaaeaa64b4d8f8358", preview_id = "03c8c8dd3b032b0528f6547d0e1a83f3" },  { binding = "BAR", id = "90e6f6abd5b4f981c748c532844461ae", preview_id = "e5011a026c5032c09af62c55ecc3f438" }]
[site]bucket = "./public"entry-point = "workers-site"
[dev]ip = "0.0.0.0"port = 9000local_protocol="http"upstream_protocol="https"
# environment configuration[env.staging]name = "my-worker-staging"route = "staging.example.com/*"kv_namespaces = [  { binding = "FOO", id = "0f2ac74b498b48028cb68387c421e279" },  { binding = "BAR", id = "068c101e168d03c65bddf4ba75150fb0" }]
# environment configuration[env.production]workers_dev= truekv_namespaces = [  { binding = "FOO", id = "0d2ac74b498b48028cb68387c421e233" },  { binding = "BAR", id = "0d8c101e168d03c65bddf4ba75150f33" }]