Cloudflare Workers · Wrangler · all subjects

wrangler.toml

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

Legacy assets deprecated and removed in Wrangler v4

Legacy Assets feature is removed in Wrangler v4. The `--legacy-assets` flag for `wrangler dev` and `wrangler deploy` commands and the `legacy_assets` configuration property are no longer supported. Users should migrate to Workers Static Assets instead.

Legacy Node.js compatibility removed in Wrangler v4

Legacy Node.js compatibility feature is removed in Wrangler v4. The `--node-compat` flag for `wrangler dev` and `wrangler deploy` commands and the `node_compat` configuration property are no longer supported. Users should use the `nodejs_compat` compatibility flag instead, which includes the functionality from legacy `node_compat` polyfills and natively implemented Node.js APIs.

Wrangler v2 [build] section for webpack

To configure Wrangler v2 to use webpack for bundling, add a [build] section to the Wrangler configuration file. The [build] section should contain a 'command' field specifying how to invoke the build (e.g., 'npm run build' or 'yarn build'). Additionally, set the 'main' field to point to the JavaScript file that webpack outputs (by default this is './worker/script.js' or similar).

Wrangler v2 [build] key continues to work

The [build] key is supported in Wrangler v2, so existing Workers projects that use the [build] section to run webpack or another bundler external to Wrangler will continue to build as before without requiring changes.

Remove type and webpack_config keys in Wrangler v2

The `type` and `webpack_config` keys are not supported in Wrangler v2. These keys should be removed from the Wrangler configuration file when migrating from Wrangler v1.

Deprecated wrangler.toml fields causing v2 errors

The wrangler.toml fields type, zone_id, and build.upload.format are deprecated in Wrangler v2. The type field is ignored because most features now work out of the box with wrangler, including modules, jsx, typescript, etc. If you need anything more, use a custom build. The zone_id field is unnecessary since it can be deduced from routes directly. The build.upload.format field is no longer needed because the format is inferred automatically from the code.

Route configuration error in wrangler.toml v2

In Wrangler v2, the route field in wrangler.toml must be either a string or an object with shape { pattern, zone_id | zone_name }. It cannot be empty.

Wrangler v1 credentials storage location

Wrangler v1 creates a configuration file in a .wrangler directory in your computer's home directory to store user credentials globally.

Key inheritance types in Wrangler v1

Wrangler v1 has three types of keys: (1) Top level only - required at top level only, shared across environments. (2) Inherited - can be configured at top level and/or environment, environment value overrides top-level if defined in environment. (3) Non-inherited - must be defined individually for every environment.

name field in Wrangler v1 configuration

The name field is inherited and required. It specifies the name of your Worker script. If inherited from top level, the environment name will be appended to the top-level name.

type field in Wrangler v1 configuration

The type field is top-level only and required. It specifies how wrangler build will build your project. Valid options are: javascript (checks for build command in [build] section), webpack (builds using webpack v4), and rust (compiles Rust to WebAssembly). Cloudflare recommends using javascript project type with custom build section.

account_id field in Wrangler v1 configuration

The account_id field is inherited and required. It specifies the ID of the account associated with your zone. It can also be specified through the CF_ACCOUNT_ID environment variable.

zone_id field in Wrangler v1 configuration

The zone_id field is inherited and optional. It specifies the ID of the zone or domain where you want to run your Worker. It can also be specified through the CF_ZONE_ID environment variable. This field is optional if using only a *.workers.dev subdomain.

workers_dev field in Wrangler v1 configuration

The workers_dev field is inherited and optional. It is a boolean flag that specifies if your Worker will be deployed to your *.workers.dev subdomain. If omitted, it defaults to false.

route and routes fields in Wrangler v1 configuration

The route field (not inherited, optional) specifies a single route by URL pattern on your zone. The routes field (not inherited, optional) specifies a list of routes. Example: route = "http://example.com/*" or routes = ["http://example.com/hello", "http://example.com/goodbye"]. A route OR routes key is only required if not using a *.workers.dev subdomain.

Wrangler v1 configuration file location and format

Configuration for Wrangler v1 is done through a Wrangler file located in the root of your project directory. The file must be manually edited to change keys and values before publishing. The configuration file uses JSON format with optional JSONC comments.

Top-level configuration keys in Wrangler v1

Top-level configuration consists of values specified at the top of the Wrangler file that are inherited by all environments unless overridden. Top-level configuration keys include: $schema, name, type, account_id, workers_dev, zone_id, routes, route, vars, kv_namespaces, site, dev, triggers, usage_model, webpack_config, and build.

dev field in Wrangler v1 configuration

The dev field is not inherited and optional. It configures arguments for wrangler dev so you do not have to repeatedly pass them. It contains: ip (optional, defaults to 127.0.0.1), port (optional, defaults to 8787), local_protocol (optional, defaults to http), and upstream_protocol (optional, defaults to https).

usage_model field in Wrangler v1 configuration

The usage_model field is inherited and optional. It specifies the Usage Model for your Worker. Options are: bundled and unbound. For newly created Workers, if omitted it defaults to the default Usage Model set on the account. For existing Workers, if omitted it uses the Usage Model configured in the dashboard for that Worker.

webpack_config field in Wrangler v1 configuration

The webpack_config field is inherited and optional. It specifies 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.

vars field in Wrangler v1 configuration

The vars field is not inherited and optional. It is an object containing text variables that can be directly accessed in a Worker script. All values are plaintext. The table keys are available to your Worker as global variables containing their associated values. For example, vars: { "FOO": "some value", "BAR": "some other string" } makes FOO and BAR available as global variables in the Worker.

site field in Wrangler v1 configuration

The site field is inherited and optional. It configures a Workers Site for serving static assets. It requires a bucket field (directory containing static assets relative to Wrangler file) and optional entry-point field (location of Worker script, defaults to workers-site), include field (exclusive list of .gitignore-style patterns to upload), and exclude field (list of .gitignore-style patterns to exclude from uploads).

site bucket field in Wrangler v1

The bucket field in the site configuration is required. It specifies the directory containing your static assets and must be a path relative to your Wrangler file. Example: bucket = "./public"

site entry-point field in Wrangler v1

The entry-point field in the site configuration is optional. It specifies the location of your Worker script. The default location is workers-site. Example: entry-point = "./workers-site"

site include field in Wrangler v1

The include field in the site configuration is optional. It is an exclusive list of .gitignore-style patterns that match file or directory names from your bucket location. Only matched items will be uploaded. When both include and exclude are provided, include takes precedence and exclude is ignored.

site exclude field in Wrangler v1

The exclude field in the site configuration is optional. It is a list of .gitignore-style patterns that match files or directories in your bucket that should be excluded from uploads. When both include and exclude are provided, include takes precedence and exclude is ignored.

Workers Site storage limit in Wrangler v1

Workers Sites have a 25 MiB limit per page or file. Wrangler creates an asset manifest for your files that counts towards your script's size limit. If you have too many files, you may not be able to use Workers Sites.

site default ignored entries in Wrangler v1

Wrangler always ignores these entries in site buckets: node_modules, hidden files and directories, and symlinks.

Setting webpack_config in Wrangler file

To use Wrangler's webpack integration, you must set 'type = "webpack"' in your Wrangler file. To use a custom webpack configuration file, set the 'webpack_config' field in the Wrangler file to specify the path to your custom webpack configuration file.

account_id configuration field

The account_id is an inheritable key in the Wrangler configuration file that specifies which Cloudflare account should be targeted. It takes precedence in account selection within an active profile and serves as a failsafe to prevent commands from reaching the wrong account.

Give your agent this brain