Configuration
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.
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:
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:
To deploy this example Worker to the helloworld
environment, you would run wrangler publish --env helloworld
.
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.
-
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
, andrust
.javascript
checks for a build command specified in the[build]
section,webpack
builds your project using webpack v4, andrust
compiles the Rust in your project to WebAssembly.
- Specifies how
-
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 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
-
zone_id
inherited optional- This is the ID of the zone or domain you want to run your Worker 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 Worker on. It can also be specified through the
-
workers_dev
inherited optional- This is a boolean flag that specifies if your Worker will be deployed to your
*.workers.dev
↗ subdomain. If omitted, it defaults to false.
- This is a boolean flag that specifies if your Worker will be deployed to your
-
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/*"
. 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 optional- A list of routes you would 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 would like to use your Worker on. These follow exactly the same rules a
-
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. Refer to 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
that configure local server.
- Arguments for
-
triggers
inherited optional- Configures cron triggers for running a Worker on a schedule.
-
usage_model
inherited optional- Specifies the Usage Model for your Worker. There are two options -
bundled
andunbound
. 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.
- Specifies the Usage Model for your Worker. There are two options -
-
build
top level optional- Configures a custom build step to be run by Wrangler when building your Worker. Refer to the custom builds documentation for more details.
The vars
key defines a table of environment variables provided to your Worker script. All values are plaintext values.
Usage:
The table keys are available to your Worker as global variables, which will contain their associated values.
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:
kv_namespaces
defines a list of KV namespace bindings for your Worker.
Usage:
Alternatively, you can define kv namespaces
like so:
Much like environment variables and secrets, the binding
names are available to your Worker as global variables.
-
binding
required- The name of the global variable your code will reference. It will be provided as a KV runtime instance.
-
id
required- The ID of the KV namespace that your
binding
should represent. Required forwrangler publish
.
- The ID of the KV namespace that your
-
preview_id
required- The ID of the KV namespace that your
binding
should represent duringwrangler dev
orwrangler preview
. Required forwrangler dev
andwrangler preview
.
- The ID of the KV namespace that your
A Workers Site generated with wrangler generate --site
or wrangler init --site
.
Usage:
-
bucket
required- The directory containing your static assets. It must be a path relative to your
wrangler.toml
file. Example:bucket = "./public"
- The directory containing your static assets. It must be a path relative to your
-
entry-point
optional- The location of your Worker script. The default location is
workers-site
. Example:entry-point = "./workers-site"
- The location of your Worker script. The default location is
-
include
optional- An exclusive list of
.gitignore
-style patterns that match file or directory names from yourbucket
location. Only matched items will be uploaded. Example:include = ["upload_dir"]
- An exclusive list of
-
exclude
optional- A list of
.gitignore
-style patterns that match files or directories in yourbucket
that should be excluded from uploads. Example:exclude = ["ignore_dir"]
- A list of
You can also define your site
using an alternative TOML syntax ↗.
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.
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:
Wrangler will only upload files or directories matching the patterns in the include
array.
If you want to exclude files or directories in your bucket
, add an exclude
field to your [site]
section of your wrangler.toml
file:
Wrangler will ignore files or directories matching the patterns in the exclude
array when uploading assets to Workers KV.
If you provide both include
and exclude
fields, the include
field will be used and the exclude
field will be ignored.
Wrangler will always ignore:
node_modules
- Hidden files and directories
- Symlinks
Refer to the gitignore documentation ↗ to learn more about the standard matching patterns.
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.
A set of cron triggers used to call a Worker on a schedule.
Usage:
crons
optional- A set of cron expressions ↗, where each expression is a separate schedule to run the Worker on.
Arguments for wrangler dev
can be configured here so you do not have to repeatedly pass them.
Usage:
-
ip
optional- IP address for the local
wrangler dev
server to listen on, defaults to127.0.0.1
.
- IP address for the local
-
port
optional- Port for local
wrangler dev
server to listen on, defaults to8787
.
- Port for local
-
local_protocol
optional- Protocol that local
wrangler dev
server listen to requests on, defaults tohttp
.
- Protocol that local
-
upstream_protocol
optional- Protocol that
wrangler dev
forwards requests on, defaults tohttps
.
- Protocol that
A custom build command for your project. There are two configurations based on the format of your Worker: service-worker
and modules
.
This section is for customizing Workers with the service-worker
format. These Workers use addEventListener
and look like the following:
Usage:
-
command
optional- The command used to build your Worker. On Linux and macOS, the command is executed in the
sh
shell and thecmd
shell for Windows. The&&
and||
shell operators may be used.
- The command used to build your Worker. On Linux and macOS, the command is executed in the
-
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 thesrc
relative to the project root directory.
- The directory to watch for changes while using
-
format
required- The format of the Worker script, must be
"service-worker"
.
- The format of the Worker script, must be
Workers now supports the ES Modules syntax. 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.
To create a Workers project using Wrangler and Modules, add a [build]
section:
-
command
optional- The command used to build your Worker. On Linux and macOS system, the command is executed in the
sh
shell and thecmd
shell for Windows. The&&
and||
shell operators may be used.
- The command used to build your Worker. On Linux and macOS system, the command is executed in the
-
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 thesrc
relative to the project root directory.
- The directory to watch for changes while using
-
format
required- The format of the Workers script, must be
"modules"
.
- The format of the Workers script, must be
-
dir
optional- The directory you wish to upload your modules from, defaults to the
dist
relative to the project root directory.
- The directory you wish to upload your modules from, defaults to the
-
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.
- The relative path of the main module from
-
rules
optional- An ordered list of rules that define which modules to import, and what type to import them as.
You will need to specify rules to use Text, Data, and CompiledWasm modules, or when you wish to
have a
.js
file be treated as anESModule
instead ofCommonJS
.
- An ordered list of rules that define which modules to import, and what type to import them as.
You will need to specify rules to use Text, Data, and CompiledWasm modules, or when you wish to
have a
Defaults:
-
type
required- The module type, see the table below for acceptable options:
-
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 frombuild.upload.dir
without the./
prefix. Rules are evaluated in order, starting at the top.
- UNIX-style glob rules ↗ that are used to determine the module type to use for a given file in
-
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.
To illustrate how these levels are applied, here is a wrangler.toml
file using multiple environments: