Environment variables

Background

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

Text strings and JSON values are not encrypted and are useful for storing application configuration. If you need to store sensitive information (such as API keys or tokens), use secrets.

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

Note

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.

Managing environment variables across multiple environments

Since vars is a non-inheritable key, you need to explicitly define your environment variables for each environment (for example, staging and production).

wrangler.jsonc

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

wrangler.toml

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 }

Overriding environment variables during local development

When running wrangler dev, variables in the Wrangler configuration file 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 the Wrangler configuration file and provide an environment value via the --env flag when developing locally:

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

Secrets vs Environment Variables

Use secrets for sensitive information

Never store sensitive information in plaintext environment variables. Always use secrets for data like passwords or API tokens.

When to use secrets

If your environment variable is a secret (such as a password or API token), select the Secret type when adding it via the dashboard or use Wrangler's built-in command:

 wrangler secret put <KEY>

Secrets function similarly to environment variables in a Worker, but with crucial differences:

• Visibility: Once you define a secret, its value is no longer visible in Wrangler or the Cloudflare dashboard.

• Security: Sensitive data, such as passwords and tokens, should always be encrypted to prevent accidental exposure.

To your Worker, there is no difference between an environment variable and a secret. The secret's value is passed through as defined.

When to use plaintext environment variables

Plaintext environment variables are best for non-sensitive configuration details, such as hostnames and IDs. These are values that do not require encryption because leaking them does not compromise security or privacy.

Related resources

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