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 will be appended to the top level.
type top level required
- Specifies how wrangler build will build your project. There are three options: javascript, webpack, and rust. javascript checks for a build command specified in the [build] section, webpack builds your project using webpack v4, and rust compiles the Rust in your project to WebAssembly.

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.
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.
workers_dev inherited optional
- This is a boolean flag that specifies if your worker will be deployed to your workers.dev subdomain. If omitted defaults to false.
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
usage_model top level optional
- Specifies the Usage Model for your Worker. There are two options - bundled and unbound. For newly created Workers, if the Usage Model is omitted it will be set to the default Usage Model set on the account. For existing Workers, if the Usage Model is omitted, it will be set to the Usage Model configured in the dashboard for that Worker.
build inherited optional
- Allows configuring a custom build step to be run by wrangler when building your worker. See the custom builds documentation for more details.

vars

Values to use in your Worker script as 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 may be referenced 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 25MB 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 Sites 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.

You can also use the [build] section with Workers Sites, as long as your build step will resolve dependencies in node_modules. See the custom builds section for more information.

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

build

Customize the command used to build your project. There are two configurations based on the format of your Worker: service-worker and modules (in beta).

Service Workers

This section is for customizing Workers with the service-worker format. If you're not familar, these are Workers that use addEventListener and look like the following:

addEventListener('fetch', function (event) {  event.respondWith(new Response("I'm a service Worker!"))})

Usage:

[build]command = "npm install && npm run build"[build.upload]format = "service-worker"

`[build]`

command optional
- The command to build your project which is executed in the shell of your machine: sh for Linux and MacOS, and cmd for Windows. You can also use shell operators such as && and |
cwd optional
- The working directory for commands, defaults to the project root directory
watch_dir optional
- The directory to watch for changes while using wrangler dev, defaults to "src" relative to the project root directory

`[build.upload]`

- `format` required

- The format of the Worker script, must be "service-worker"

Modules

Cloudflare Workers now supports uploading scripts as a collection of modules, instead of a single file. Scripts uploaded in this fashion are written a bit differently -- they export their event handlers instead of registering them using the global addEventListener('fetch', handler...). Modules also receive bindings (like KV Namespaces, Config Vargs, and Secrets) as arguments to their handlers, rather than global variables. Uploaded modules can import (for ES Modules) or require() (for CommonJS modules) other uploaded modules.

import html from './index.html'
export default {  // * request is the same as `event.request` from the service worker format  // * waitUntil() and passThroughOnException() are accessible from `ctx` instead of `event` from the service worker format  // * env is where bindings like KV namespaces, Durable Object namespaces, Config variables, and Secrets  // are exposed, instead of them being placed in global scope.  async fetch(request, env, ctx) {    const headers = { 'Content-Type': 'text/html;charset=UTF-8' }    return new Response(html, { headers })  }}

In the future, Modules will become the default format for writing Workers scripts. Until then, we are still working on "full" support, so consider this as a beta feature.

To create a Workers project using wrangler and Modules, you'll need to add a [build] section:

[build]command = "npm install && npm run build"
[build.upload]format = "modules"main = "./worker.mjs"

`[build]`

command optional
- The command to build your project which is executed in the shell of your machine: sh for Linux and MacOS, and cmd for Windows. You can also use shell operators such as && and ||
cwd optional
- The working directory for commands, defaults to the project root directory
watch_dir optional
- The directory to watch for changes while using wrangler dev, defaults to "src" relative to the project root directory

`[build.upload]`

format required
- The format of the Workers script, must be "modules"
dir optional
- The directory you wish to upload your modules from, defaults to "dist" relative to the project root directory
main required
- The relative path of the main module from dir, including the ./ prefix. The main module must be an ES module. For projects with a build script, this usually refers to the output of your JavaScript bundler.

rules optional
- An ordered list of rules that define which modules to import, and what type to import them as. You'll 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.
- Defaults:
```
[build.upload]format = "modules"main = "./worker.mjs"
# You don't need to include these default rules in your `wrangler.toml`, they are implicit.# The default rules are treated as the last two rules in the list.
[[build.upload.rules]]type = "ESModule"globs = ["**/*.mjs"]
[[build.upload.rules]]type = "CommonJS"globs = ["**/*.js", "**/*.cjs"]
```
- - type required
    - The module type, see the table below for acceptable options
    type JavaScript type
    ESModule -
    CommonJS -
    Text String
    Data ArrayBuffer
    CompiledWasm WebAssembly.Module
  - globs required
    - Unix-style glob rules that are used to determine the module type to use for a given file in dir. Globs are matched against the module's relative path from build.upload.dir without the ./ prefix. Rules are evaluated in order, starting at the top.
  - fallthrough optional
    - This option allows further rules for this module type to be considered if set to true. If not specified or set to false, further rules for this module type will be ignored.

`type`	JavaScript type
ESModule	-
CommonJS	-
Text	`String`
Data	`ArrayBuffer`
CompiledWasm	`WebAssembly.Module`

Example

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

wrangler.toml# top level configurationtype = "javascript"name = "my-worker-dev"account_id = "12345678901234567890"zone_id = "09876543210987654321"route = "dev.example.com/*"usage_model = "unbound"kv_namespaces = [  { binding = "FOO", id = "b941aabb520e61dcaaeaa64b4d8f8358", preview_id = "03c8c8dd3b032b0528f6547d0e1a83f3" },  { binding = "BAR", id = "90e6f6abd5b4f981c748c532844461ae", preview_id = "e5011a026c5032c09af62c55ecc3f438" }]
[build]command = "webpack"[build.upload]format = "service-worker"
[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" }]

Configuration

​Background

​Environments

​Keys

​vars

​kv_namespaces

​site

​Storage Limits

​Ignoring Subsets of Static Assets

​Exclusively including files/directories

​Excluding files/directories

​Include > Exclude

​Default ignored entries

​More about include/exclude patterns

​Customizing your Sites Build

​triggers

​dev

​build

​Service Workers

​[build]

​[build.upload]

​Modules

​[build]

​[build.upload]

​Example

Background

Environments

Keys

vars

kv_namespaces

site

Storage Limits

Ignoring Subsets of Static Assets

Exclusively including files/directories

Excluding files/directories

Include > Exclude

Default ignored entries

More about include/exclude patterns

Customizing your Sites Build

triggers

dev

build

Service Workers

`[build]`

`[build.upload]`

Modules

`[build]`

`[build.upload]`

Example