Environments

Wrangler allows you to use environments to create different configurations for the same Worker application. Environments are configured in the Worker's Wrangler configuration file. There is a default (top-level) environment and you can create named environments that provide environment-specific configuration.

Review the following environments flow:

1. Create a Worker, named my-worker for example.
2. Create an environment, for example dev, in the Worker's Wrangler configuration file, by adding a [env.<ENV_NAME>] section.

wrangler.jsonc

{
  "name": "my-worker",
  "env": {
    "<ENV_NAME>": {
      // environment-specific configuration goes here
    }
  }
}

wrangler.toml

name = "my-worker"

[env]
"<ENV_NAME>" = { }

3. You can configure the dev environment with different values to the top-level environment. Refer here for how different options are inherited - or not inherited - between environments.

For example, to set a different route for a Worker in the dev environment:

wrangler.jsonc

{
  "name": "your-worker",
  "route": "example.com",
  "env": {
    "dev": {
      "route": "dev.example.com"
    }
  }
}

wrangler.toml

name = "your-worker"
route = "example.com"

[env.dev]
route = "dev.example.com"

4. Environments are used with the --env or -e flag on Wrangler commands. For example, you can develop the Worker in the dev environment by running npx wrangler dev -e=dev, and deploy it with npx wrangler deploy -e=dev.

Note

Cloudflare effectively creates a new Worker for you when you create a Worker with an environment. Wrangler appends the environment name to the top-level name. For example, a Worker project named my-worker with an environment dev would deploy a Worker named my-worker-dev. You must use this name when referencing a Worker in a particular environment, for example in a service binding.

Non-inheritable keys and environments

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

For example, bindings and environment variables are non-inheritable, and must be specified per environment in your Wrangler configuration file.

Review the following example Wrangler file:

wrangler.jsonc

{
  "name": "my-worker",
  "vars": {
    "API_HOST": "example.com"
  },
  "kv_namespaces": [
    {
      "binding": "<BINDING_NAME>",
      "id": "<KV_NAMESPACE_ID_DEV>"
    }
  ],
  "env": {
    "production": {
      "vars": {
        "API_HOST": "production.example.com"
      },
      "kv_namespaces": [
        {
          "binding": "<BINDING_NAME>",
          "id": "<KV_NAMESPACE_ID_PRODUCTION>"
        }
      ]
    }
  }
}

wrangler.toml

name = "my-worker"

vars = { API_HOST = "example.com" }

kv_namespaces = [
  { binding = "<BINDING_NAME>", id = "<KV_NAMESPACE_ID_DEV>" }
]

[env.production]

vars = { API_HOST = "production.example.com" }

kv_namespaces = [
  { binding = "<BINDING_NAME>", id = "<KV_NAMESPACE_ID_PRODUCTION>" }
]

Service bindings

To use a service binding that targets a Worker in a specific environment, you need to append the environment name to the target Worker name in the service field. This should be in the format <worker-name>-<environment-name>. In the example below, we have two Workers, both with a staging environment. worker-b has a service binding to worker-a. Note how the service field in the staging environment points to worker-a-staging, whereas the top-level service binding points to worker-a.

wrangler.jsonc

{
  "name": "worker-a",
  "vars": {
    "FOO": "<top-level-var>"
  },
  "env": {
    "staging": {
      "vars": {
        "FOO": "<staging-var>"
      }
    }
  }
}

wrangler.toml

name = "worker-a"

vars = { FOO = "<top-level-var>" }
[env.staging.vars]
FOO = "<staging-var>"

wrangler.jsonc

{
  "name": "worker-b",
  "services": {
    "binding": "<BINDING_NAME>",
    "service": "worker-a"
  },
  "env": {
    "staging": {
      "service": {
        "binding": "<BINDING_NAME>",
        "service": "worker-a-staging"
      }
    }
  }
}

wrangler.toml

name = "worker-b"

services = { binding = "<BINDING_NAME>", service = "worker-a" }

# Note how `service = "worker-a-staging"`
env.staging.service ={ binding = "<BINDING_NAME>", service = "worker-a-staging" }

Secrets

You may assign environment-specific secrets by running the command wrangler secret put <KEY> -env. You can also create dotenv type files named .dev.vars.<environment-name>.

Like other environment variables, secrets are non-inheritable and must be defined per environment.

---

Examples

Staging and production environments

The following Wrangler file adds two environments, [env.staging] and [env.production], to the Wrangler file. If you are deploying to a Custom Domain or route, you must provide a route or routes key for each environment.

wrangler.jsonc

{
  "name": "my-worker",
  "route": "dev.example.com/*",
  "vars": {
    "ENVIRONMENT": "dev"
  },
  "env": {
    "staging": {
      "vars": {
        "ENVIRONMENT": "staging"
      },
      "route": "staging.example.com/*"
    },
    "production": {
      "vars": {
        "ENVIRONMENT": "production"
      },
      "routes": [
        "example.com/foo/*",
        "example.com/bar/*"
      ]
    }
  }
}

wrangler.toml

name = "my-worker"
route = "dev.example.com/*"
vars = { ENVIRONMENT = "dev" }

[env.staging]
vars = { ENVIRONMENT = "staging" }
route = "staging.example.com/*"

[env.production]
vars = { ENVIRONMENT = "production" }
routes = [
  "example.com/foo/*",
  "example.com/bar/*"
]

You can pass the name of the environment via the --env flag to run commands in a specific environment.

With this configuration, Wrangler will behave in the following manner:

npx wrangler deploy

Uploaded my-worker
Published my-worker
  dev.example.com/*

npx wrangler deploy --env staging

Uploaded my-worker-staging
Published my-worker-staging
  staging.example.com/*

npx wrangler deploy --env production

Uploaded my-worker-production
Published my-worker-production
  example.com/*

Any defined environment variables (the vars key) are exposed as global variables to your Worker.

With this configuration, the ENVIRONMENT variable can be used to call specific code depending on the given environment:

if (ENVIRONMENT === "staging") {
  // staging-specific code
} else if (ENVIRONMENT === "production") {
  // production-specific code
}

Staging environment with *.workers.dev

To deploy your code to your *.workers.dev subdomain, include workers_dev = true in the desired environment. Your Wrangler file may look like this:

wrangler.jsonc

{
  "name": "my-worker",
  "route": "example.com/*",
  "env": {
    "staging": {
      "workers_dev": true
    }
  }
}

wrangler.toml

name = "my-worker"
route = "example.com/*"

[env.staging]
workers_dev = true

With this configuration, Wrangler will behave in the following manner:

npx wrangler deploy

Uploaded my-worker
Published my-worker
  example.com/*

npx wrangler deploy --env staging

Uploaded my-worker
Published my-worker
  https://my-worker-staging.<YOUR_SUBDOMAIN>.workers.dev

Warning

When you create a Worker via an environment, Cloudflare automatically creates an SSL certification for it. SSL certifications are discoverable and a matter of public record. Be careful when naming your environments that they do not contain sensitive information, such as, migrating-service-from-company1-to-company2 or company1-acquisition-load-test.