Cloudflare Workers · Wrangler · all subjects

wrangler.toml

210 notes in this subject, read out of this brain and free to use. This is page 2 of 4.

Routes add Workers functionality to proxied hostnames

Routes add Workers functionality to your existing proxied hostnames in front of your application server. They allow your Workers to act as a proxy and perform necessary work before reaching out to an application server behind Cloudflare. Routes are recommended if you have a designated application server you always need to communicate with.

Routes can fetch Custom Domains and take precedence

Routes can fetch() Custom Domains and take precedence if configured on the same hostname. If you create a Custom Domain on your application Worker for app.example.com and create a Route for your logging Worker at app.example.com/*, calling fetch() will invoke the application Worker on your Custom Domain. Routes cannot be the target of a same-zone fetch() call.

Route configuration in wrangler.toml

Routes are configured in the wrangler configuration file using a routes array. Each route object requires a pattern and either zone_name or zone_id. The zone_name and zone_id options are interchangeable. Example: {"routes": [{"pattern": "subdomain.example.com/*", "zone_name": "example.com"}, {"pattern": "subdomain.example.com/*", "zone_id": "<YOUR_ZONE_ID>"}]}

Route pattern matching rules

Route patterns follow specific rules: (1) The only supported operator is the wildcard (*), which matches zero or more of any character. (2) Route patterns may not contain infix wildcards or query parameters (e.g., example.com/*.jpg or example.com/?foo=* are invalid). (3) When more than one route pattern could match a request URL, the most specific route pattern wins. (4) Route pattern matching considers the entire request URL, including the query parameter string. Since patterns may not contain query parameters, only routes terminating with a wildcard can match URLs with query parameters.

Route pattern path case sensitivity

The path component of route patterns is case sensitive. For example, example.com/Images/* and example.com/images/* are two distinct routes.

Route pattern host case sensitivity based on creation date

For routes created before October 15th, 2023, the host component of route patterns is case sensitive (example.com/* and Example.com/* are distinct routes). For routes created on or after October 15th, 2023, the host component is not case sensitive (example.com/* and Example.com/* are equivalent).

Route pattern wildcards match zero or more characters

The wildcard (*) in route patterns matches zero or more of any character, not just subdomains. For example, *example.com will also match hostnames that are not subdomains of example.com, like myexample.com. If you only want to match example.com and its subdomains, use two separate routes: example.com/* and *.example.com/*

Route pattern host wildcard variations

If a route pattern hostname begins with *, it matches the host and all subhosts. If it begins with *., it only matches all subhosts. *example.com/ matches both https://example.com/ and https://www.example.com/. *.example.com/ matches https://www.example.com/ but not https://example.com/.

Route pattern path wildcard behavior

If a route pattern path ends with *, it matches all suffixes of that path. For example, https://example.com/path* matches https://example.com/path, https://example.com/path2, and https://example.com/path/readme.txt

Route patterns must include your zone

Route patterns must include your zone. If your zone is example.com, then the simplest possible route pattern is example.com, which matches http://example.com/ and https://example.com/, and nothing else. As with a URL, there is an implied path of / if you do not specify one.

Route patterns cannot contain query parameters

Route patterns may not contain any query parameters. For example, https://example.com/?anything is not a valid route pattern.

Routes can negate less specific patterns

A route can be specified without being associated with a Worker to negate any less specific patterns. For example, if *example.com/images/cat.png has no script and *example.com/images/* routes to worker-script, then requests to /images/cat.png bypass Workers completely, but /images/cat.png?foo=bar routes to worker-script due to the presence of the query string.

Domains and subdomains must have DNS records

All domains and subdomains must have a DNS record to be proxied on Cloudflare and used to invoke a Worker. If you want to put a Worker on myname.example.com but have not added DNS records for it, requests will result in ERR_NAME_NOT_RESOLVED error.

Route pattern specificity precedence

When more than one route pattern could match a request URL, the most specific route pattern wins. The pattern www.example.com/* takes precedence over *.example.com/* when matching https://www.example.com/. The pattern example.com/hello/* takes precedence over example.com/* when matching example.com/hello/world.

Route pattern matching includes query strings

Route pattern matching considers the entire request URL, including the query parameter string. Since route patterns may not contain query parameters themselves, the only way to have a route pattern match URLs with query parameters is to terminate it with a wildcard *.

Example: Text and JSON environment variables in wrangler.toml

Example showing how to define environment variables in wrangler.toml: [vars] API_HOST = "api.example.com" API_ACCOUNT_ID = "123" SERVICE_X_DATA = { service_x_token = "abc123", service_x_url = "https://api.service-x.com" } API_HOST and API_ACCOUNT_ID are text values, and SERVICE_X_DATA is a JSON value.

Example: Environment-specific vars in wrangler.toml

Example showing how to configure different environment variables for staging and production environments: { "name": "my-worker-dev", "vars": { "API_HOST": "api.example.com" }, "env": { "staging": { "vars": { "API_HOST": "staging.example.com" } }, "production": { "vars": { "API_HOST": "production.example.com" } } } }

Define environment variables in wrangler.toml with [vars] section

To add environment variables using Wrangler, define text and JSON via the [vars] configuration in your Wrangler file. Both text values and JSON values are supported in the vars section.

vars is a non-inheritable key in wrangler.toml

The vars key is a non-inheritable key in Wrangler configuration, meaning environment variables are not inherited by environments and must be specified for each environment separately.

Use --env or -e flag to run Wrangler commands in specific environments

To run Wrangler commands in specific environments, pass in the --env or -e flag. For example, npx wrangler dev --env staging or npx wrangler deploy --env staging.

Default ignored entries in Workers Sites

Wrangler automatically ignores the following entries regardless of include/exclude configuration: `node_modules`, hidden files and directories, and symlinks.

Workers Sites file size limit

There is a 25 MiB limit per page or file in Workers Sites. For very exceptionally large pages, Workers Sites might not work.

Site configuration placement with environments

If a project uses environments in wrangler.toml, the `site` configuration block must be placed above any environment-specific configuration blocks.

Include and exclude patterns use gitignore semantics

The `include` and `exclude` fields in Workers Sites configuration use gitignore-style patterns, similar to Cargo's optional include and exclude fields. Refer to the gitignore documentation for information about the standard patterns used.

Workers Sites configuration example with environments

Example wrangler.toml configuration for Workers Sites with environments: ```jsonc { "$schema": "./node_modules/wrangler/config-schema.json", "name": "docs-site-blah", "site": { "bucket": "./public" }, "env": { "production": { "name": "docs-site", "route": "https://example.com/docs*" }, "staging": { "name": "docs-site-staging", "route": "https://staging.example.com/docs*" } } } ```

Workers Sites bucket configuration

The `bucket` field is required in the `site` section of wrangler.toml. It specifies the directory containing static assets, with the path relative to the Wrangler configuration file. Example: `bucket = "./public"`.

Workers Sites include field for selective uploads

The `include` field is optional in the `site` section of wrangler.toml. It is an array of gitignore-style patterns that specifies files or directories in the bucket to exclusively upload. Wrangler will only upload files or directories matching the patterns in the `include` array. Example: `include = ["upload_dir"]`.

Workers Sites exclude field for filtering uploads

The `exclude` field is optional in the `site` section of wrangler.toml. It is an array of gitignore-style patterns that specifies files or directories in the bucket to exclude from uploads. Wrangler will ignore files or directories matching the patterns in the `exclude` array when uploading assets to Workers KV. Example: `exclude = ["ignore_dir"]`.

Include field takes precedence over exclude in Workers Sites

If both `include` and `exclude` fields are provided in the `site` section, the `include` field will be used and the `exclude` field will be ignored.

Workers Sites use cases and frameworks

Workers Sites enables developers to deploy static applications directly to Workers. It can be used for deploying applications built with static site generators like Hugo and Gatsby, or front-end frameworks like Vue and React.

Workers Sites is deprecated, use Workers Static Assets instead

Workers Sites is no longer recommended for new projects. Developers should use Workers Static Assets instead to host full-stack applications. Workers Sites is built on Workers KV.

Workers Sites pricing based on Workers KV

Workers Sites is built on Workers KV, and usage rates may apply. Refer to the Pricing documentation for more details.

Declare required secrets using secrets configuration property

You can declare the secret names your Worker requires using the secrets configuration property in your Wrangler configuration. When defined, wrangler deploy and wrangler versions upload will fail with a clear error if any required secrets are not configured on the Worker.

public directory contains static assets

The public directory contains the static assets for a Workers Sites project. By default it contains an index.html and a favicon.ico file.

src directory contains Worker code

The src directory contains the Worker configured for serving static assets. The default entry point is src/index.ts, which can be edited to add more functionality to the Worker.

wrangler.jsonc configuration file

The wrangler.jsonc file contains project configuration for Workers Sites. It includes the name property for the project name and the bucket property that tells Wrangler where to find static assets, for example: site = { bucket = "./public" }

name property in wrangler.jsonc

Set the name property in wrangler.jsonc to specify the name of your project.

site property with bucket configuration

The site property in wrangler.jsonc uses the bucket field to specify the directory containing static assets. Example: site = { bucket = "./public" }

route property in wrangler.jsonc for custom domains

To deploy a Worker site to a custom domain you own and have attached as a Cloudflare zone, add a 'route' property to wrangler.jsonc with the format 'route': 'https://example.com/*'. This requires the domain to already be added to Cloudflare as a zone.

site.bucket configuration field for static assets directory

The 'site' object in wrangler.jsonc must contain a 'bucket' field that specifies the build/output directory path where static assets are located, for example './public'. This is required for Workers Sites to find and upload assets.

Default build directories for static site generators

Common static site generators have these default output directories: Hugo uses 'public', Gatsby uses 'public', Jekyll uses '_site', and Eleventy uses '_site'.

site.bucket configuration for static assets

The wrangler.toml configuration file uses a 'site' object with a 'bucket' field to point to the directory containing static assets. The value should be a relative path string, such as "./public", indicating the directory in the root of the project that contains the static files to be served.

Control bundling with rules and find_additional_modules

You can provide 'rules' and set 'find_additional_modules' in your configuration to control which files are included in the deployed Worker but not bundled into the entry-point file. This allows for partial bundling where source files matching configured rules are treated as external and not bundled.

find_additional_modules traverses file tree for unbundled modules

Setting 'find_additional_modules' to true in the configuration file causes Wrangler to traverse the file tree below 'base_dir'. Any files matching the 'rules' you define will be included as unbundled, external modules in the deployed Worker. This supports lazy loading of large or dynamically imported JavaScript files.

Generated Wrangler configuration

Some framework tools or custom pre-build processes can generate a modified Wrangler configuration that Wrangler will automatically use instead of the original user's configuration when deploying Worker code.

Custom build configuration example

Example custom build configuration in wrangler.jsonc: ```jsonc { "build": { "command": "npm run build", "cwd": "build_cwd", "watch_dir": "build_watch_dir" } } ``` This example demonstrates setting a build command, specifying the working directory for that command, and configuring which directory to watch for changes during development.

Custom builds configuration with [build] section

Custom builds are configured by adding a [build] section in the Wrangler configuration file. The [build] section allows you to customize how your code is compiled before being processed by Wrangler.

Custom build cwd option

The 'cwd' field specifies the directory in which the command is executed. This field is optional.

Custom build watch_dir option

The 'watch_dir' field specifies the directory or directories to watch for changes while using wrangler dev. It accepts either a string or an array of strings. This field is optional and defaults to the current working directory.

observability configuration field

The observability field is an optional object that configures automatic observability settings for telemetry data emitted from the Worker. Contains: enabled (required boolean) - When set to true, logs for the Worker are persisted. Defaults to true for all new Workers. head_sampling_rate (optional number) - A number between 0 and 1, where 0 indicates zero out of one hundred requests are logged, and 1 indicates every request is logged. If head_sampling_rate is unspecified, it is configured to a default value of 1 (100%).

vars configuration field

The vars field is an optional non-inheritable object that specifies a map of environment variables to set when deploying the Worker.

Migrations for Durable Objects

Migrations are defined in a migrations array, where each migration has a tag (string) and new_sqlite_classes (array of strings listing class names that are new in this migration).

Required configuration keys minimum

At a minimum, the name, main, and compatibility_date keys are required to deploy a Worker. The main key is optional for assets-only Workers.

name configuration field

The name field is a required string that specifies the name of the Worker. Alphanumeric characters (a, b, c, etc.) and dashes (-) only are allowed. Do not use underscores (_). Worker names can be up to 255 characters. If you plan to use a workers.dev subdomain, the name must be 63 characters or less and cannot start or end with a dash.

main configuration field

The main field is a required string that specifies the path to the entrypoint of the Worker that will be executed. For example: ./src/index.ts. This field is optional only for assets-only Workers.

compatibility_date configuration field

The compatibility_date field is a required string in the form yyyy-mm-dd, which will be used to determine which version of the Workers runtime is used.

account_id configuration field

The account_id field is an optional string that specifies the ID of the account associated with the zone. If you have more than one account, ensure to use the ID of the account associated with the zone or route you provide. It can also be specified through the CLOUDFLARE_ACCOUNT_ID environment variable.

compatibility_flags configuration field

The compatibility_flags field is an optional array of strings that enable features from upcoming features of the Workers runtime, usually used together with compatibility_date.

workers_dev configuration field

The workers_dev field is an optional boolean that enables use of *.workers.dev subdomain to deploy the Worker. If the Worker is only for scheduled events, it can be set to false. Defaults to true.

preview_urls configuration field

The preview_urls field is an optional boolean that enables use of Preview URLs to test the Worker. Defaults to the value of workers_dev.

Give your agent this brain