Configuration

​​ Background

Your project will need some configuration before you can publish your Worker. Configuration is done through changes to keys and values stored in a wrangler.toml file located in the root of your project directory. You must manually edit this file to edit your keys and values before you can publish.

​​ Environments

The top-level configuration is the collection of values you specify at the top of your wrangler.toml file. These values will be inherited by all environments, unless otherwise defined in the environment.

The layout of a top-level configuration in a wrangler.toml file is displayed below:

name = "your-worker"
type = "javascript"
account_id = "your-account-id"

# This field specifies that the Worker
# will be deployed to a *.workers.dev domain
workers_dev = true

# -- OR --

# These fields specify that the Worker
# will deploy to a custom domain
zone_id = "your-zone-id"
routes = ["example.com/*"]

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

Environments allow 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 Workers:

• build
• dev
• preview
• publish
• secret

Some environment properties can be inherited from the top-level configuration, but if new values are configured in an environment, they will always override those at the top level.

An example of an [env.name] configuration looks like this:

wrangler.toml
type = "javascript"

name = "your-worker"
account_id = "your-account-id"

[vars]
FOO = "default FOO value"
BAR = "default BAR value"

kv_namespaces = [
  { binding = "FOO", id = "1a...", preview_id = "1b..." }
]

[env.helloworld]
# Now adding configuration keys for the "helloworld" environment.
# These new values will override the top-level configuration.
name = "your-worker-helloworld"
account_id = "your-other-account-id"

[vars]
FOO = "env-helloworld FOO value"
BAR = "env-helloworld BAR value"

kv_namespaces = [
  # Redeclare kv namespace bindings for each environment
  # NOTE: In this case, passing new IDs because new `account_id` value.
  { binding = "FOO", id = "888...", preview_id = "999..." }
]

To deploy this example Worker to the helloworld environment, you would run wrangler publish --env helloworld.

​​ Keys

There are three types of keys in a wrangler.toml file:

• Top level only keys are required to be configured at the top level of your wrangler.toml file only; multiple environments on the same project must share this key’s value.

• Inherited keys can be configured at the top level and/or environment. If the key is defined only at the top level, the environment will use the key’s value from the top level. If the key is defined in the environment, the environment value will override the top-level value.

• Non-inherited keys must be defined for every environment individually.

​​ vars

The vars key defines a table of environment variables provided to your Worker script. All values are plaintext values.

Usage:

[vars]
FOO = "some value"
BAR = "some other string"

The table keys are available to your script as global variables, which will contain their associated values.

// Worker code:
console.log(FOO);
//=> "some value"

console.log(BAR);
//=> "some other string"

Alternatively, you can define vars using an inline table format. This style should not include any new lines to be considered a valid TOML configuration:

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

​​ kv_namespaces

kv_namespaces defines a list of KV namespace bindings for your Worker.

Usage:

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

Alternatively, you can define kv namespaces like so:

[[kv_namespaces]]
binding = "FOO"
preview_id = "abc456"
id = "abc123"

[[kv_namespaces]]
binding = "BAR"
preview_id = "xyz456"
id = "xyz123"

Much like environment variables and secrets, the binding names are available to your Worker as global variables.

// Worker script:

let value = await FOO.get("keyname");
//=> gets the value for "keyname" from
//=> the FOO variable, which points to
//=> the "0f2ac...e279" KV namespace

​​ site

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

Usage:

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

You can also define your site using an alternative TOML syntax Open external link .

​​ Storage Limits

For exceptionally large pages, Workers Sites may not be ideal. There is a 25 MiB 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.

​​ Exclusively including files/directories

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

[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, add an exclude field to your [site] section of your wrangler.toml file:

[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

Refer to the gitignore documentation Open external link to learn more about the standard matching patterns.

​​ Customizing your Sites Build

Workers Sites projects use webpack by default. Though you can bring your own webpack configuration, be aware 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. Refer to 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 *"]

​​ dev

Arguments for wrangler dev can be configured here so you do not have to repeatedly pass them.

Usage:

[dev]
port = 9000
local_protocol = "https"

​​ build

A custom build command for your project. There are two configurations based on the format of your Worker: service-worker and modules (beta).

​​ Service Workers

This section is for customizing Workers with the service-worker format. These Workers use addEventListener and look like the following:

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

Usage:

[build]
command = "npm install && npm run build"

[build.upload]
format = "service-worker"

​​ [build]

​​ [build.upload]

​​ Modules

Workers now supports the ES Modules syntax. Modules support in Cloudflare Workers is currently in beta. This format allows you to export a collection of files and/or modules, unlike the Service Worker format which requires a single file to be uploaded.

Module Workers export their event handlers instead of using addEventListener calls.

Modules receive all bindings (KV Namespaces, Environment Variables, and Secrets) as arguments to the exported handlers. With the Service Worker format, these bindings are available as global variables.

An uploaded module may import other uploaded ES Modules. If using the CommonJS format, you may require other uploaded CommonJS 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 });
  },
};

To create a Workers project using Wrangler and Modules, add a [build] section:

[build]
command = "npm install && npm run build"

[build.upload]
format = "modules"
main = "./worker.mjs"

​​ [build]

​​ [build.upload]

• 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 Open external link 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.