Configuration

Wrangler optionally uses a configuration file to customize the development and deployment setup for a Worker.

It is best practice to treat Wrangler's configuration file as the source of truth for configuring a Worker.

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	// Top-level configuration
	"name": "my-worker",
	"main": "src/index.js",
	// Set this to today's date
	"compatibility_date": "2026-08-12",
	"workers_dev": false,
	"route": {
		"pattern": "example.org/*",
		"zone_name": "example.org",
	},
	"kv_namespaces": [
		{
			"binding": "<MY_NAMESPACE>",
			"id": "<KV_ID>",
		},
	],
	"env": {
		"staging": {
			"name": "my-worker-staging",
			"route": {
				"pattern": "staging.example.org/*",
				"zone_name": "example.org",
			},
			"kv_namespaces": [
				{
					"binding": "<MY_NAMESPACE>",
					"id": "<STAGING_KV_ID>",
				},
			],
		},
	},
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "my-worker"
main = "src/index.js"
# Set this to today's date
compatibility_date = "2026-08-12"
workers_dev = false

[route]
pattern = "example.org/*"
zone_name = "example.org"

[[kv_namespaces]]
binding = "<MY_NAMESPACE>"
id = "<KV_ID>"

[env.staging]
name = "my-worker-staging"

  [env.staging.route]
  pattern = "staging.example.org/*"
  zone_name = "example.org"

  [[env.staging.kv_namespaces]]
  binding = "<MY_NAMESPACE>"
  id = "<STAGING_KV_ID>"

You can define different configurations for a Worker using Wrangler environments. There is a default (top-level) environment and you can create named environments that provide environment-specific configuration.

These are defined under [env.<name>] keys, such as [env.staging] which you can then preview or deploy with the -e / --env flag in the wrangler commands like npx wrangler deploy --env staging.

The majority of keys are inheritable, meaning that top-level configuration can be used in environments. Bindings, such as vars or kv_namespaces, are not inheritable and need to be defined explicitly.

Further, there are a few keys that can only appear at the top-level.

Wrangler can automatically provision resources for you when you deploy your Worker without you having to create them ahead of time.

This currently works for the following resources: KV, R2, D1, Flagship, AI Search, Agent Memory, Dispatch Namespaces and Queues.

To use this feature, add bindings to your configuration file without adding resource IDs, or in the case of R2, a bucket name. Resources will be created with the name of your worker as the prefix.

{
	"kv_namespaces": [
		{
			"binding": "<MY_KV_NAMESPACE>",
		},
	],
}

[[kv_namespaces]]
binding = "<MY_KV_NAMESPACE>"

When you run wrangler dev, local resources will automatically be created which persist between runs. When you run wrangler deploy, resources will be created for you, and their IDs will be written back to your configuration file.

If you deploy a worker with resources and no resource IDs from the dashboard (for example, via GitHub), resources will be created, but their IDs will only be accessible via the dashboard. Currently, these resource IDs will not be written back to your repository.

Top-level keys apply to the Worker as a whole (and therefore all environments). They cannot be defined within named environments.

• keep_vars booleanoptional

  • Whether Wrangler should keep variables configured in the dashboard on deploy. Refer to source of truth.

• send_metrics booleanoptional

  • Whether Wrangler should send usage data to Cloudflare for this project. Defaults to true. You can learn more about this in our data policy ↗.

• dependencies_instrumentation objectoptional

  • Configures npm package dependency instrumentation when deploying or uploading a Worker version. Defaults to enabled.
  • enabled boolean — Whether Wrangler should collect and send npm package dependency metadata (package names and versions). Defaults to true.

• site objectoptional deprecated

  • See the Workers Sites section below for more information. Cloudflare Pages and Workers Assets is preferred over this approach.
  • This is not supported by the Cloudflare Vite plugin.

Inheritable keys are configurable at the top-level, and can be inherited (or overridden) by environment-specific configuration.

• name stringrequired

  • The name of your Worker. Alphanumeric characters (a,b,c, etc.) and dashes (-) only. 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 stringrequired

  • The path to the entrypoint of your Worker that will be executed. For example: ./src/index.ts.

• compatibility_date stringrequired

  • A date in the form yyyy-mm-dd, which will be used to determine which version of the Workers runtime is used. Refer to Compatibility dates.

• account_id stringoptional

  • This is the ID of the account associated with your zone. You might have more than one account, so make sure to use the ID of the account associated with the zone/route you provide, if you provide one. It can also be specified through the CLOUDFLARE_ACCOUNT_ID environment variable.

• compatibility_flags string[]optional

  • A list of flags that enable features from upcoming features of the Workers runtime, usually used together with compatibility_date. Refer to compatibility dates.

• workers_dev booleanoptional

  • Enables use of *.workers.dev subdomain to deploy your Worker. If you have a Worker that is only for scheduled events, you can set this to false. Defaults to true. Refer to types of routes.

• preview_urls booleanoptional

  • Enables use of Preview URLs to test your Worker. Defaults to value of workers_dev. Refer to Preview URLs.

• route Routeoptional

  • A route that your Worker should be deployed to. Only one of routes or route is required. Refer to types of routes.

• routes Route[]optional

  • An array of routes that your Worker should be deployed to. Only one of routes or route is required. Refer to types of routes.

• tsconfig stringoptional

  • Path to a custom tsconfig.
  • Not applicable if you're using the Cloudflare Vite plugin.

• triggers objectoptional

  • Cron definitions to trigger a Worker's scheduled function. Refer to triggers.

• rules Ruleoptional

  • An ordered list of rules that define which modules to import, and what type to import them as. You will need to specify rules to use Text, Data and CompiledWasm modules, or when you wish to have a .js file be treated as an ESModule instead of CommonJS.
  • Not applicable if you're using the Cloudflare Vite plugin.

• build Buildoptional

  • Configures a custom build step to be run by Wrangler when building your Worker. Refer to Custom builds.
  • Not applicable if you're using the Cloudflare Vite plugin.

• no_bundle booleanoptional

  • Skip internal build steps and directly deploy your Worker script. You must have a plain JavaScript Worker with no dependencies.
  • Not applicable if you're using the Cloudflare Vite plugin.

• find_additional_modules booleanoptional

  • If true then Wrangler will traverse the file tree below base_dir. Any files that match rules will be included in the deployed Worker. Defaults to true if no_bundle is true, otherwise false. Can only be used with Module format Workers (not Service Worker format).
  • Not applicable if you're using the Cloudflare Vite plugin.

• base_dir stringoptional

  • The directory in which module "rules" should be evaluated when including additional files (via find_additional_modules) into a Worker deployment. Defaults to the directory containing the main entry point of the Worker if not specified.
  • Not applicable if you're using the Cloudflare Vite plugin.

• preserve_file_names booleanoptional

  • Determines whether Wrangler will preserve the file names of additional modules bundled with the Worker. The default is to prepend filenames with a content hash. For example, 34de60b44167af5c5a709e62a4e20c4f18c9e3b6-favicon.ico.
  • Not applicable if you're using the Cloudflare Vite plugin.

• minify booleanoptional

  • Minify the Worker script before uploading.
  • If you're using the Cloudflare Vite plugin, minify is replaced by Vite's build.minify ↗.

• keep_names booleanoptional

  • Wrangler uses esbuild to process the Worker code for development and deployment. This option allows you to specify whether esbuild should apply its keepNames ↗ logic to the code or not. Defaults to true.

• logpush booleanoptional

  • 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 your account. Defaults to false. Refer to Workers Logpush.

• limits Limitsoptional

  • Configures limits to be imposed on execution at runtime. Refer to Limits.

• observability objectoptional

  • Configures automatic observability settings for telemetry data emitted from your Worker. Refer to Observability.

• assets Assetsoptional

  • Configures static assets that will be served. Refer to Assets for more details.

• exports objectoptional

  • Declares the Durable Object classes this Worker exports and their lifecycle state (created, deleted, renamed, transferred, expecting-transfer). Refer to Durable Object class exports. Mutually exclusive with migrations.

• migrations objectoptional

  • Legacy imperative configuration that maps a Durable Object from a class name to a runtime state. For new Workers, prefer exports. Refer to Durable Object class migrations (legacy).

• placement objectoptional

  • Configures where your Worker runs to minimize latency to back-end services. Refer to Placement.
  • mode string — Set to "smart" to automatically place your Worker near back-end services based on observed latency.
  • region string — Specify a cloud region (for example, "aws:us-east-1", "gcp:europe-west1", or "azure:westeurope") to place your Worker near infrastructure in that region.
  • host string — Specify a hostname and port for a single-homed layer 4 service (for example, "my_database_host.com:5432") to place your Worker near that service.
  • hostname string — Specify a hostname for a single-homed layer 7 service (for example, "my_api_server.com") to place your Worker near that service.

Non-inheritable keys are configurable at the top-level, but cannot be inherited by environments and must be specified for each environment.

• define Record<string, string>optional

  • A map of values to substitute when deploying your Worker.
  • If you're using the Cloudflare Vite plugin, define is replaced by Vite's define ↗.

• vars objectoptional

  • A map of environment variables to set when deploying your Worker. Refer to Environment variables.

• durable_objects objectoptional

  • A list of Durable Objects that your Worker should be bound to. Refer to Durable Objects.

• kv_namespaces objectoptional

  • A list of KV namespaces that your Worker should be bound to. Refer to KV namespaces.

• r2_buckets objectoptional

  • A list of R2 buckets that your Worker should be bound to. Refer to R2 buckets.

• ai_search_namespaces objectoptional

  • A list of AI Search namespaces that your Worker should be bound to. Refer to AI Search namespaces.

• ai_search objectoptional

  • A list of AI Search instance bindings bound directly to pre-existing instances in the default namespace. Refer to AI Search instances.

• vectorize objectoptional

  • A list of Vectorize indexes that your Worker should be bound to. Refer to Vectorize indexes.

• services objectoptional

  • A list of service bindings that your Worker should be bound to. Refer to service bindings.

• queues objectoptional

  • A list of Queue producers and consumers that your Worker should be bound to. Refer to Queues.

• workflows objectoptional

  • A list of Workflows that your Worker should be bound to. Refer to Workflows.

• tail_consumers objectoptional

  • A list of the Tail Workers your Worker sends data to. Refer to Tail Workers.

• secrets objectoptional

  • Declares the secret names your Worker requires. Used for validation during local development and deploy, and as the source of truth for type generation. Refer to Secrets.
  • required string[]optional — A list of secret names that must be set to deploy your Worker.

• secrets_store_secrets objectoptional

  • A list of Secrets Store bindings that your worker should be bound to. Refer to Secrets Store.

There are three types of routes: Custom Domains, routes, and workers.dev.

Custom Domains allow you to connect your Worker to a domain or subdomain, without having to make changes to your DNS settings or perform any certificate management.

• pattern stringrequired

  • The pattern that your Worker should be run on, for example, "example.com".

• custom_domain booleanoptional

  • Whether the Worker should be on a Custom Domain as opposed to a route. Defaults to false.

Example:

{
	"routes": [
		{
			"pattern": "shop.example.com",
			"custom_domain": true,
		},
	],
}

[[routes]]
pattern = "shop.example.com"
custom_domain = true

Routes allow users to map a URL pattern to a Worker. A route can be configured as a zone ID route, a zone name route, or a simple route.

• pattern stringrequired

  • The pattern that your Worker can be run on, for example,"example.com/*".

• zone_id stringrequired

  • The ID of the zone that your pattern is associated with. Refer to Find zone and account IDs.

Example:

{
	"routes": [
		{
			"pattern": "subdomain.example.com/*",
			"zone_id": "<YOUR_ZONE_ID>",
		},
	],
}

[[routes]]
pattern = "subdomain.example.com/*"
zone_id = "<YOUR_ZONE_ID>"

• pattern stringrequired

  • The pattern that your Worker should be run on, for example, "example.com/*".

• zone_name stringrequired

  • The name of the zone that your pattern is associated with. If you are using API tokens, this will require the Account scope.

Example:

{
	"routes": [
		{
			"pattern": "subdomain.example.com/*",
			"zone_name": "example.com",
		},
	],
}

[[routes]]
pattern = "subdomain.example.com/*"
zone_name = "example.com"

This is a simple route that only requires a pattern.

Example:

{
	"route": "example.com/*",
}

route = "example.com/*"

Cloudflare Workers accounts come with a workers.dev subdomain that is configurable in the Cloudflare dashboard.

• workers_dev booleanoptional
  • Whether the Worker runs on a custom workers.dev account subdomain. Defaults to true.

{
	"workers_dev": false,
}

workers_dev = false

Triggers allow you to define the cron expression to invoke your Worker's scheduled function. Refer to Supported cron expressions.

• crons string[]required
  • An array of cron expressions.
  • To disable a Cron Trigger, set crons = []. Commenting out the crons key will not disable a Cron Trigger.

Example:

{
	"triggers": {
		"crons": ["* * * * *"],
	},
}

[triggers]
crons = [ "* * * * *" ]

The Observability setting allows you to automatically ingest, store, filter, and analyze logging data emitted from Cloudflare Workers directly from your Cloudflare Worker's dashboard.

• enabled booleanrequired

  • When set to true on a Worker, logs for the Worker are persisted. Defaults to true for all new Workers.

• head_sampling_rate numberoptional

  • 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%). Read more about head-based sampling.

Example:

{
	"observability": {
		"enabled": true,
		"head_sampling_rate": 0.1, // 10% of requests are logged
	},
}

[observability]
enabled = true
head_sampling_rate = 0.1

You can configure a custom build step that will be run before your Worker is deployed. Refer to Custom builds.

• command stringoptional

  • The command used to build your Worker. On Linux and macOS, the command is executed in the sh shell and the cmd shell for Windows. The && and || shell operators may be used.

• cwd stringoptional

  • The directory in which the command is executed.

• watch_dir string | string[]optional

  • The directory to watch for changes while using wrangler dev. Defaults to the current working directory.

Example:

{
	"build": {
		"command": "npm run build",
		"cwd": "build_cwd",
		"watch_dir": "build_watch_dir",
	},
}

[build]
command = "npm run build"
cwd = "build_cwd"
watch_dir = "build_watch_dir"

You can impose limits on your Worker's behavior at runtime. Limits are only supported for the Standard Usage Model. Limits are only enforced when deployed to Cloudflare's network, not in local development. The CPU limit can be set to a maximum of 300,000 milliseconds (5 minutes).

Each isolate has some built-in flexibility to allow for cases where your Worker infrequently runs over the configured limit. If your Worker starts hitting the limit consistently, its execution will be terminated according to the limit configured.

• cpu_ms numberoptional

  • The maximum CPU time allowed per invocation, in milliseconds.

• subrequests numberoptional

  • 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. Refer to subrequest limits for more information.

Example:

{
	"limits": {
		"cpu_ms": 100,
		"subrequests": 150,
	},
}

[limits]
cpu_ms = 100
subrequests = 150

The Workers Browser Run API allows developers to programmatically control and interact with a headless browser instance and create automation flows for their applications and products.

A browser binding will provide your Worker with an authenticated endpoint to interact with a dedicated Chromium browser instance.

• binding stringrequired
  • The binding name used to refer to the browser binding. The value (string) you set will be used to reference this headless browser in your Worker. The binding must be a valid JavaScript variable name ↗. For example, binding = "HEAD_LESS" or binding = "simulatedBrowser" would both be valid names for the binding.

Example:

{
	"browser": {
		"binding": "<BINDING_NAME>",
	},
}

[browser]
binding = "<BINDING_NAME>"

D1 is Cloudflare's serverless SQL database. A Worker can query a D1 database (or databases) by creating a binding to each database for D1 Workers Binding API.

To bind D1 databases to your Worker, assign an array of the below object to the [[d1_databases]] key.

• binding stringrequired

  • The binding name used to refer to the D1 database. The value (string) you set will be used to reference this database in your Worker. The binding must be a valid JavaScript variable name ↗. For example, binding = "MY_DB" or binding = "productionDB" would both be valid names for the binding.

• database_name stringrequired

  • The name of the database. This is a human-readable name that allows you to distinguish between different databases, and is set when you first create the database.

• database_id stringrequired

  • The ID of the database. The database ID is available when you first use wrangler d1 create or when you call wrangler d1 list, and uniquely identifies your database.

• preview_database_id stringoptional

  • The preview ID of this D1 database. If provided, wrangler dev uses this ID. Otherwise, it uses database_id. This option is required when using wrangler dev --remote.

• migrations_dir stringoptional

  • The migration directory containing the migration files. By default, wrangler d1 migrations create creates a folder named migrations. You can use migrations_dir to specify a different folder containing the migration files (for example, if you have a mono-repo setup, and want to use a single D1 instance across your apps/packages).
  • For more information, refer to D1 Wrangler migrations commands and D1 migrations.

• migrations_pattern stringoptional

  • A glob pattern (relative to your Wrangler config file) used to discover migration files. Defaults to migrations/*.sql.
  • Use this to opt in to nested layouts produced by ORMs like Drizzle (for example, migrations/*/migration.sql).
  • When migrations_pattern is set, migrations_dir must also be set, and migrations_pattern must start with whatever migrations_dir is set to. Each migration is recorded in the migrations table as a path relative to migrations_dir.

Example:

{
	"d1_databases": [
		{
			"binding": "<BINDING_NAME>",
			"database_name": "<DATABASE_NAME>",
			"database_id": "<DATABASE_ID>",
		},
	],
}

[[d1_databases]]
binding = "<BINDING_NAME>"
database_name = "<DATABASE_NAME>"
database_id = "<DATABASE_ID>"

Dispatch namespace bindings allow for communication between a dynamic dispatch Worker and a dispatch namespace. Dispatch namespace bindings are used in Workers for Platforms. Workers for Platforms helps you deploy serverless functions programmatically on behalf of your customers.

• binding stringrequired

  • The binding name. The value (string) you set will be used to reference this database in your Worker. The binding must be a valid JavaScript variable name ↗. For example, binding = "MY_NAMESPACE" or binding = "productionNamespace" would both be valid names for the binding.

• namespace stringrequired

  • The name of the dispatch namespace.

• outbound objectoptional

  • service stringrequired The name of the outbound Worker to bind to.
  • parameters array optional A list of parameters to pass data from your dynamic dispatch Worker to the outbound Worker.

{
	"dispatch_namespaces": [
		{
			"binding": "<BINDING_NAME>",
			"namespace": "<NAMESPACE_NAME>",
			"outbound": {
				"service": "<WORKER_NAME>",
				"parameters": ["params_object"],
			},
		},
	],
}

[[dispatch_namespaces]]
binding = "<BINDING_NAME>"
namespace = "<NAMESPACE_NAME>"

  [dispatch_namespaces.outbound]
  service = "<WORKER_NAME>"
  parameters = [ "params_object" ]

Durable Objects provide low-latency coordination and consistent storage for the Workers platform.

To bind Durable Objects to your Worker, assign an array of the below object to the durable_objects.bindings key.

• name stringrequired

  • The name of the binding used to refer to the Durable Object.

• class_name stringrequired

  • The exported class name of the Durable Object.

• script_name stringoptional

  • The name of the Worker where the Durable Object is defined, if it is external to this Worker. This option can be used both in local and remote development. In local development, you must run the external Worker in a separate process (via wrangler dev). In remote development, the appropriate remote binding must be used.

• environment stringoptional

  • The environment of the script_name to bind to.

Example:

{
	"durable_objects": {
		"bindings": [
			{
				"name": "<BINDING_NAME>",
				"class_name": "<CLASS_NAME>",
			},
		],
	},
}

[[durable_objects.bindings]]
name = "<BINDING_NAME>"
class_name = "<CLASS_NAME>"

The exports field declares the Durable Object classes this Worker exports and their lifecycle state. Refer to Durable Object class exports.

Each entry in exports is keyed by Durable Object class name. The fields on each entry are:

• type stringrequired

  • For Durable Object class entries, set this to "durable-object".

• state stringoptional

  • The lifecycle state. One of "created" (the default — a live class), "deleted", "renamed", "transferred", or "expecting-transfer".

• storage stringconditional

  • Required when state is "created" or "expecting-transfer". One of "sqlite" (recommended; required for new namespaces) or "legacy-kv" (only for existing key-value-backed namespaces).

• renamed_to stringconditional

  • Required when state is "renamed". The destination class name, which must also appear as a live entry in the same exports map.

• transferred_to stringconditional

  • Required when state is "transferred". The name of the target Worker that will receive the namespace.

• transfer_from stringconditional

  • Required when state is "expecting-transfer". The name of the source Worker the namespace is being transferred from.

Example:

{
	"exports": {
		"MyDurableObject": {
			"type": "durable-object",
			"storage": "sqlite",
		},
		"OldClass": {
			"type": "durable-object",
			"state": "deleted",
		},
		"OldName": {
			"type": "durable-object",
			"state": "renamed",
			"renamed_to": "NewName",
		},
		"NewName": {
			"type": "durable-object",
			"storage": "sqlite",
		},
	},
}

[exports.MyDurableObject]
type = "durable-object"
storage = "sqlite"

[exports.OldClass]
type = "durable-object"
state = "deleted"

[exports.OldName]
type = "durable-object"
state = "renamed"
renamed_to = "NewName"

[exports.NewName]
type = "durable-object"
storage = "sqlite"

When making changes to your Durable Object classes on a Worker that uses the legacy migrations array, you must perform a migration. Refer to Durable Object class migrations (legacy).

• tag stringrequired

  • A unique identifier for this migration.

• new_sqlite_classes string[]optional

  • New Durable Object classes being defined with the SQLite storage backend.

• new_classes string[]optional

  • New Durable Object classes being defined with the legacy key-value storage backend.

• renamed_classes {from: string, to: string}[]optional

  • The Durable Object classes being renamed.

• deleted_classes string[]optional

  • The Durable Object classes being removed.

• transferred_classes {from: string, from_script: string, to: string}[]optional

  • The Durable Object classes being transferred from another Worker.

Example:

{
	"migrations": [
		{
			"tag": "v1",
			"new_sqlite_classes": [
				// Array of new classes
				"DurableObjectExample",
			],
		},
		{
			"tag": "v2", // Should be unique for each entry
			"renamed_classes": [
				// Array of rename directives
				{
					"from": "DurableObjectExample",
					"to": "UpdatedName",
				},
			],
			"deleted_classes": [
				// Array of deleted class names
				"DeprecatedClass",
			],
		},
	],
}

[[migrations]]
tag = "v1"
new_sqlite_classes = [ "DurableObjectExample" ]

[[migrations]]
tag = "v2"
deleted_classes = [ "DeprecatedClass" ]

  [[migrations.renamed_classes]]
  from = "DurableObjectExample"
  to = "UpdatedName"