In Cloudflare Workers, how does a var differ from a secret, and how does each one reach the Worker's code?
answer
- plaintext config versus encrypted value
- the vars block in the Wrangler file
- wrangler secret put deploys
- same kind of value on env
basics
~20 sA var is plaintext configuration declared under vars in the Wrangler file or the dashboard; a secret is an encrypted value set with wrangler secret put and never displayed again. Both arrive on env as ordinary values.
solid answer
~50 sBoth are bindings on `env`, but they live in different places. A **var** sits in the `vars` block of `wrangler.jsonc` (or is added in the dashboard), is committed with the code and stays readable; it can be a string or a JSON value, so `"RETRY_LIMIT": 3` arrives as a number. A **secret** is set out of band with `npx wrangler secret put PROVIDER_API_KEY` (typed at a prompt or piped in), `wrangler secret bulk` for many at once, or the dashboard's Secret type; it is stored encrypted and its value is hidden in Wrangler and the dashboard afterwards. `wrangler secret put` creates a new version of the Worker and deploys it immediately. Inside the Worker there is no difference: `env.PROVIDER_API_KEY` is just a string. A `wrangler deploy` overwrites vars edited in the dashboard unless `keep_vars` is set, but it never deletes a secret; that takes `wrangler secret delete`.
code
json · 9 lines{
"name": "payments-webhook",
"main": "src/index.js",
"compatibility_date": "2026-10-01",
"vars": {
"REFUNDS_ENABLED": "false",
"RETRY_LIMIT": 3
}
}go deeper
Recall where each lives: vars in the vars block of the Wrangler file, secrets set with wrangler secret put, and both read as env.NAME in the handler.
Explain that secret put deploys a new version at once, that vars can carry JSON types, and that a deploy overwrites dashboard vars unless keep_vars is set.
Show the habits that keep credentials out of repositories and logs, and know that vars and secrets share one per-Worker count of 64 or 128.
Frame where the line sits for a team: which values count as secrets, who may run secret commands, and when per-Worker secrets give way to account-level ones.
## Two kinds of value on `env` A Cloudflare Worker receives its configuration through **bindings**: named properties on the `env` object that the runtime passes to every handler, as in `fetch(request, env, ctx)`. Most bindings hand the Worker a resource such as a KV namespace or an R2 bucket. Two binding types carry plain values instead: - **Environment variables**, usually called **vars**: text or JSON values for ordinary configuration, such as a feature flag, a region or a retry limit. - **Secrets**: encrypted text values for credentials, such as a payment provider's API key or a webhook signing token. Cloudflare's documentation states the relationship directly: secrets *are* environment variables, with one difference. A secret's value is not visible in Wrangler or the dashboard after you define it. To the running Worker nothing distinguishes the two; the value is passed through exactly as it was defined. ## Vars: configuration that travels with the code A var is declared in the `vars` block of the Wrangler configuration file (`wrangler.jsonc` or `wrangler.toml`), so it is versioned and reviewed with the code: - **Values may be strings or JSON.** A JSON number, boolean or object arrives on `env` with that type, so `"RETRY_LIMIT": 3` is the number 3 and `"PROVIDER": { "region": "eu" }` is an object whose `region` can be read directly. A quoted `"false"` stays the string `"false"`, which is truthy in an `if`. - **They change only through a deploy.** A new value in the file reaches the Worker when the next version is deployed, which makes vars a poor fit for anything that must flip at run time without one. - **Everyone with the repository can read them.** That is the point for configuration and the reason a var must never hold a credential. - **The file is the source of truth.** Vars can also be added in the dashboard under **Settings > Variables and Secrets**, but the next `wrangler deploy` overwrites dashboard-edited vars with the file's values unless the file sets `keep_vars: true` (or the deploy passes `--keep-vars`). ## Secrets: set out of band, never shown again A secret never appears in the Wrangler file. It is created through one of these paths: 1. `npx wrangler secret put PROVIDER_API_KEY` prompts for the value, or reads it from piped standard input, so it never lands in a tracked file. 2. `npx wrangler secret bulk secrets.json` creates or updates many secrets in one request (up to 100 per command) from a JSON or `.env`-style file. 3. The dashboard's **Secret** type does the same through the UI; the value is hidden as soon as it is saved. `wrangler secret list` prints the names and the type `secret_text`, never the values. Each `wrangler secret put` or `wrangler secret delete` **creates a new version of the Worker and deploys it immediately**. A team that ships through gradual deployments uses `wrangler versions secret put` instead, which only creates a version for a later `wrangler versions deploy`. ## What a deploy does to each | | Var | Secret | |---|---|---| | Declared in | `vars` in the Wrangler file, or the dashboard | `wrangler secret put` or `bulk`, or the dashboard | | Readable after saving | Yes, in the file and the dashboard | No; only the name is listed | | Stored as | Plaintext | Encrypted | | Value types | String or JSON | String | | On `wrangler deploy` | Replaced by the file's `vars` unless `keep_vars` | Kept until `wrangler secret delete` | | In the Worker | `env.NAME` | `env.NAME` | ## Limits shared by both Vars and secrets draw on one count per Worker: **64 on Workers Free and 128 on Workers Paid**, each value up to **5 KB**. A credential that many Workers need is a reason to look at account-level secrets in Secrets Store, which reach the Worker as a different binding type with an asynchronous `get()`. ## A working rule - If a value would cause harm in a public repository, it is a secret. - If it differs between deployments but is harmless (a region, a timeout, a feature flag), it is a var. - Treat a secret in code like any string you must not print: the runtime hands the Worker the plain value, so a `console.log` of it ends up in logs like any other text. - Read flags explicitly (`env.REFUNDS_ENABLED === "true"`) or declare them as JSON booleans, so a quoted `"false"` cannot switch a feature on.
- Why does `if (env.REFUNDS_ENABLED)` take the branch when the Wrangler file sets that var to "false"?A quoted value in `vars` arrives as the string `"false"`, and any non-empty string is truthy. Compare explicitly (`env.REFUNDS_ENABLED === "true"`) or declare the var as the JSON boolean `false`, which reaches `env` as a boolean. Numbers behave the same way: `3` arrives as a number, `"3"` as a string.
- A teammate changed a var in the dashboard to fix production; what happens on the next `wrangler deploy`?Wrangler overwrites it with the value in the Wrangler file, because the file is treated as the source of truth for vars. Copy the change into the file, or set `keep_vars: true` so dashboard vars survive deploys. Secrets are unaffected either way: a deploy never deletes them, only `wrangler secret delete` does.
- Putting an API key in vars because the repository is private.
- Expecting wrangler deploy to delete a secret that the Wrangler file does not mention.
- Believing secrets reach the Worker encrypted and must be decrypted in code.
- Assuming wrangler secret put only stages the value until the next deploy.
- Treating the quoted var "false" as a boolean false in an if check.