Configuration (17)

Last updated Oct 20, 2026 Wrangler optionally uses a configuration file to customize the development and deployment setup for a Worker.

Note

As of Wrangler v3.91.0 Wrangler supports both JSON (wrangler.json or wrangler.jsonc) and TOML (wrangler.toml) for its configuration file. Prior to that version, only wrangler.toml was supported.

Cloudflare recommends using wrangler.jsonc for new projects, and some newer Wrangler features will only be available to projects using a JSON config file.

The format of Wrangler's configuration file is exactly the same across both languages, only the syntax differs.

You can use one of the many available online converters to easily switch between the two.

Throughout this page and the rest of Cloudflare's documentation, configuration snippets are provided as both JSON and TOML.

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

Sample Wrangler configuration

{
    "$schema": "./node_modules/wrangler/config-schema.json",
    // Top-level configuration
    "name": "my-worker",
    "main": "src/index.js",
    "upload_source_maps": true,
    // Set this to today's date
    "compatibility_date": "2026-10-27",
    "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"
upload_source_maps = true
# Set this to today's date
compatibility_date = "2026-10-27"
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>"

Environments

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.

Note

If you're using the Cloudflare Vite plugin, you select the environment at dev or build time via the CLOUDFLARE_ENV environment variable rather than the --env flag. Otherwise, environments are defined in your Worker config file as usual. For more detail on using environments with the Cloudflare Vite plugin, refer to the plugin documentation.

Automatic provisioning

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 only keys

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

  • keep_vars boolean optional
  • Whether Wrangler should keep variables configured in the dashboard on deploy. Refer to source of truth.
  • addresses string[] optional
  • A list of inbound email addresses that Email Routing routes to this Worker. Each entry is either a literal recipient address (for example, support@example.com) or a *@domain catch-all (for example, *@example.com). Catch-all entries support apex domains only. When you deploy the Worker or its triggers, Wrangler reconciles the Worker's managed Email Routing rules with this list.
  • send_metrics boolean optional
  • 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 object optional
  • 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 object optional 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

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

Note

At a minimum, the name, main and compatibility_date keys are required to deploy a Worker.

The main key is optional for assets-only Workers.

  • name string required
  • 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 string required
  • The path to the entrypoint of your Worker that will be executed. For example: ./src/index.ts.
  • compatibility_date string required
  • 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 string optional
  • 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 boolean optional
  • 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 when the configuration has no route or routes, and false otherwise. Refer to types of routes.
  • preview_urls boolean optional
  • Enables Version URLs and workers.dev Preview URLs. If omitted, Wrangler does not change an existing setting. If no setting exists, its initial value depends on workers_dev. Refer to Version URLs and Previews.
  • route Route optional
  • 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 string optional
  • Path to a custom tsconfig.
  • Not applicable if you're using the Cloudflare Vite plugin.
  • triggers object optional
  • Cron definitions to trigger a Worker's scheduled function. Refer to triggers.
  • rules Rule optional
  • 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 Build optional
  • 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 boolean optional
  • 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 boolean optional
  • 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 string optional
  • 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 boolean optional
  • 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 boolean optional
  • Minify the Worker script before uploading.
  • If you're using the Cloudflare Vite plugin, minify is replaced by Vite's build.minify ↗︎.
  • keep_names boolean optional
  • 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 boolean optional
  • 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 Limits optional

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

  • observability object optional

  • Configures automatic observability settings for telemetry data emitted from your Worker. Refer to Observability.
  • assets Assets optional
  • Configures static assets that will be served. Refer to Assets for more details.
  • exports object optional
  • Declares the Durable Object classes this Worker exports and their lifecycle state ( created, deleted, renamed, transferred, expecting-transfer). Refer to Durable Object class exports. Durable Object entries are mutually exclusive with migrations.
  • Declares the Workflows this Worker defines. Refer to Workflow exports.
  • migrations object optional
  • 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 object optional
  • 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

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