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 [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
- The name of your Worker script. If inherited, your environment name will be appended to the top level.
type
top level
- Specifies how
wrangler build
will build your project. There are currently three options —webpack
,javascript
, andrust
.javascript
skips building the project,webpack
builds your project with webpack, andrust
compiles the Rust in your project to WASM.
- Specifies how
zone_id
inherited
- 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.
- This is the ID of the "zone" or domain you want to run your script on. It can also be specified through the
account_id
inherited
- 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 theCF_ACCOUNT_ID
environment variable.
- 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
workers_dev
inherited
- 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
- A route, specified by URL pattern, on your zone that you would like to run your Worker on.
route = "http://example.com/*"
. Aroute
ORroutes
key is only required if you are not using a workers.dev subdomain.
- A route, specified by URL pattern, on your zone that you would like to run your Worker on.
routes
not inherited
- 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"]
. Aroute
ORroutes
key is only required if you are not using a workers.dev subdomain.
- A list of routes you’d like to use your worker on. These follow exactly the same rules a
webpack_config
inherited
- 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
- An object containing text variables that can be directly accessed in a Worker script.
kv_namespaces
not inherited
- These specify any Workers KV Namespaces you want to access from inside your Worker.
site
inherited
- Determines the local folder to upload and serve from a Worker
dev
not inherited
- Arguments for
wrangler dev
, configure local server
- Arguments for
triggers
inherited
- Configures cron triggers for executing a Worker on a schedule
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
- 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
- The ID of the namespace you wish to bind to the Worker’s global scope when it is deployed. Required for
wrangler publish
.
- The ID of the namespace you wish to bind to the Worker’s global scope when it is deployed. Required for
preview_id
- The ID of the namespace you wish to bind to the Worker’s global scope when it is previewed . Required for
wrangler dev
andwrangler preview
.
- The ID of the namespace you wish to bind to the Worker’s global scope when it is previewed . Required for
site
A Workers Site generated with wrangler generate --site
or wrangler init --site
.
Usage:
[site]bucket = "./public"entry-point = "workers-site"
bucket
- The directory containing your static assets, path relative to your
wrangler.toml
. Example:bucket = "./public"
- The directory containing your static assets, path relative to your
entry-point
- The location of your Worker script, default is
workers-site
. Example:entry-point = "./workers-site"
- The location of your Worker script, default is
include
- A list of gitignore-style patterns for files or directories in
bucket
you exclusively want to upload. Example:include = ["upload_dir"]
- A list of gitignore-style patterns for files or directories in
exclude
- A list of gitignore-style patterns for files or directories in
bucket
you want to exclude from uploads. Example:exclude = ["ignore_dir"]
- A list of gitignore-style patterns for files or directories in
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 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
- Ip for local
wrangler dev
server to listen on, defaults to 127.0.0.1
- Ip for local
port
- Port for local
wrangler dev
server to listen on, defaults to 8787
- Port for local
local_protocol
- Protocol that local
wrangler dev
server listen to requests on, defaults to http
- Protocol that local
upstream_protocol
- Protocol that
wrangler dev
forwards requests on, defaults to https
- Protocol that
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" }]