Skip to content
Cloudflare Docs

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.

When you create an environment, Cloudflare effectively creates a new Worker with the name <top-level-name>-<environment-name>. For example, a Worker project named my-worker with an environment dev would deploy as a Worker named my-worker-dev.

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.

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

  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:

    {
      "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.

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:

{
  "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.

{
  "name": "worker-a",
  "vars": {
    "FOO": "<top-level-var>"
  },
  "env": {
    "staging": {
      "vars": {
        "FOO": "<staging-var>"
      }
    }
  }
}
 
{
  "name": "worker-b",
  "services": {
    "binding": "<BINDING_NAME>",
    "service": "worker-a"
  },
  "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.

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

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:

Terminal window
npx wrangler deploy
Uploaded my-worker
Published my-worker
  dev.example.com/*
Terminal window
npx wrangler deploy --env staging
Uploaded my-worker-staging
Published my-worker-staging
  staging.example.com/*
Terminal window
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:

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

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

Terminal window
npx wrangler deploy
Uploaded my-worker
Published my-worker
  example.com/*
Terminal window
npx wrangler deploy --env staging
Uploaded my-worker
Published my-worker
  https://my-worker-staging.<YOUR_SUBDOMAIN>.workers.dev