skip to content

Bindings, Vars & Secrets

Bindings hand a Worker its resources and settings on env instead of URLs and keys. Interviewers ask how secrets differ from vars and why a binding beats an API token in code.

on this pageshow

explore

questions

6

In Cloudflare Workers, how does a var differ from a secret, and how does each one reach the Worker's code?

level: juniorimportance: must knowfreq 72%

answer

  1. plaintext config versus encrypted value
  2. the vars block in the Wrangler file
  3. wrangler secret put deploys
  4. same kind of value on env

basics

~20 s

A 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 s

Both 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
json
{
  "name": "payments-webhook",
  "main": "src/index.js",
  "compatibility_date": "2026-10-01",
  "vars": {
    "REFUNDS_ENABLED": "false",
    "RETRY_LIMIT": 3
  }
}

go deeper

for a junior

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.

for a middle

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.

for a senior

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.

for a principal

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.
open as a page

Why does a Cloudflare Worker reach its KV namespace and R2 bucket through bindings on env rather than through an API token?

level: middleimportance: must knowfreq 58%

basics

~20 s

A binding hands the Worker a ready-made object for one resource, such as env.RECEIPTS for an R2 bucket, with the permission built in. No token sits in code to leak, and no REST endpoint has to be called.

open as a page

In Cloudflare Workers, what does `import { env } from "cloudflare:workers"` let module-level code do, and which binding calls still fail there?

level: middleimportance: should knowfreq 30%

basics

~20 s

It exposes the Worker's bindings at module level and in nested functions without passing env along. Top-level code may read vars and secrets, but I/O such as a KV get or a service binding call throws outside a handler.

open as a page

In a TypeScript Cloudflare Worker, what does `wrangler types` generate from the Wrangler file, and how does it type vars and secrets?

level: middleimportance: should knowfreq 28%

basics

~20 s

wrangler types writes worker-configuration.d.ts with an Env interface listing every binding's type, plus runtime types for the compatibility date. Vars get literal types by default; secrets are typed string, named from secrets.required when it is declared.

open as a page

When a team moves a payment provider key from per-Worker secrets into Cloudflare Secrets Store, what changes in configuration, permissions and Worker code?

level: seniorimportance: should knowfreq 20%

basics

~20 s

The key becomes one account-level secret bound into each Worker through secrets_store_secrets. Binding needs a role or token that can bind plus the workers scope, and code reads it with await env.PROVIDER_KEY.get() instead of a string.

open as a page

After `wrangler secret put` replaced a Cloudflare Worker's payment provider key, some requests kept using the old key; what in the code explains it?

level: seniorimportance: should knowfreq 36%

basics

~20 s

A provider client built in global scope from the old secret. A deploy that changes only bindings may reuse running isolates, so a module-level object keeps the value it was built with, while each request's env carries the new one.

open as a page