skip to content

In Cloudflare Workers, what happens on the next wrangler deploy to vars, routes and secrets someone changed in the dashboard instead of the Wrangler file?

level: middleimportance: should knowfreq 25%

answer

  1. the file is the source of truth
  2. vars are replaced, not merged
  3. one top-level switch for vars
  4. secrets always survive

basics

~20 s

wrangler deploy deletes dashboard vars the file does not list unless keep_vars or --keep-vars is set, replaces routes with the file's list when it has any, and always keeps secrets until wrangler secret delete removes them.

solid answer

~40 s

Cloudflare recommends treating the Wrangler file as the source of truth, and a deploy enforces it. Unless `--keep-vars` is passed or the top-level `keep_vars` key is `true`, Wrangler deletes all vars and sets only those in the file, so a dashboard-added var disappears. If the file has `route` or `routes`, the deploy replaces the Worker's routes with that list; to manage routes only in the dashboard, remove those keys and set `"workers_dev": false`, or `workers.dev` comes back on. An absent `crons` key leaves schedules untouched, while `"crons": []` clears them. Secrets are always preserved: a deploy never removes one, and only `wrangler secret delete` does.

code

toml · 8 lines
toml
name = "orders-api"
main = "src/index.js"
compatibility_date = "2026-10-01"
keep_vars = true
workers_dev = false

[vars]
STAGE = "production"

go deeper

for a junior

Recall that the Wrangler file is the source of truth and that a deploy can undo dashboard changes.

for a middle

Explain each case: vars deleted unless keep_vars, routes replaced when the file has them, crons left alone when absent, secrets always kept.

for a senior

Show how you would reconcile an incident-time dashboard edit with the file before the next CI deploy silently reverts it.

for a principal

Decide which settings the team lets live outside the file, if any, and make that explicit with keep_vars or dashboard-only routes.

## The file wins, mostly Cloudflare recommends treating the **Wrangler configuration file** as the source of truth for a Worker and avoiding dashboard changes to a Worker that is deployed with Wrangler. The reason is what `wrangler deploy` does with settings it finds in the file: it sends them as the new state, and for several kinds of setting that replaces whatever the dashboard holds. Knowing which settings are replaced and which survive tells you what a dashboard hotfix is worth after the next CI run. ## Vars **Environment variables** (`vars`, plain text or JSON values) are replaced. The deploy flag's own description says it plainly: unless `--keep-vars` is used, Wrangler deletes all vars before setting those found in the Wrangler configuration. A var someone added in the dashboard is therefore gone after the next deploy if the file does not list it. Two switches keep dashboard vars: - `keep_vars: true` in the file, a **top-level-only** key that applies to every environment and is ignored inside an env block; - `--keep-vars` on a single `wrangler deploy`. ## Routes and `workers.dev` - **Routes:** when the file has `route` or `routes`, a deploy replaces the Worker's routes with the file's list, so a route added in the dashboard disappears. - **Routes managed only in the dashboard:** remove every `route` and `routes` key from the file and add `"workers_dev": false`. - **The `workers.dev` hostname:** when the file has no routes, turning it off in the dashboard is undone by the next deploy unless the file says `"workers_dev": false`, because the key then defaults to `true`. ## Cron Triggers `triggers.crons` behaves differently from vars. When the key is present, the deploy sends exactly that list, and `"crons": []` clears every schedule. When the key is **absent**, Wrangler sends no schedule update at all, so schedules added in the dashboard, or left over from an earlier deploy, keep running. Commenting out the line therefore does not disable a Cron Trigger. ## Secrets **Secrets** are the exception that keeps a deploy safe. `wrangler deploy` always preserves secret bindings: a secret set with `wrangler secret put` or in the dashboard survives every deploy, whether the file mentions it or not, until someone runs `wrangler secret delete`. Declaring the names in the file's `secrets.required` list adds validation and type generation; it is not how the values are stored. The difference between vars and secrets themselves is covered in the lesson on bindings, vars and secrets. ## Summary | Changed in the dashboard | Missing from the file | Next `wrangler deploy` | |---|---|---| | A var | not listed in `vars` | deleted, unless `keep_vars` or `--keep-vars` | | A route | file has other routes | replaced by the file's routes | | A route | file has no `route` / `routes` | left in place | | `workers.dev` turned off | no routes and no `workers_dev: false` | turned back on | | A Cron Trigger | no `crons` key | left in place | | A secret | anything | always kept | ## Working with dashboard edits 1. Prefer the file: change it, review it and deploy it, so the next deploy cannot undo the fix. 2. If someone must edit in the dashboard during an incident, copy the change into the file before the next deploy. When you edit a Worker there, the dashboard offers a configuration snippet to paste into the file. 3. If the team deliberately keeps some values out of the file, choose the switch on purpose: `keep_vars` for vars, no `routes` key plus `workers_dev: false` for routes. 4. Put credentials in secrets, never in `vars`, which also means a deploy can never delete them by accident. ## A typical incident During an outage an engineer adds a `FEATURE_SEARCH` var in the dashboard to switch off a failing code path, and adds a temporary route to send a broken path to a maintenance Worker. The next afternoon a routine CI deploy from the file runs. The var is deleted, because the file does not list it and `keep_vars` is not set, so the failing path switches back on. The temporary route is gone too, because the file lists its own routes and the deploy replaces the Worker's routes with them. A database password stored as a secret is untouched. The lesson is to land the incident change in the file, or deliberately decide that it stays a dashboard setting, before the next deploy.

  • Can keep_vars be turned on for only one environment?
    Not in the file. `keep_vars` is a top-level-only key, read from the top of the file and applied to every environment; inside an environment block Wrangler reports it as an unexpected field and ignores it. A team that wants dashboard vars kept for one environment only can pass `--keep-vars` on that environment's `wrangler deploy` command instead.
  • Does wrangler deploy ever delete a secret the file does not mention?
    No. Wrangler always sends its upload with secret bindings preserved, so a secret set with `wrangler secret put` or in the dashboard survives every deploy. Removing one takes `wrangler secret delete`. Listing names under `secrets.required` in the file adds a check that those secrets are set, and feeds type generation; it does not create, change or remove them.

  • Dashboard vars are merged with the file's vars on every deploy
  • A deploy deletes any secret that the Wrangler file does not list
  • Removing the crons line from the file disables the Cron Trigger
  • Turning off workers.dev in the dashboard sticks even when the file has no routes
  • keep_vars also protects routes that were added in the dashboard