INTEGRITY Cloudflare Docs

← Workers / workers / wrangler / migration / v1-to-v2 / wrangler-legacy

Configuration

Background

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 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.

Environments

The top-level configuration is the collection of values you specify at the top of your Wrangler 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 file is displayed below:

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "your-worker",
	"type": "javascript",
	"account_id": "your-account-id",
	// This field specifies that the Worker
	// will be deployed to a *.workers.dev domain
	"workers_dev": true,
	// -- OR --
	// These fields specify that the Worker
	// will deploy to a custom domain
	"zone_id": "your-zone-id",
	"routes": [
		"example.com/*"
	]
}
"$schema" = "./node_modules/wrangler/config-schema.json"
name = "your-worker"
type = "javascript"
account_id = "your-account-id"
workers_dev = true
zone_id = "your-zone-id"
routes = [ "example.com/*" ]

Environment configuration (optional): the configuration values you specify under an [env.name] in your Wrangler 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:

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:

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"type": "javascript",
	"name": "your-worker",
	"account_id": "your-account-id",
	"vars": {
		"FOO": "default FOO value",
		"BAR": "default BAR value"
	},
	"kv_namespaces": [
		{
			"binding": "FOO",
			"id": "1a...",
			"preview_id": "1b..."
		}
	],
	"env": {
		"helloworld": {
			// Now adding configuration keys for the "helloworld" environment.
			// These new values will override the top-level configuration.
			"name": "your-worker-helloworld",
			"account_id": "your-other-account-id",
			"vars": {
				"FOO": "env-helloworld FOO value",
				"BAR": "env-helloworld BAR value"
			},
			"kv_namespaces": [
				{
					// Redeclare kv namespace bindings for each environment
					// NOTE: In this case, passing new IDs because new `account_id` value.
					"binding": "FOO",
					"id": "888...",
					"preview_id": "999..."
				}
			]
		}
	}
}
"$schema" = "./node_modules/wrangler/config-schema.json"
type = "javascript"
name = "your-worker"
account_id = "your-account-id"

[vars]
FOO = "default FOO value"
BAR = "default BAR value"

[[kv_namespaces]]
binding = "FOO"
id = "1a..."
preview_id = "1b..."

[env.helloworld]
name = "your-worker-helloworld"
account_id = "your-other-account-id"

  [env.helloworld.vars]
  FOO = "env-helloworld FOO value"
  BAR = "env-helloworld BAR value"

  [[env.helloworld.kv_namespaces]]
  binding = "FOO"
  id = "888..."
  preview_id = "999..."

To deploy this example Worker to the helloworld environment, you would run wrangler deploy --env helloworld.

Keys

There are three types of keys in a Wrangler file:

vars

The vars key defines a table of environment variables provided to your Worker script. All values are plaintext values.

Usage:

{
	"vars": {
		"FOO": "some value",
		"BAR": "some other string"
	}
}
[vars]
FOO = "some value"
BAR = "some other string"

The table keys are available to your Worker as global variables, which will contain their associated values.

// Worker code:
console.log(FOO);
//=> "some value"

console.log(BAR);
//=> "some other string"

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:

{
	"vars": {
		"FOO": "some value",
		"BAR": "some other string"
	}
}
[vars]
FOO = "some value"
BAR = "some other string"

kv_namespaces

kv_namespaces defines a list of KV namespace bindings for your Worker.

Usage:

{
	"kv_namespaces": [
		{
			"binding": "FOO",
			"id": "0f2ac74b498b48028cb68387c421e279",
			"preview_id": "6a1ddb03f3ec250963f0a1e46820076f"
		},
		{
			"binding": "BAR",
			"id": "068c101e168d03c65bddf4ba75150fb0",
			"preview_id": "fb69528dbc7336525313f2e8c3b17db0"
		}
	]
}
[[kv_namespaces]]
binding = "FOO"
id = "0f2ac74b498b48028cb68387c421e279"
preview_id = "6a1ddb03f3ec250963f0a1e46820076f"

[[kv_namespaces]]
binding = "BAR"
id = "068c101e168d03c65bddf4ba75150fb0"
preview_id = "fb69528dbc7336525313f2e8c3b17db0"

Alternatively, you can define kv namespaces like so:

{
	"kv_namespaces": [
		{
			"binding": "FOO",
			"preview_id": "abc456",
			"id": "abc123"
		},
		{
			"binding": "BAR",
			"preview_id": "xyz456",
			"id": "xyz123"
		}
	]
}
[[kv_namespaces]]
binding = "FOO"
preview_id = "abc456"
id = "abc123"

[[kv_namespaces]]
binding = "BAR"
preview_id = "xyz456"
id = "xyz123"

Much like environment variables and secrets, the binding names are available to your Worker as global variables.

// Worker script:

let value = await FOO.get("keyname");
//=> gets the value for "keyname" from
//=> the FOO variable, which points to
//=> the "0f2ac...e279" KV namespace

site

A Workers Site generated with wrangler generate --site or wrangler init --site.

Usage:

{
	"site": {
		"bucket": "./public",
		"entry-point": "workers-site"
	}
}
[site]
bucket = "./public"
entry-point = "workers-site"

You can also define your site using an alternative TOML syntax ↗.

Storage Limits

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.

Exclusively including files/directories

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 file:

{
	"site": {
		"bucket": "./public",
		"entry-point": "workers-site",
		"include": [ // must be an array.
			"included_dir"
		]
	}
}
[site]
bucket = "./public"
entry-point = "workers-site"
include = [ "included_dir" ]

Wrangler will only upload files or directories matching the patterns in the include array.

Excluding files/directories

If you want to exclude files or directories in your bucket, add an exclude field to your [site] section of your Wrangler file:

{
	"site": {
		"bucket": "./public",
		"entry-point": "workers-site",
		"exclude": [ // must be an array.
			"excluded_dir"
		]
	}
}
[site]
bucket = "./public"
entry-point = "workers-site"
exclude = [ "excluded_dir" ]

Wrangler will ignore files or directories matching the patterns in the exclude array when uploading assets to Workers KV.

Include > Exclude

If you provide both include and exclude fields, the include field will be used and the exclude field will be ignored.

Default ignored entries

Wrangler will always ignore:

More about include/exclude patterns

Refer to the gitignore documentation ↗ to learn more about the standard matching patterns.

Customizing your Sites Build

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.

triggers

A set of cron triggers used to call a Worker on a schedule.

Usage:

{
	"triggers": {
		"crons": [
			"0 0 * JAN-JUN FRI",
			"0 0 LW JUL-DEC *"
		]
	}
}
[triggers]
crons = [ "0 0 * JAN-JUN FRI", "0 0 LW JUL-DEC *" ]

dev

Arguments for wrangler dev can be configured here so you do not have to repeatedly pass them.

Usage:

{
	"dev": {
		"port": 9000,
		"local_protocol": "https"
	}
}
[dev]
port = 9_000
local_protocol = "https"

build

A custom build command for your project. There are two configurations based on the format of your Worker: service-worker and modules.

Service Workers

This section is for customizing Workers with the service-worker format. These Workers use addEventListener and look like the following:

addEventListener("fetch", (event) => {
	event.respondWith(new Response("I'm a service Worker!"));
});

Usage:

{
	"build": {
		"command": "npm install && npm run build",
		"upload": {
			"format": "service-worker"
		}
	}
}
[build]
command = "npm install && npm run build"

  [build.upload]
  format = "service-worker"
[build]
[build.upload]

Modules

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.

import html from "./index.html";

export default {
	// * request is the same as `event.request` from the service worker format
	// * waitUntil() and passThroughOnException() are accessible from `ctx` instead of `event` from the service worker format
	// * env is where bindings like KV namespaces, Durable Object namespaces, Config variables, and Secrets
	// are exposed, instead of them being placed in global scope.
	async fetch(request, env, ctx) {
		const headers = { "Content-Type": "text/html;charset=UTF-8" };
		return new Response(html, { headers });
	},
};

To create a Workers project using Wrangler and Modules, add a [build] section:

{
	"build": {
		"command": "npm install && npm run build",
		"upload": {
			"format": "modules",
			"main": "./worker.mjs"
		}
	}
}
[build]
command = "npm install && npm run build"

  [build.upload]
  format = "modules"
  main = "./worker.mjs"
[build]
[build.upload]

Defaults:

{
	// You do not need to include these default rules in your [Wrangler configuration file](/workers/wrangler/configuration/), they are implicit.
	// The default rules are treated as the last two rules in the list.
	"build": {
		"upload": {
			"format": "modules",
			"main": "./worker.mjs",
			"rules": [
				{
					"type": "ESModule",
					"globs": [
						"**/*.mjs"
					]
				},
				{
					"type": "CommonJS",
					"globs": [
						"**/*.js",
						"**/*.cjs"
					]
				}
			]
		}
	}
}
[build.upload]
format = "modules"
main = "./worker.mjs"

  [[build.upload.rules]]
  type = "ESModule"
  globs = [ "**/*.mjs" ]

  [[build.upload.rules]]
  type = "CommonJS"
  globs = [ "**/*.js", "**/*.cjs" ]

Example

To illustrate how these levels are applied, here is a Wrangler file using multiple environments:

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	// top level configuration
	"type": "javascript",
	"name": "my-worker-dev",
	"account_id": "12345678901234567890",
	"zone_id": "09876543210987654321",
	"route": "dev.example.com/*",
	"usage_model": "unbound",
	"kv_namespaces": [
		{
			"binding": "FOO",
			"id": "b941aabb520e61dcaaeaa64b4d8f8358",
			"preview_id": "03c8c8dd3b032b0528f6547d0e1a83f3"
		},
		{
			"binding": "BAR",
			"id": "90e6f6abd5b4f981c748c532844461ae",
			"preview_id": "e5011a026c5032c09af62c55ecc3f438"
		}
	],
	"build": {
		"command": "webpack",
		"upload": {
			"format": "service-worker"
		}
	},
	"site": {
		"bucket": "./public",
		"entry-point": "workers-site"
	},
	"dev": {
		"ip": "0.0.0.0",
		"port": 9000,
		"local_protocol": "http",
		"upstream_protocol": "https"
	},
	"env": {
		// environment configuration
		"staging": {
			"name": "my-worker-staging",
			"route": "staging.example.com/*",
			"kv_namespaces": [
				{
					"binding": "FOO",
					"id": "0f2ac74b498b48028cb68387c421e279"
				},
				{
					"binding": "BAR",
					"id": "068c101e168d03c65bddf4ba75150fb0"
				}
			]
		},
		// environment configuration
		"production": {
			"workers_dev": true,
			"kv_namespaces": [
				{
					"binding": "FOO",
					"id": "0d2ac74b498b48028cb68387c421e233"
				},
				{
					"binding": "BAR",
					"id": "0d8c101e168d03c65bddf4ba75150f33"
				}
			]
		}
	}
}
"$schema" = "./node_modules/wrangler/config-schema.json"
type = "javascript"
name = "my-worker-dev"
account_id = "12345678901234567890"
zone_id = "09876543210987654321"
route = "dev.example.com/*"
usage_model = "unbound"

[[kv_namespaces]]
binding = "FOO"
id = "b941aabb520e61dcaaeaa64b4d8f8358"
preview_id = "03c8c8dd3b032b0528f6547d0e1a83f3"

[[kv_namespaces]]
binding = "BAR"
id = "90e6f6abd5b4f981c748c532844461ae"
preview_id = "e5011a026c5032c09af62c55ecc3f438"

[build]
command = "webpack"

  [build.upload]
  format = "service-worker"

[site]
bucket = "./public"
entry-point = "workers-site"

[dev]
ip = "0.0.0.0"
port = 9_000
local_protocol = "http"
upstream_protocol = "https"

[env.staging]
name = "my-worker-staging"
route = "staging.example.com/*"

  [[env.staging.kv_namespaces]]
  binding = "FOO"
  id = "0f2ac74b498b48028cb68387c421e279"

  [[env.staging.kv_namespaces]]
  binding = "BAR"
  id = "068c101e168d03c65bddf4ba75150fb0"

[env.production]
workers_dev = true

  [[env.production.kv_namespaces]]
  binding = "FOO"
  id = "0d2ac74b498b48028cb68387c421e233"

  [[env.production.kv_namespaces]]
  binding = "BAR"
  id = "0d8c101e168d03c65bddf4ba75150f33"