Compatibility date wrangler.toml example
Example of setting compatibility_date in wrangler configuration: {"compatibility_date": "2022-04-05"} - this opts into backwards-incompatible changes through April 5, 2022.
Cloudflare Workers · Wrangler · all subjects
wrangler.toml
210 notes in this subject, read out of this brain and free to use. This is page 1 of 4.
Set compatibility_date in wrangler.toml or wrangler.jsonc
The compatibility_date can be set in the Wrangler configuration file (wrangler.toml or wrangler.jsonc) using the field name compatibility_date with a date string in YYYY-MM-DD format.
nodejs_als wrangler.toml example
To enable only the AsyncLocalStorage API, add nodejs_als to the compatibility_flags array in wrangler.toml: {"compatibility_flags": ["nodejs_als"]}
Setting compatibility flags in wrangler.toml
Compatibility flags are set in the Wrangler configuration file using the compatibility_flags array. For example, to enable formdata_parser_supports_files, add it to the compatibility_flags array alongside a compatibility_date field.
compatibility_flags wrangler.toml field example
The wrangler.toml file can include a compatibility_flags field as an array of strings, such as ["formdata_parser_supports_files"]. This can be used to enable flags not yet enabled by default or disable changes that became default in the past.
Remove Cron Triggers via wrangler.toml
To remove all Cron Triggers via the Wrangler configuration file, set the 'crons' property to an empty array: { "triggers": { "crons": [] } }.
wrangler.toml triggers configuration for cron
Configure Cron Triggers in wrangler.toml under the 'triggers' object with a 'crons' array containing cron expressions. Example: { "triggers": { "crons": ["*/3 * * * *", "0 15 1 * *", "59 23 LW * *"] } }. Per-environment cron triggers are configured by placing the 'triggers' object under the specific environment in the 'env' section.
Wrangler is the command-line tool for Workers development
Wrangler is the command-line tool used to develop, test, and deploy Workers.
Worker configuration managed through Wrangler configuration file
Worker configuration is managed through a Wrangler configuration file that defines project settings, bindings, and deployment options.
Smart Placement traffic analysis requirements
Smart Placement requires consistent traffic to the Worker from multiple locations to make a placement decision. The analysis process may take up to 15 minutes.
Smart Placement baseline traffic
By default, 1% of requests are not routed with Smart Placement to serve as a baseline for comparison when measuring the impact of Smart Placement.
cf-placement header format
Cloudflare adds a 'cf-placement' header to all requests when placement is enabled. The header value includes a placement type and an airport code indicating the data center location. Examples: 'remote-LHR' means the request was routed using Smart Placement to a data center near London; 'local-EWR' means the request was not routed using Smart Placement and the Worker ran in the default location near Newark.
Smart Placement analysis time
Smart Placement may take up to 15 minutes to analyze a Worker after deployment before it makes placement decisions.
Smart Placement status states
When checking placement status via the Workers API, possible status values are: status not present (Worker has not been analyzed yet and runs in default location closest to request); SUCCESS (Worker was analyzed and will be optimized by Smart Placement); INSUFFICIENT_INVOCATIONS (Worker has not received enough requests from multiple locations to make a placement decision); UNSUPPORTED_APPLICATION (Smart Placement made the Worker slower and reverted placement, rare occurrence affecting fewer than 1% of Workers).
host-based placement is experimental
The host-based placement feature using placement.host is experimental.
placement configuration options
Workers placement is configured in wrangler.toml under the 'placement' object. The placement object has four mutually exclusive options: 'mode' can be set to 'smart' for automatic placement near the upstream with the most requests; 'region' accepts a cloud provider region identifier like 'aws:us-east-1' or 'gcp:us-east4' to place the Worker closest to that cloud region; 'host' specifies a TCP/layer 4 endpoint like 'db.example.com:5432' for Cloudflare to probe and place the Worker closest to; 'hostname' specifies an HTTP/layer 7 endpoint like 'api.example.com' for Cloudflare to probe using HTTP HEAD checks.
Placement Hints cloud region identifiers
Placement Hints support Amazon Web Services (AWS), Google Cloud Platform (GCP), and Microsoft Azure region identifiers. AWS format is 'aws:{region}' with examples like 'aws:us-east-1', 'aws:us-west-2', 'aws:eu-central-1'. GCP format is 'gcp:{region}' with examples like 'gcp:us-east4', 'gcp:europe-west1', 'gcp:asia-east1'. Azure format is 'azure:{region}' with examples like 'azure:westeurope', 'azure:eastus', 'azure:southeastasia'.
placement probes sent from public IP ranges
Probes sent for host-based or hostname-based placement are sent from public IP ranges, not Cloudflare IP ranges. These probes locate single-homed resources and do not work correctly for broadcast, anycast, multicast, or replicated resources. Cloudflare rechecks service location at regular intervals.
Smart Placement only considers previously seen locations
Smart Placement only considers locations where the Worker has previously run. It cannot place a Worker in a location that does not normally receive traffic.
placement limitations on handlers and assets
Placement only affects the execution of fetch event handlers and does not affect RPC methods or named entrypoints. Workers without a fetch event handler are ignored by placement. Static assets are always served from the location nearest to the incoming request. If code retrieves assets via the static assets binding, those assets are served from the location where the Worker runs.
Worker placement at extremely high request volumes
At extremely high request volumes (hundreds of thousands of requests per second or more), Cloudflare may run Worker instances across a more distributed area to balance traffic, even when explicit placement is configured.
cf-placement header may be removed
The cf-placement header may be removed before Smart Placement exits beta.
Metadata keep_assets attribute
The keep_assets boolean attribute (optional) specifies whether assets should be retained from a previously uploaded Worker version, used in lieu of providing a completion token.
Metadata assets configuration
The assets object (optional) contains asset configuration for a Worker. It includes a nested config object (optional) that specifies html_handling for redirects and rewrites of HTML content requests, and not_found_handling for responses when requests do not match a static asset. The assets object also includes a jwt field that provides a token authorizing assets to be attached to a Worker.
Metadata placement configuration
The placement object (optional) contains Smart placement configuration for the Worker. The mode field only supports the value 'smart' for automatic placement.
Metadata main_module attribute required
The main_module key is required at minimum to upload a Worker. It must be a string specifying the part name that contains the module entry point of the Worker that will be executed, such as 'main.js'.
Metadata top-level attributes
Top-level metadata attributes include: main_module (string, required), assets (object, optional), keep_assets (boolean, optional), bindings (array of objects, optional), placement (object, optional), compatibility_date (string, optional), and compatibility_flags (array of strings, optional).
Metadata migrations attribute for Script Upload API
The migrations array of objects (optional) is available only for immediately deployed uploads via the Workers Script Upload API. It specifies Durable Objects migrations to apply. This attribute is not available for version uploads.
Metadata logpush attribute
The logpush boolean attribute (optional) is available only for immediately deployed uploads via the Workers Script Upload API. It specifies whether Logpush is turned on for the Worker. This attribute is not available for version uploads.
Metadata tail_consumers attribute
The tail_consumers array of objects (optional) is available only for immediately deployed uploads via the Workers Script Upload API. It specifies Tail Workers that will consume logs from the attached Worker. This attribute is not available for version uploads.
Multipart upload metadata overview
When using the Workers Script Upload API or Version Upload API directly with multipart/form-data uploads, you must specify a metadata part that defines the Worker's configuration in JSON format, analogous to the wrangler.toml file.
Metadata annotations attribute for Version Upload API
The annotations object (optional) is available for Version Upload API version uploads. It specifies annotations specific to the Worker version. Fields include: workers/message (custom message for the version), workers/tag (custom identifier for the version), and workers/alias (custom alias for this version).
Metadata tags attribute
The tags array of strings (optional) is available only for immediately deployed uploads via the Workers Script Upload API. It specifies a list of strings to use as tags for this Worker. This attribute is not available for version uploads.
Three types of Worker routes
There are three types of routes to connect a Worker to an external endpoint: Custom Domains, Routes, and workers.dev subdomains. Custom Domains route to a domain or subdomain within a Cloudflare zone where the Worker is the origin. Routes are set within a Cloudflare zone where your origin server is behind a Worker that the Worker can communicate with. A workers.dev subdomain route is automatically created for each Worker and can be disabled.
Production Worker routing best practice
It is recommended to run production Workers on a Workers route or custom domain, rather than on your workers.dev subdomain.
workers.dev subdomain scope
Your workers.dev subdomain is treated as a Free website and is intended for personal or hobby projects that aren't business-critical. It is not recommended for production Workers.
Routes use case
Routes are recommended for use cases where your application's origin server is external to Cloudflare. Routes cannot be the target of a same-zone fetch() call.
Custom Domains use case
Custom Domains are recommended for use cases where your Worker is your application's origin server. Custom Domains can be invoked within the same zone via fetch(), unlike Routes.
Migrate from Routes to Custom Domain recommended scenario
If you are currently invoking a Worker using a route with /*, and you have a CNAME record pointing to 100:: or similar, a Custom Domain is a recommended replacement.
Configure Custom Domain in Wrangler configuration file
To configure a Custom Domain in your Wrangler configuration file, add the custom_domain=true option on each pattern under routes. Example for single Custom Domain: {"routes": [{"pattern": "shop.example.com", "custom_domain": true}]}. Example for multiple Custom Domains: {"routes": [{"pattern": "shop.example.com", "custom_domain": true}, {"pattern": "shop-two.example.com", "custom_domain": true}]}.
Custom Domain exact hostname matching requires redirect setup
Because Custom Domains require an exact hostname match, a Worker attached to example.com will not receive requests sent to www.example.com, and vice versa. To make both versions of your domain work, set up a redirect rule: either redirect from www to root or from root to www. You also need a proxied DNS record for the hostname you are redirecting from. For www to root: add a proxied DNS A record for www pointing to 192.0.2.0, or a proxied AAAA record pointing to 100::. For root to www: add a proxied DNS A record for your root domain pointing to 192.0.2.0, or a proxied AAAA record pointing to 100::. These are reserved placeholder addresses for originless setups and requests never reach them since Cloudflare intercepts and applies your redirect rule.
Custom Domain certificate deletion behavior
When you delete a Custom Domain, the associated Advanced Certificate is not automatically deleted. You must manually remove the certificate from the Cloudflare dashboard under SSL/TLS > Edge Certificates, or via the API. Leaving unused certificates in place does not affect functionality but may cause confusion when auditing certificate inventory.
Custom Domain automatic certificate generation
Creating a Custom Domain automatically generates an Advanced Certificate on your target zone for your target hostname. These certificates are generated with default settings. To override these settings, delete the generated certificate and create your own certificate in the Cloudflare dashboard.
Custom Domain chaining example with fetch
Example: A Custom Domain for api.example.com points to api-worker. A route at api.example.com/auth points to auth-worker. A request to api.example.com/auth triggers auth-worker. Within auth-worker, calling fetch(request) invokes api-worker as if it were a normal application server. Code example: export default { fetch(request) { const url = new URL(request.url); if(url.searchParams.get("auth") !== "SECRET_TOKEN") { return new Response(null, { status: 401 }); } else { return fetch(request); } } }
Custom Domain and Route interaction
A Worker running on a Custom Domain is treated as an origin. Workers running on routes before your Custom Domain can optionally call the Worker registered on your Custom Domain by issuing fetch(request) with the incoming Request object. This allows you to chain together two Workers in the same request.
Custom Domain request matching behavior
Custom Domains do not support wildcard DNS records. An incoming request must exactly match the domain or subdomain your Custom Domain is registered to. Other parts of the URL such as path and query parameters are not considered in the matching logic. For example, a Custom Domain on api.example.com would handle both api.example.com/login and api.example.com/user with the same Worker.
Custom Domain prerequisites
To add a Custom Domain, you must have an active Cloudflare zone and a Worker to invoke. You cannot create a Custom Domain on a hostname with an existing CNAME DNS record or on a zone you do not own.
Custom Domain stacking and cross-domain fetch
Custom Domains can stack on top of each other. For example, Worker A attached to app.example.com can call fetch() on api.example.com and invoke Worker B. Custom Domains can also be invoked within the same zone via fetch(), unlike Routes.
Custom Domain definition and purpose
Custom Domains allow you to connect your Worker to a domain or subdomain without making DNS changes or performing certificate management. Cloudflare creates DNS records and issues certificates automatically. Custom Domains point all paths of a domain or subdomain to your Worker. They are recommended if you want to connect your Worker to the Internet and do not have an external application server that you need to communicate with. Unlike Routes, Custom Domains point directly to your Worker as the origin.
Migrate from Routes to Custom Domain via Wrangler
To migrate a route like example.com/* to a Custom Domain in your Wrangler configuration file: (1) Delete the CNAME record for example.com from DNS Records page. (2) Add to Wrangler file: {"routes": [{"pattern": "example.com", "custom_domain": true}]}. (3) Run npx wrangler deploy to create the Custom Domain.
workers_dev inferred as false when routes configured
If you do not specify workers_dev: false but add a routes component to your Wrangler configuration file, the value of workers_dev will be inferred as false on the next deploy.
Disable workers.dev in wrangler configuration
To disable the workers.dev route for a Worker, include workers_dev: false in the Worker's Wrangler configuration file. When you redeploy your Worker with this change, the workers.dev route will be disabled.
workers.dev subdomain format
All Workers are assigned a workers.dev route when they are created or renamed following the syntax <YOUR_WORKER_NAME>.<YOUR_SUBDOMAIN>.workers.dev. The name field in the Worker configuration is used as the subdomain for the deployed Worker.
Worker name character restrictions for workers.dev
When deploying a Worker with a workers.dev subdomain enabled, the Worker name must contain only alphanumeric characters (a-z, A-Z, 0-9) and dashes (-). The name cannot start or end with a dash.
workers_dev re-enabled on redeploy if not set in config
If you disable your workers.dev route in the Cloudflare dashboard but do not update your Worker's Wrangler file with workers_dev: false, the workers.dev route will be re-enabled the next time you deploy your Worker with Wrangler.
Worker name length limit for workers.dev
When deploying a Worker with a workers.dev subdomain enabled, the Worker name must be 63 characters or less. This restriction applies because the Worker name is used as a DNS label in the workers.dev URL, and DNS labels have a maximum length of 63 characters.
Worker name length without workers.dev
Worker names can be up to 255 characters when not using a workers.dev subdomain. If you need a longer name, you can disable workers.dev and use routes or custom domains instead.
Preview URLs default to workers_dev setting
Preview URLs default to matching your workers_dev setting unless explicitly configured. If you explicitly enabled Preview URLs, you must disable them separately.
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 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.