Environments

Background

Wrangler allows you to deploy the same Worker application with different configuration for each environment. You must configure environments in your Worker application's Wrangler file.

Review the following environments flow:

You have created a Worker application named my-worker.
You create an environment, for example, dev, in the Worker's Wrangler configuration file.
In the Wrangler configuration file, you configure the dev environment by adding bindings and/or routes.
You deploy the Worker using npx wrangler deploy -e dev.
In the background, Wrangler creates a new Worker named my-worker-dev.
You can now change your my-worker Worker code and configuration, and choose which environment to deploy your changes to.

Environments are used with the --env or -e flag on wrangler dev, npx wrangler deploy, and wrangler secret.

Configuration

To create an environment:

Open your Worker's Wrangler file.
Add [env.<NAME>] and change <NAME> to the desired name of your environment.
Repeat step 2 to create multiple environments.

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.

Review the layout of an example [env.dev] environment that sets up a custom dev.example.com route:

wrangler.jsonc
wrangler.toml

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

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

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

You cannot specify multiple environments with the same name.

Wrangler appends the environment name to the top-level name to deploy a Worker. For example, a Worker project named my-worker with an environment [env.dev] would deploy a Worker named my-worker-dev.

After you have configured your environment, run npx wrangler deploy in your Worker project directory for the changes to take effect.

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.

Bindings and environment variables must be specified per each environment in your Wrangler configuration file.

Review the following example Wrangler file:

wrangler.jsonc
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>"
        }
      ]
    }
  }
}

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>" }
]

You may assign environment-specific secrets by running the command wrangler secret put <KEY> -env.

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

{
  "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/*"
      ]
    }
  }
}

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/*"
]

In order to use environments with this configuration, you can pass the name of the environment via the --env flag.

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

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

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

[env.staging]
workers_dev = true