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 file. In the following example, API_HOST and API_ACCOUNT_ID are text values and SERVICE_X_DATA is a JSON value.

wrangler.jsonc

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

wrangler.toml

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>;

Configuring different environments in Wrangler

Environments in Wrangler let you specify different configurations for the same Worker, including different values for vars in each environment. As vars is a non-inheritable key, they are not inherited by environments and must be specified for each environment.

The example below sets up two environments, staging and production, with different values for API_HOST.

wrangler.jsonc

{
  "name": "my-worker-dev",
  "vars": {
    "API_HOST": "api.example.com"
  },
  "env": {
    "staging": {
      "vars": {
        "API_HOST": "staging.example.com"
      }
    },
    "production": {
      "vars": {
        "API_HOST": "production.example.com"
      }
    }
  }
}

wrangler.toml

name = "my-worker-dev"

# top level environment
[vars]
API_HOST = "api.example.com"

[env.staging.vars]
API_HOST = "staging.example.com"

[env.production.vars]
API_HOST = "production.example.com"

To run Wrangler commands in specific environments, you can pass in the --env or -e flag. For example, you can develop the Worker in an environment called staging by running npx wrangler dev --env staging, and deploy it with npx wrangler deploy --env staging.

Learn about environments in Wrangler.

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. Under Variables and Secrets, select Add.
6. Select a Type, input a Variable name, and input its Value. This variable will be made available to your Worker.
7. (Optional) To add multiple environment variables, select Add variable.
8. Select Deploy to implement your changes.

Plaintext strings and secrets

Select the Secret type 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.

When developing your Worker or Pages Function, create a .dev.vars file in the root of your project to define secrets that will be used when running wrangler dev or wrangler pages dev, as opposed to using environment variables in the Wrangler configuration file. This works both in 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"
API_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9"

To set different secrets for each environment, create files named .dev.vars.<environment-name>. When you use wrangler <command> --env <environment-name>, the corresponding environment-specific file will be loaded instead of the .dev.vars file.

Like other environment variables, secrets are non-inheritable and must be defined per environment.

Related resources

• Migrating environment variables from Service Worker format to ES modules syntax.