Configuration (18)

Last updated Apr 23, 2026 Caution

This page is for Wrangler v1, which has been deprecated. Learn how to update to the latest version of Wrangler.

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:

  • build
  • dev
  • preview
  • publish
  • secret

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:

  • Top level only keys are required to be configured at the top level of your Wrangler file only; multiple environments on the same project must share this key's value.
  • Inherited keys can be configured at the top level and/or environment. If the key is defined only at the top level, the environment will use the key's value from the top level. If the key is defined in the environment, the environment value will override the top-level value.
  • Non-inherited keys must be defined for every environment individually.
  • name inherited required
  • The name of your Worker script. If inherited, your environment name will be appended to the top level.
  • type top level required
  • Specifies how wrangler build will build your project. There are three options: javascript, webpack, and rust. javascript checks for a build command specified in the [build] section, webpack builds your project using webpack v4, and rust compiles the Rust in your project to WebAssembly.

Note

Cloudflare will continue to support rust and webpack project types, but recommends using the javascript project type and specifying a custom build section.

  • account_id inherited required
  • 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_id you provide, if you provide one. It can also be specified through the CF_ACCOUNT_ID environment variable.
  • zone_id inherited optional
  • This is the ID of the zone or domain you want to run your Worker on. It can also be specified through the CF_ZONE_ID environment variable. This key is optional if you are using only a *.workers.dev subdomain.
  • workers_dev inherited optional
  • This is a boolean flag that specifies if your Worker will be deployed to your *.workers.dev ↗︎ subdomain. If omitted, it defaults to false.
  • route not inherited optional
  • A route, specified by URL pattern, on your zone that you would like to run your Worker on.
    route = "http://example.com/*". A route OR routes key is only required if you are not using a *.workers.dev ↗︎ subdomain.
  • routes not inherited optional
  • A list of routes you would like to use your Worker on. These follow exactly the same rules a route, but you can specify a list of them.
    routes = ["http://example.com/hello", "http://example.com/goodbye"]. A route OR routes key is only required if you are not using a *.workers.dev subdomain.
  • webpack_config inherited optional
  • This is 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 for you. Refer to the Wrangler webpack page for more information.
  • vars not inherited optional
  • An object containing text variables that can be directly accessed in a Worker script.
  • kv_namespaces not inherited optional
  • These specify any Workers KV Namespaces you want to access from inside your Worker.
  • site inherited optional
  • Determines the local folder to upload and serve from a Worker.
  • dev not inherited optional
  • Arguments for wrangler dev that configure local server.
  • triggers inherited optional
  • Configures cron triggers for running a Worker on a schedule.
  • usage_model inherited optional
  • Specifies the Usage Model for your Worker. There are two options - bundled and unbound. For newly created Workers, if the Usage Model is omitted it will be set to the default Usage Model set on the account ↗︎. For existing Workers, if the Usage Model is omitted, it will be set to the Usage Model configured in the dashboard for that Worker.
  • build top level optional
  • Configures a custom build step to be run by Wrangler when building your Worker. Refer to the custom builds documentation for more details.

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"

Note

Secrets should be handled using the wrangler secret command.

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
  • binding required
  • The name of the global variable your code will reference. It will be provided as a KV runtime instance.
  • id required
  • The ID of the KV namespace that your binding should represent. Required for wrangler publish.
  • preview_id required
  • The ID of the KV namespace that your binding should represent during wrangler dev or wrangler preview. Required for wrangler dev and wrangler preview.

Note

Creating your KV namespaces can be handled using Wrangler’s KV Commands.

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

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"
  • bucket required
  • The directory containing your static assets. It must be a path relative to your Wrangler file. Example: bucket = "./public"
  • entry-point optional
  • The location of your Worker script. The default location is workers-site. Example: entry-point = "./workers-site"
  • include optional
  • An exclusive list of .gitignore-style patterns that match file or directory names from your bucket location. Only matched items will be uploaded. Example: include = ["upload_dir"]
  • exclude optional
  • A list of .gitignore-style patterns that match files or directories in your bucket that should be excluded from uploads. Example: exclude = ["ignore_dir"]

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