In a Wrangler configuration file, which keys does an env block inherit from the top level, and why must vars and bindings be repeated?
answer
- each environment is its own Worker
- name gets a suffix
- inherited keys replace, never merge
- bindings and vars stay behind
basics
~20 sAn env block inherits most keys, such as main, compatibility_date, routes, triggers and limits, and its Worker is named name-env. Vars, define and every binding are not inherited, so a block that omits them gets none, and Wrangler only warns.
solid answer
~40 sEach `env.<name>` block deploys as a separate Worker, named `<name>-<env>` unless the block sets `name` itself. Inheritable keys such as `main`, `compatibility_date`, `compatibility_flags`, `routes`, `workers_dev`, `triggers`, `limits` and `placement` fall through from the top level, and setting one in the block replaces it whole. Non-inheritable keys, meaning `vars`, `define`, `secrets` and every binding (`kv_namespaces`, `d1_databases`, `r2_buckets`, `durable_objects`, `services` and the rest), must be repeated: if `env.staging` omits `kv_namespaces`, staging's `env.CACHE` is `undefined`, and Wrangler prints a warning rather than failing. A few keys, such as `keep_vars` and `send_metrics`, are top-level only. The effect is that each environment's data is chosen deliberately, so staging never picks up production's namespace by inheritance.
code
json · 43 lines{
"$schema": "./node_modules/wrangler/config-schema.json",
"name": "orders-api",
"main": "src/index.js",
"compatibility_date": "2026-10-01",
"workers_dev": false,
"env": {
"staging": {
"workers_dev": true,
"vars": {
"STAGE": "staging"
},
"kv_namespaces": [
{
"binding": "CACHE",
"id": "22222222222222222222222222222222"
}
]
},
"production": {
"routes": [
{
"pattern": "api.example.com",
"custom_domain": true
}
],
"triggers": {
"crons": [
"0 3 * * *"
]
},
"vars": {
"STAGE": "production"
},
"kv_namespaces": [
{
"binding": "CACHE",
"id": "33333333333333333333333333333333"
}
]
}
}
}go deeper
Recall that each environment deploys as its own Worker named name-env, chosen with --env on the command line.
Explain the split: inheritable keys fall through and are replaced whole, while vars, define and every binding must be declared in each env block.
Show you read Wrangler's warnings, know that a missing binding deploys anyway, and can reason about which Worker a command targets without --env.
Argue for a layout rule, shared keys only at the top level and everything stateful inside its environment, and enforce it in review.
## One file, several Workers A **Wrangler environment** is a named block under `env` in the Wrangler configuration file, such as `env.staging` or `env.production`, selected with `--env` (or `-e`) on a Wrangler command. Each environment deploys as its **own Worker**. Unless the block sets its own `name`, Wrangler names that Worker `<top-level name>-<environment name>`, so `orders-api` with `env.staging` deploys `orders-api-staging`. If the block does set `name`, that value is used as written, with no suffix. The top level of the file is itself an environment too, the default one, and deploys under the plain `name`. Because every environment is a separate Worker, it has its own `env` object, its own traffic and its own secrets. The file decides what each one starts from, and the rule is the subject of this question. ## What an environment inherits Most keys are **inheritable**: if `env.staging` leaves a key out, staging uses the top-level value. Among them: - `name` (with the environment suffix appended), `main`, `compatibility_date`, `compatibility_flags` and `account_id` - `route`, `routes`, `workers_dev` and `preview_urls` - `triggers`, `limits`, `placement` and `observability` - build settings such as `build`, `minify`, `no_bundle` and `rules`, plus `assets` and `migrations` An inheritable key set inside the environment **replaces** the top-level value whole. It is not merged: if the top level lists two Cron Triggers and `env.production` lists one, production gets exactly one. ## What it does not inherit | Kind of key | Examples | Left out of an env block | |---|---|---| | Non-inheritable | `vars`, `define`, `secrets`, and every binding: `kv_namespaces`, `d1_databases`, `r2_buckets`, `durable_objects`, `services`, `queues`, `workflows`, `hyperdrive`, `ai`, `vectorize`, `tail_consumers` | the environment gets **none**, and Wrangler warns | | Top-level only | `keep_vars`, `send_metrics`, `addresses`, `dependencies_instrumentation` | apply to every environment; inside an env block they are reported as unexpected fields and ignored | So a staging block that omits `kv_namespaces` produces a staging Worker whose `env.CACHE` is `undefined`. Under `wrangler dev --env staging`, a handler that returns `env.CACHE !== undefined` answers `false`, and the same handler at the top level answers `true`. Wrangler prints this while processing the file: ```plaintext - "env.staging" environment configuration - "kv_namespaces" exists at the top level, but not on "env.staging". This is not what you probably want, since "kv_namespaces" is not inherited by environments. ``` It is a **warning, not an error**: the deploy goes ahead without the binding. Secrets follow the same rule, set per environment with `--env`. ## Choosing the environment on the command line 1. `--env staging` (or `-e staging`) selects the block; the `CLOUDFLARE_ENV` environment variable does the same, and the flag wins when both are set. 2. `--env=""` explicitly targets the top-level Worker. 3. With environments defined but none selected, commands such as `wrangler deploy` target the top level and warn that no target environment was specified. 4. Naming an environment the file does not define is an error when other environments exist, and only a warning when the file defines none. ## Why bindings are explicit The effect of the rule is that each environment's data is chosen on purpose. If bindings were inherited, a forgotten line in `env.staging` would leave staging reading and writing production's KV namespace or database without any sign. Under the real rule, the same mistake gives staging no binding at all, which fails loudly on the first request and is flagged in Wrangler's output before that. The cost is repetition: every binding, var and service binding target (for example `worker-a-staging` instead of `worker-a`) is written once per environment. ## A layout that stays safe A common layout follows from the rules above: - The top level holds only what every environment truly shares: `name`, `main`, `compatibility_date`, `compatibility_flags` and perhaps `observability`. - Each environment holds its own `vars`, every binding with that environment's resource IDs, its own routes or `workers_dev`, and its own Cron Triggers. - The top level sets `"workers_dev": false`, and an environment that needs a test URL turns it back on. - Reviews read Wrangler's configuration warnings, because a missing binding or an inherited route is reported there before anything breaks. With that shape, adding an environment means writing a complete block, and forgetting a line produces a missing binding rather than a shared one.
- What happens if you run wrangler deploy without --env when the file defines environments?Wrangler deploys the top-level Worker, the plain `name`, and warns that multiple environments are defined but no target environment was specified. To target the top level on purpose and make the intent visible in CI, pass `--env=""`. The `CLOUDFLARE_ENV` variable can select an environment instead of the flag, but `--env` wins when both are set.
- How does a service binding reach another Worker's staging environment?Each environment is a separate Worker, so the binding names that Worker: inside `env.staging`, the `services` entry uses `"service": "worker-a-staging"`, while the top level points at `worker-a`. Because `services` is not inherited, the staging block must declare the entry itself; leaving it out gives the staging Worker no service binding at all.
- What does Wrangler do with keep_vars written inside env.staging?`keep_vars` is a top-level-only key, so inside an environment Wrangler reports it as an unexpected field in `env.staging` and ignores it. Top-level-only keys, which include `send_metrics` and `addresses`, apply to the Worker project as a whole, in every environment, and are written once at the top of the file.
A branch office copies the head office's letterhead and opening hours automatically, but it is never handed the head office's keys or bank cards; each branch gets its own, or has none.
- An env block inherits the top-level KV namespaces and D1 databases automatically
- Every environment deploys as a new version of the same Worker
- An env block's triggers list is merged with the top-level triggers list
- Wrangler refuses to deploy when an environment omits a top-level binding
- keep_vars can be switched on for just one environment