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.

​vars

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

Usage:

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

​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" }]

​site

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

Usage:

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

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 syntaxOpen external link.

​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 WranglerOpen external link — make sure to be on the latest version — and the Workers Bundled planOpen external link.

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 fieldsOpen external link. 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 documentationOpen external link.

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

​dev

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

Usage:

[dev]port=9000local_protocol="https"

​Example

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

# 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" }]