Environment variables

In the Workers platform, environment variables, secrets, and KV namespaces are known as bindings. Regardless of type, bindings are always available as global variables within your Worker script.

​​ Environment variables with module Workers

When deploying a Module Worker, any bindings will not be available as global runtime variables. Instead, they are passed to the handler as a parameter – refer to the FetchEvent documentation for further comparisons and examples.

​​ Environment variables via wrangler

​​ Add environment variables via Wrangler

Environment variables are defined via the [vars] configuration in your wrangler.toml file and are always plaintext values.

wrangler.toml
name = "my-worker-dev"

# Define top-level environment variables
# under the `[vars]` block using
# the `key = "value"` format
[vars]
API_TOKEN = "example_dev_token"
STRIPE_TOKEN = "pk_xyz1234_test"

# Override values for `--env production` usage
[env.production]
name = "my-worker-production"
[env.production.vars]
API_TOKEN = "example_production_token"
STRIPE_TOKEN = "pk_xyz1234"

These environment variables can then be accessed within your Worker script as global variables. They will be plaintext strings.

// Worker code:
console.log(API_TOKEN);
//=> (default) "example_dev_token"
//=> (env.production) "example_production_token"

console.log(STRIPE_TOKEN);
//=> (default) "pk_xyz1234_test"
//=> (env.production) "pk_xyz1234"

If using module Workers, your environment variables are available on the env parameter passed to your Worker’s fetch event handler. Refer to the following example:

export interface Env {
  API_TOKEN: string;
}
export default {
  async fetch(
    request: Request,
    env: Env,
    ctx: ExecutionContext
  ): Promise<Response> {
    console.log(env.API_TOKEN)
  }
}

​​ Add secrets to your project

​​ Secrets in development

When developing your Worker or Pages Functions, create a .dev.vars file in the root of your project to define variables that will be used when running wrangler dev or wrangler pages dev, as opposed to using another environment and [vars] in wrangler.toml. This works both in the local and remote development modes.

The .dev.vars file should be formatted like a dotenv file, such as KEY=VALUE.

.dev.vars
SECRET_KEY=value

​​ Secrets on deployed Workers

Secrets are defined by running wrangler secret put <KEY> in your terminal, where <KEY> is the name of your binding. You may assign environment-specific secrets by rerunning the command wrangler secret put <KEY> -e or wrangler secret put <KEY> --env. Keep a detailed list of the secrets used in your code in your wrangler.toml file, like the example under [vars]:

wrangler.toml
[vars]
# ...

# ...

# The necessary secrets are:
# - SPARKPOST_KEY
# - GTOKEN_PRIVKEY
# - GTOKEN_KID
# Run `echo <VALUE> | wrangler secret put <NAME>` for each of these

​​ Add KV namespaces via Wrangler

KV namespaces are defined via the kv_namespaces configuration in your wrangler.toml and are always provided as KV runtime instances.

wrangler.toml
name = "my-worker-dev"

[[kv_namespaces]]
binding = "Customers"
preview_id = "<PREVIEW KV NAMESPACEID>"
id = "<DEV KV NAMESPACEID>"

[env.production]
name = "my-worker-production"
[[kv_namespaces]]
binding = "Customers"
id = "<PRODUCTION KV NAMESPACEID>"

​​ Environment variables via the dashboard

​​ Add environment variables via the dashboard

Add environment variables by logging in to Cloudflare dashboard Open external link > Account Home > Workers and select your Workers script.

To add environment variables, such as vars and secret:

1. Go to your Workers script > Settings > Add variable under Environment Variables.
2. Input a Variable name and its value, which will be made available to your Worker.
3. If your variable is a secret, select Encrypt to protect its value. This will prevent the value from being visible via Wrangler and the dashboard.
4. (Optional) To add multiple environment variables, select Add variable.
5. Select Save to implement your changes.

​​ Add KV namespace bindings via the dashboard

To add KV namespace bindings:

1. Go to your Workers script > Settings > Add binding under KV Namespace Bindings.
2. Choose a Variable name. This will be the way the variable name will be referenced in your Worker script.
3. Next, select a KV namespace from the dropdown.
4. Select Add binding to add multiple bindings.
5. When you are finished, select Save to implement your changes.

Your completed Workers dashboard, with environment variables and KV namespace bindings added, will look like the following example reference.

​​ Compare secrets and environment variables

Secrets are environment variables. The difference is secret values are not visible within Wrangler or dashboard interfaces after you define them. This means that sensitive data, including passwords or API tokens, should always be encrypted to prevent data leaks. To your Worker, there is no difference between an environment variable and a secret. The secret’s value is passed through as defined.