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.

Use Wrangler environments for persistent Workers such as staging or development. Use Previews when you want every branch or pull request to get a URL. For the difference between these workflows, refer to Compare workflows.

Review the following environments flow:

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:

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"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>",
				},
			],
		},
	},
}

"$schema" = "./node_modules/wrangler/config-schema.json"
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"

[[env.production.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.

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "worker-a",
	"vars": {
		"FOO": "<top-level-var>",
	},
	"env": {
		"staging": {
			"vars": {
				"FOO": "<staging-var>",
			},
		},
	},
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "worker-a"

[vars]
FOO = "<top-level-var>"

[env.staging.vars]
FOO = "<staging-var>"

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"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",
			},
		},
	},
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "worker-b"

[services]
binding = "<BINDING_NAME>"
service = "worker-a"

[env.staging.service]
binding = "<BINDING_NAME>"
service = "worker-a-staging"

Secrets for production

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.

Secrets in local development

Put secrets for use in local development in either a .dev.vars file or a .env file, in the same directory as the Wrangler configuration file.

:::info Choose to use either .dev.vars or .env but not both. If you define a .dev.vars file, then values in .env files will not be included in the env object during local development. :::

These files should be formatted using the dotenv syntax. For example:

SECRET_KEY="value"
API_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9"

To set different secrets for each Cloudflare environment, create files named .dev.vars.<environment-name> or .env.<environment-name>.

When you select a Cloudflare environment in your local development, the corresponding environment-specific file will be loaded ahead of the generic .dev.vars (or .env) file.

• When using .dev.vars.<environment-name> files, all secrets must be defined per environment. If .dev.vars.<environment-name> exists then only this will be loaded; the .dev.vars file will not be loaded.
• In contrast, all matching .env files are loaded and the values are merged. For each variable, the value from the most specific file is used, with the following precedence:
  • .env.<environment-name>.local (most specific)
  • .env.local
  • .env.<environment-name>
  • .env (least specific)

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.

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"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/*"],
		},
	},
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "my-worker"
route = "dev.example.com/*"

[vars]
ENVIRONMENT = "dev"

[env.staging]
route = "staging.example.com/*"

[env.staging.vars]
ENVIRONMENT = "staging"

[env.production]
routes = [ "example.com/foo/*", "example.com/bar/*" ]

[env.production.vars]
ENVIRONMENT = "production"

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 available via the env object in your Worker.

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

export default {
	async fetch(request, env, ctx) {
		if (env.ENVIRONMENT === "staging") {
			// staging-specific code
		} else if (env.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:

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "my-worker",
	"route": "example.com/*",
	"env": {
		"staging": {
			"workers_dev": true,
		},
	},
}

"$schema" = "./node_modules/wrangler/config-schema.json"
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