routes configuration field
The routes field is an optional array of route objects that specifies routes the Worker should be deployed to. Only one of routes or route is required.
Cloudflare Workers · Wrangler · all subjects
wrangler.toml
210 notes in this subject, read out of this brain and free to use. This is page 3 of 4.
tsconfig configuration field
The tsconfig field is an optional string that specifies the path to a custom tsconfig. Not applicable if using the Cloudflare Vite plugin.
rules configuration field
The rules field is an optional ordered list of Rule objects that define which modules to import and what type to import them as. It is needed to use Text, Data and CompiledWasm modules, or when a .js file should be treated as an ESModule instead of CommonJS. Not applicable if using the Cloudflare Vite plugin.
logpush configuration field
The logpush field is an optional boolean that enables Workers Trace Events Logpush for a Worker. Any scripts with this property will automatically get picked up by the Workers Logpush job configured for the account. Defaults to false.
keep_vars configuration field
The keep_vars field is an optional boolean (top-level only) that specifies whether Wrangler should keep variables configured in the dashboard on deploy. Refer to source of truth configuration guidance.
send_metrics configuration field
The send_metrics field is an optional boolean (top-level only) that specifies whether Wrangler should send usage data to Cloudflare for this project. Defaults to true.
dependencies_instrumentation configuration field
The dependencies_instrumentation field is an optional top-level object that configures npm package dependency instrumentation when deploying or uploading a Worker version. Defaults to enabled. It contains an enabled field (boolean) that specifies whether Wrangler should collect and send npm package dependency metadata (package names and versions). Defaults to true.
site configuration field (deprecated)
The site field is a deprecated optional top-level object used for Workers Sites configuration. Cloudflare Pages and Workers Assets is preferred over this approach. This is not supported by the Cloudflare Vite plugin.
Environments in Wrangler configuration
Environments allow defining different configurations for a Worker using Wrangler. A default (top-level) environment exists and named environments can be created that provide environment-specific configuration. These are defined under [env.<name>] keys, such as [env.staging], and can be previewed or deployed with the -e / --env flag in wrangler commands like npx wrangler deploy --env staging. The majority of keys are inheritable, but bindings such as vars or kv_namespaces are not inheritable and must be defined explicitly in each environment.
Automatic provisioning of resources
Wrangler can automatically provision resources when deploying a Worker without needing to create them ahead of time. This currently works for KV, R2, D1, Flagship, AI Search, Agent Memory, Dispatch Namespaces and Queues. To use this feature, add bindings to the configuration file without adding resource IDs, or in the case of R2, a bucket name. Resources will be created with the name of the worker as the prefix. When running wrangler dev, local resources will automatically be created which persist between runs. When running wrangler deploy, resources will be created and their IDs will be written back to the configuration file.
limits configuration field
The limits field is an optional object that configures limits to be imposed on execution at runtime. Limits are only supported for the Standard Usage Model and are only enforced when deployed to Cloudflare's network, not in local development. Contains: cpu_ms (optional number) - The maximum CPU time allowed per invocation, in milliseconds. The CPU limit can be set to a maximum of 300,000 milliseconds (5 minutes). subrequests (optional number) - The maximum number of subrequests allowed per invocation. This value defaults to 50 for free accounts and 10,000 for paid accounts. The free account maximum is 50 and the paid account maximum is 10,000,000.
assets configuration field
The assets field is an optional object that configures static assets to be served. Only one collection of assets per Worker can be configured. Contains: directory (optional string) - Folder of static assets to be served. Not required if using the Cloudflare Vite plugin. binding (optional string) - The binding name used to refer to the assets. Optional, and only useful when a Worker script is set with main. run_worker_first (optional boolean or string array) - Controls whether static assets are fetched directly, or a Worker script is invoked. Can be a boolean (true/false) or an array of route pattern strings with support for glob patterns (*) and exception patterns (! prefix). Patterns must begin with / or !/. html_handling (optional string) - Determines the redirects and rewrites of requests for HTML content. Valid values: "auto-trailing-slash" (default), "force-trailing-slash", "drop-trailing-slash", "none". not_found_handling (optional string) - Determines the handling of requests that do not map to an asset. Valid values: "single-page-application", "404-page", "none" (default).
define configuration field
The define field is an optional non-inheritable object of type Record<string, string> that specifies a map of values to substitute when deploying the Worker. If using the Cloudflare Vite plugin, define is replaced by Vite's define option.
placement configuration field
The placement field is an optional object that configures where the Worker runs to minimize latency to back-end services. Contains: mode (optional string) - Set to "smart" to automatically place the Worker near back-end services based on observed latency. region (optional string) - Specify a cloud region (e.g., "aws:us-east-1", "gcp:europe-west1", "azure:westeurope") to place the Worker near infrastructure in that region. host (optional string) - Specify a hostname and port for a single-homed layer 4 service (e.g., "my_database_host.com:5432") to place the Worker near that service. hostname (optional string) - Specify a hostname for a single-homed layer 7 service (e.g., "my_api_server.com") to place the Worker near that service.
Custom domain route configuration
Custom Domains allow connecting a Worker to a domain or subdomain without making DNS changes or performing certificate management. A custom domain route object contains: pattern (required string) - The pattern the Worker should run on, e.g., "example.com". custom_domain (optional boolean) - Whether the Worker should be on a Custom Domain as opposed to a route. Defaults to false.
Zone ID route configuration
A Zone ID route specifies a route by zone ID. The route object contains: pattern (required string) - The pattern the Worker can run on, e.g., "example.com/*". zone_id (required string) - The ID of the zone that the pattern is associated with.
Zone name route configuration
A Zone name route specifies a route by zone name. The route object contains: pattern (required string) - The pattern the Worker should run on, e.g., "example.com/*". zone_name (required string) - The name of the zone that the pattern is associated with. If using API tokens, this will require the Account scope.
Simple route configuration
A simple route only requires a pattern and can be configured as a string. Example: "route": "example.com/*"
build custom build configuration fields
The build object contains configuration for custom build steps. Fields: command (optional string) - The command used to build the Worker. On Linux and macOS, executed in sh shell; cmd shell for Windows. && and || shell operators may be used. cwd (optional string) - The directory in which the command is executed. watch_dir (optional string or string array) - The directory to watch for changes while using wrangler dev. Defaults to the current working directory.
containers configuration field
The containers field allows defining Containers to run alongside a Worker. Must also define a Durable Object with class_name matching the container configuration. Fields: image (required string) - The image for the container. Can be a local Dockerfile path (wrangler deploy will build and push) or an image reference. Supported registries: Cloudflare Registry, Docker Hub, Amazon ECR, Google Artifact Registry. class_name (required string) - The corresponding Durable Object class name. instance_type (optional string) - The instance type determining memory, CPU, disk. Options: "lite" (default), "basic", "standard-1", "standard-2", "standard-3", "standard-4". max_instances (optional string) - Maximum concurrent container instances. Defaults to 20. Only enforced in production, not local development. name (optional string) - Name of the container. Defaults to combination of Worker name, class name, and environment. image_build_context (optional string) - Build context, default is directory of image. image_vars (optional Record<string, string>) - Build-time variables equivalent to docker build --build-arg. rollout_active_grace_period (optional number) - Minimum seconds before active container instance becomes eligible for updating during rollout. Defaults to 0. rollout_step_percentage (optional number or number array) - Configures percentage of instances updated at each rollout step. If single number, options: 5, 10, 20, 25, 50, 100. If array, each step specifies cumulative progress, final step must be 100. Defaults to [10, 100]. Can be overridden with --containers-rollout=immediate flag. ssh (optional object) - Configuration for SSH through Wrangler. wrangler_ssh (optional object, deprecated, use ssh) - Deprecated alias for ssh. authorized_keys (optional object array) - Public keys added to Container's authorized_keys file. constraints (optional object) - Placement constraints. constraints.regions (optional string array) - Limit placement to geographic regions. Valid: "ENAM", "WNAM", "EEUR", "WEUR", "APAC", "SAM", "ME", "OC", "AFR". constraints.jurisdiction (optional string) - Restrict to compliance boundaries. Valid: "eu", "fedramp".
Containers configuration: basic fields
A container in wrangler.toml has the following fields: class_name (string, required), image (string, required, path to Dockerfile), max_instances (number), instance_type (string, optional, defaults to "lite"), image_vars (object for environment variables), and constraints (object with regions array and jurisdiction string).
Custom instance types for containers
Instead of using named instance types, you can configure custom instance types by setting vcpu (number, optional, defaults to 0.0625), memory_mib (number, optional, defaults to 256), and disk_mb (number, optional, defaults to 2000). These are set in the instance_type field as an object.
SSH configuration for containers
SSH access to Container instances through Wrangler is configured with enabled (boolean, optional, defaults to true) and port (number, optional, defaults to 22). Authorized keys have name (string, required) and public_key (string, required, currently only ssh-ed25519 type is supported).
Local development settings: dev configuration
Local development is configured in the dev object with: ip (string, optional, defaults to localhost), port (number, optional, defaults to 8787), local_protocol (string, optional, defaults to http), upstream_protocol (string, optional, defaults to https), host (string, optional, defaults to host of first route), enable_containers (boolean, optional, defaults to true), container_engine (string, optional for Docker socket path), and generate_types (boolean, optional, defaults to false).
Module aliasing configuration
The alias field in wrangler.toml maps package names to replacement modules. For example, alias: { "foo": "./replacement-module-filepath" } replaces all imports or requires of "foo" with the replacement module. This is used to fix bundling issues or provide Worker-compatible implementations of incompatible packages.
Aliasing node-fetch for Workers
You can alias node-fetch to the built-in fetch API in Workers by setting alias: { "node-fetch": "./fetch-polyfill" } and creating a fetch-polyfill.js file that exports the fetch function.
Aliasing fs module example
To alias the fs module for a Node.js API that is not yet available in Workers, configure alias: { "fs": "./fs-polyfill" } and create an fs-polyfill.js file exporting the required functions like readFile().
Source maps configuration
The upload_source_maps boolean field, when set to true, automatically generates and uploads source map files when running wrangler deploy or wrangler versions deploy.
Workers Sites configuration
Workers Sites configuration has: bucket (string, required, directory containing static assets relative to wrangler config), include (string array, optional, .gitignore-style patterns for files to upload), and exclude (string array, optional, .gitignore-style patterns for files to exclude from uploads).
keep_vars configuration option
Setting keep_vars = true in the wrangler configuration file disables the default behavior where environment variables changed in the Cloudflare dashboard are overridden by Wrangler on the next deploy.
Generated wrangler configuration via .wrangler/deploy/config.json
Build tools can create a .wrangler/deploy/config.json file containing { "configPath": "path/to/wrangler.jsonc" } to redirect Wrangler to use a generated configuration for deploy and dev commands. Wrangler searches up the directory tree from the current working directory for this file. The generated configuration should not include environments, as build tools should generate distinct configuration files for different environments.
Service Environments and legacy_env deprecated in Wrangler v4
Usage of Service Environments, enabled via the legacy_env property in Wrangler config, is deprecated as of Wrangler v4. Support for using Service Environments with Wrangler will be removed in a future version of Wrangler. Instead, you should migrate to Wrangler Environments.
name field not required for wrangler dev or kv commands in Wrangler v2
The name configuration field is not required for wrangler dev or any of the wrangler kv:* commands in Wrangler v2. It can also be passed as a command line argument as --name <name>. It is still required for wrangler deploy.
account_id field not required in Wrangler v2
The account_id configuration field is not required for any commands in Wrangler v2. Any relevant commands will check if you are logged in, and if not, will prompt you to log in. Once logged in, it will use your account ID and will not prompt you again until your login session expires. If you have multiple account IDs, you will be presented with a list of accounts to choose from. You can still configure account_id in your Wrangler file or as the CLOUDFLARE_ACCOUNT_ID environment variable. The CLOUDFLARE_API_TOKEN environment variable is also useful for situations where interactive login is not possible.
workers_dev field in Wrangler v2 configuration
The workers_dev field is a boolean, optional configuration field in Wrangler v2 with a default of true when no routes are present. It indicates that the Worker should be published to a *.workers.dev subdomain. For example, for a Worker named my-worker and a previously configured *.workers.dev subdomain username, the Worker will get published to my-worker.username.workers.dev.com. When routes are present, it defaults to false. If you want to neither publish it to a *.workers.dev subdomain nor any routes, set workers_dev to false.
zone_id field deprecated in Wrangler v2
The zone_id configuration field is deprecated in Wrangler v2 and will be removed in a future release. It is now inferred from route/routes, and optionally from dev.host when using wrangler dev. This also makes it simpler to deploy a single Worker to multiple domains.
build.upload deprecated in Wrangler v2
The build.upload configuration field is deprecated in Wrangler v2 and will be removed in a future release. Its usage results in a warning with suggestions on rewriting the configuration file. build.upload.main and build.upload.dir are replaced by the main field, build.upload.rules is replaced by the rules field, and build.upload.format is no longer specified and is automatically inferred by wrangler.
site.entry-point field deprecated in Wrangler v2
The site.entry-point configuration field is deprecated in Wrangler v2 and will not work as expected anymore. It was used to specify an entry point for Workers with a [site] configuration. This has been replaced by the top-level main field.
type field deprecated in Wrangler v2
The type configuration field with values rust, javascript, or webpack is deprecated in Wrangler v2 and will not work as expected anymore. The type configuration was used to specify the type of Worker but has since been made redundant and is now inferred from usage. If you were using type = "webpack" and the optional webpack_config field, you should refer to the webpack migration guide to modify your project and use a custom build instead.
Cloudflare dashboard-defined routes behavior change in Wrangler v2
In Wrangler v2, Cloudflare dashboard-defined routes will not be added alongside Wrangler-defined routes. Wrangler-defined routes are the route or routes key in your wrangler.toml. If both are defined, only routes defined in wrangler.toml will be valid. To manage routes via the Cloudflare dashboard only, remove any route and routes keys from wrangler.toml and add workers_dev = false.
wrangler.toml no longer mandatory in Wrangler v2
wrangler.toml is no longer mandatory in Wrangler v2.
Wrangler v2 introduces better configuration validation
Wrangler v2 introduces better configuration validation.
--legacy-assets and legacy_assets config property deprecated in Wrangler v3
The --legacy-assets command line option and the legacy_assets configuration file property are deprecated in Wrangler v3. Migrate to Workers static assets instead.
--node-compat and node_compat config property deprecated in Wrangler v3
The --node-compat command line option and the node_compat configuration file property are deprecated in Wrangler v3. Use the nodejs_compat compatibility flag instead, which includes both the functionality from legacy node_compat polyfills and natively implemented Node.js APIs.
usage_model config property no longer has any effect in Wrangler v3
The usage_model configuration file property no longer has any effect as of Wrangler v3, following the rollout of Workers Standard Pricing.
type config field no longer required in Wrangler v2
The type configuration field is no longer required in Wrangler v2. Wrangler will infer the correct project type automatically.
zone_id config field no longer required in Wrangler v2
The zone_id configuration field is no longer required in Wrangler v2. It can be deduced from the routes directly.
build.upload.format no longer used in Wrangler v2
The build.upload.format configuration field is no longer used in Wrangler v2. The format is now inferred automatically from the code.
build.upload.main and build.upload.dir replaced by main field in Wrangler v2
The build.upload.main and build.upload.dir configuration fields are no longer required in Wrangler v2. Use the top level main field instead, which now serves as the entry-point for the Worker.
main field in Wrangler v2 configuration
The main field is a string, optional configuration field in Wrangler v2 that specifies an entry point to the Worker. It may be in the established service worker format, or the newer modules format. An entry point is explicitly required and can be configured either via the main field, or passed directly as a command line argument, for example wrangler dev index.js. This field replaces the legacy build.upload.main field.
rules field in Wrangler v2 configuration
The rules field is an array, optional configuration field in Wrangler v2 that contains mappings between module types and file patterns. It instructs Wrangler to interpret specific files differently than JavaScript. For example, this is useful for reading text-like content as text files, or compiled WASM as ready to instantiate and execute. These rules can apply to Workers of both the established service worker format and the newer modules format. This field replaces the legacy build.upload.rules field.
Example: staging and production environments configuration
Example Wrangler configuration with two environments: ```jsonc { "$schema": "./node_modules/wrangler/config-schema.json", "name": "my-worker", "route": "dev.example.com/*", "vars": { "ENVIRONMENT": "dev" }, "env": { "staging": { "vars": { "ENVIRONMENT": "staging" }, "route": "staging.example.com/*" }, "production": { "vars": { "ENVIRONMENT": "production" }, "routes": ["example.com/foo/*", "example.com/bar/*"] } } } ``` This configuration deploys 'my-worker' to dev.example.com, 'my-worker-staging' to staging.example.com, and 'my-worker-production' to example.com/foo/* and example.com/bar/*.
Example: staging environment with workers.dev
Example Wrangler configuration deploying to workers.dev: ```jsonc { "$schema": "./node_modules/wrangler/config-schema.json", "name": "my-worker", "route": "example.com/*", "env": { "staging": { "workers_dev": true } } } ``` With 'npx wrangler deploy', my-worker publishes to example.com. With 'npx wrangler deploy --env staging', my-worker-staging publishes to https://my-worker-staging.<YOUR_SUBDOMAIN>.workers.dev.
Environment configuration in wrangler.toml syntax
Environments are configured in the Wrangler configuration file by adding an [env.<ENV_NAME>] section. The JSON syntax uses an 'env' object with environment names as keys, where environment-specific configuration is nested under each environment name.
Non-inheritable keys must be specified per environment
Non-inheritable keys are configurable at the top-level but cannot be inherited by environments and must be specified for each environment. Bindings and environment variables (vars) are non-inheritable and must be specified per environment in the Wrangler configuration file.
Environment variable names as keys in env object
Environment variables are configured using the 'vars' key in the Wrangler configuration. Top-level 'vars' are inherited unless overridden in environment-specific 'vars' blocks. For example, 'vars: { API_HOST: "example.com" }' at the top level can be overridden in 'env.production.vars' with a different value.
Route configuration differs per environment
The 'route' or 'routes' key can be specified differently for each environment. When deploying to Custom Domains or routes, you must provide a route or routes key for each environment. For example, top-level route 'example.com' can be overridden with 'dev.example.com' in the dev environment.
Access environment variables in Worker code via env object
Environment variables defined with the 'vars' key in the Wrangler configuration are available via the 'env' object in your Worker. In the fetch handler, you can access them as 'env.VARIABLE_NAME', allowing environment-specific code branches based on the variable values.
Deploy to workers.dev with workers_dev flag per environment
To deploy code to the *.workers.dev subdomain in a specific environment, include 'workers_dev = true' in that environment's configuration. For example, setting 'workers_dev: true' in the staging environment allows deploying to 'my-worker-staging.<YOUR_SUBDOMAIN>.workers.dev' while the top-level Worker deploys to a custom domain.
usage_model configuration removed in Wrangler v4
The `usage_model` configuration property is removed in Wrangler v4 and no longer has any effect. This follows the rollout of Workers Standard Pricing.