Environment variables

Background

Environment variables are a type of binding that allow you to attach text strings or JSON values to your Worker. Environment variables are available on the env parameter passed to your Worker’s fetch event handler.

Text strings and JSON values are not encrypted and are useful for storing application configuration.

Add environment variables via Wrangler

Text and JSON values are defined via the [vars] configuration in your wrangler.toml file. In the following example, API_HOST and API_ACCOUNT_ID are text values and SERVICE_X_DATA is a JSON value.

name = "my-worker-dev"

[vars]
API_HOST = "example.com"
API_ACCOUNT_ID = "example_user"
SERVICE_X_DATA = { URL = "service-x-api.dev.example", MY_ID = 123 }

Refer to the following example on how to access the API_HOST environment variable in your Worker code:

JavaScript

export default {
  async fetch(request, env, ctx) {
    return new Response(`API host: ${env.API_HOST}`);
  }
}

TypeScript

export interface Env {
  API_HOST: string;
}

export default {
  async fetch(request, env, ctx): Promise<Response> {
    return new Response(`API host: ${env.API_HOST}`);
  }
} satisfies ExportedHandler<Env>;

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

To define environment variables for different environments, refer to the example below:

name = "my-worker-dev"

[env.staging.vars]
API_HOST = "staging.example.com"
API_ACCOUNT_ID = "staging_example_user"
SERVICE_X_DATA = { URL = "service-x-api.dev.example", MY_ID = 123 }

[env.production.vars]
API_HOST = "production.example.com"
API_ACCOUNT_ID = "production_example_user"
SERVICE_X_DATA = { URL = "service-x-api.prod.example", MY_ID = 456 }

For local development with wrangler dev, variables in wrangler.toml are automatically overridden by any values defined in a .dev.vars file located in the root directory of your worker. This is useful for providing values you do not want to check in to source control.

API_HOST = "localhost:4000"
API_ACCOUNT_ID = "local_example_user"

Alternatively, you can specify per-environment values in wrangler.toml and provide an environment value via the env flag when developing locally like so wrangler dev --env=local.

Add environment variables via the dashboard

To add environment variables via the dashboard:

1. Log in to Cloudflare dashboard ↗ and select your account.
2. Select Workers & Pages.
3. In Overview, select your Worker.
4. Select Settings.
5. Select Variables.
6. Under Environment Variables, select Add variable.
7. Input a Variable name and its Value, which will be made available to your Worker.
8. (Optional) To add multiple environment variables, select Add variable.
9. Select Save and deploy to implement your changes.

Plaintext strings and secrets

Only select Encrypt if your environment variable is a secret.

Compare secrets and environment variables

Use secrets for sensitive information

Do not use plaintext environment variables to store sensitive information. Use secrets instead.

Secrets are environment variables. The difference is secret values are not visible within Wrangler or Cloudflare dashboard 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.

Related resources

• Learn how to access environment variables in ES modules syntax for an optimized experience.