Environment variables
You can add environment variables, which are a type of binding, 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.
To add env variables using Wrangler, define text and JSON 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.
{ "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 } }}
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:
export default { async fetch(request, env, ctx) { return new Response(`API host: ${env.API_HOST}`); },};
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>;
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
.
{ "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" } } }}
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.
To add environment variables via the dashboard:
- Log in to Cloudflare dashboard ↗ and select your account.
- Select Workers & Pages.
- In Overview, select your Worker.
- Select Settings.
- Under Variables and Secrets, select Add.
- Select a Type, input a Variable name, and input its Value. This variable will be made available to your Worker.
- (Optional) To add multiple environment variables, select Add variable.
- Select Deploy to implement your changes.
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.
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.
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)
When you enable both the nodejs_compat
and
nodejs_compat_populate_process_env
compatibility flags, and the disallow_importable_env
compatibility flag is
not set, environment variables will also be available via the global
process.env
. Note that the nodejs_compat_populate_process_env
flag is
enabled automatically when nodejs_compat
is used with a compatibility date
on or after April 1st, 2025.
The process.env
will be populated lazily the first time that process
is accessed
in the worker.
Text variable values are exposed directly.
JSON variable values that evaluate to string values are exposed as the parsed value.
JSON variable values that do not evaluate to string values are exposed as the raw JSON string.
For example, imagine a Worker with three environment variables, two text values, and one JSON value:
[vars]FOO = "abc"BAR = "abc"BAZ = { "a": 123 }
Environment variables can be added using either the wrangler.{json|jsonc|toml}
file or via the Cloudflare
dashboard UI.
The values of process.env.FOO
and process.env.BAR
will each be the
JavaScript string "abc"
.
The value of process.env.BAZ
will be the JSON-encoded string "{ \"a\": 123 }"
.
Was this helpful?
- Resources
- API
- New to Cloudflare?
- Directory
- Sponsorships
- Open Source
- Support
- Help Center
- System Status
- Compliance
- GDPR
- Company
- cloudflare.com
- Our team
- Careers
- © 2025 Cloudflare, Inc.
- Privacy Policy
- Terms of Use
- Report Security Issues
- Trademark
-