skip to content

During wrangler dev, how does Wrangler load local secrets from .dev.vars and .env files, and which value wins when they overlap?

level: middleimportance: should knowfreq 48%

answer

  1. local-only values, not for deploys
  2. one file family or the other
  3. per-environment file replaces or merges
  4. overrides the config's vars
  5. a declared list filters the keys

basics

~20 s

Wrangler reads .dev.vars beside the Wrangler file, or, only when no .dev.vars file applies, the .env files. Their values override the config's vars locally. A .dev.vars.<env> file replaces .dev.vars, while .env files for an environment merge.

solid answer

~40 s

Local secrets go in a `.dev.vars` file, or `.env` files, beside the Wrangler configuration file, in `KEY="value"` lines; they exist only for local development and have no effect on the deployed Worker. If any `.dev.vars` file applies, the `.env` files are ignored for the Worker's `env`. A key that appears in both `vars` and `.dev.vars` takes the `.dev.vars` value locally. With `wrangler dev --env staging`, `.dev.vars.staging` is read instead of `.dev.vars`, not merged with it, whereas `.env`, `.env.local`, `.env.staging` and `.env.staging.local` are layered, with later files winning. When the config declares `secrets.required`, only those names (plus existing `vars` keys) are loaded and missing ones produce a warning. Both file families belong in `.gitignore`.

code

javascript · 9 lines
javascript
export default {
  async fetch(request, env) {
    return Response.json({
      API_HOST: env.API_HOST,
      MODE: env.MODE,
      hasToken: typeof env.SECRET_TOKEN === "string",
    });
  },
};

go deeper

for a junior

Recall that local secrets go in .dev.vars (or .env) next to the Wrangler file, never affect the deployed Worker, and must be listed in .gitignore.

for a middle

Explain precedence: .dev.vars over vars, .dev.vars excluding .env, a per-environment .dev.vars replacing the base file, and .env files merging.

for a senior

Spot leaks: credentials in vars, CLOUDFLARE_INCLUDE_PROCESS_ENV exposing the shell, and Wrangler's own token in .env reaching env; use secrets.required to fail loudly.

for a principal

Set the team rule: one file family, development-only credentials, a declared secrets.required list, and production values only through wrangler secret put.

## Why local secrets need their own files In a deployed Worker, a **secret** is an encrypted binding set with `wrangler secret put` or the dashboard, and a **var** is a plain-text value written in the Wrangler file's `vars`. Neither works for local development: secrets live on Cloudflare, and putting a real token in `vars` would commit it. So `wrangler dev` (and the Cloudflare Vite plugin) read **local-only files** and inject their keys into `env` as secret-typed bindings: - **`.dev.vars`** in the same directory as the Wrangler configuration file. - **`.env`** files in that directory, used only when no `.dev.vars` file applies. Both use `.env`-style `KEY="value"` lines. They have no effect on a deployed Worker, so a local value does not reach production by being in these files; it leaks by being committed or copied. Add `.dev.vars*` and `.env*` to `.gitignore`. ## Precedence inside one session 1. Wrangler starts from the config's **`vars`**. 2. It loads **`.dev.vars`**; if that file does not apply, it loads the **`.env`** files instead. It never combines the two families: if a `.dev.vars` file is present, values in `.env` files do not reach `env`. 3. Every loaded key is added to `env` and **overrides a `vars` key of the same name**. A config `vars` entry `API_HOST = "from-config"` plus `API_HOST="from-dev-vars"` in `.dev.vars` gives the Worker `from-dev-vars`. ## Worked example Take a Wrangler file with `vars` `API_HOST = "from-config"` and `MODE = "config"`, an `env.staging` block with its own `vars`, a `.dev.vars` holding `API_HOST` and `SECRET_TOKEN`, and a `.dev.vars.staging` holding only `SECRET_TOKEN`: - `wrangler dev` gives `API_HOST` and `SECRET_TOKEN` from `.dev.vars`, and `MODE` from the config. - `wrangler dev --env staging` uses the staging block's `vars` (environments do not inherit `vars`) and reads only `.dev.vars.staging`, so `API_HOST` comes from the staging block and `SECRET_TOKEN` from the staging file. - Deleting `.dev.vars.staging` makes the staging session fall back to `.dev.vars`. ## Per-environment files behave differently by family With `wrangler dev --env staging` (or `CLOUDFLARE_ENV=staging vite dev`): | Files present | What reaches env | |---|---| | `.dev.vars` and `.dev.vars.staging` | Only `.dev.vars.staging`; `.dev.vars` is not read | | `.dev.vars` only | `.dev.vars` | | `.env`, `.env.local`, `.env.staging`, `.env.staging.local` | All of them merged, later files winning: `.env`, then `.env.local`, then `.env.staging`, then `.env.staging.local` | The `.dev.vars` rule surprises teams: a staging file must repeat every secret, because nothing falls back to the generic file. The `.env` family is the opposite: shared values can stay in `.env` and only the differences go in the environment file. ## Declaring which secrets a Worker needs The `secrets` configuration property lists the names a Worker requires: ```json { "secrets": { "required": ["SECRET_TOKEN", "PAYMENTS_KEY"] } } ``` When it is set, local development loads only those names (plus keys that override an existing `vars` entry), drops any other key in the file, and warns: `Missing required secrets: PAYMENTS_KEY. Add them to .dev.vars, .env, or set as environment variables.` With `secrets` defined and no `.dev.vars` file, required names can also come from the shell's process environment. The same list is used for type generation and is checked on deploy. ## Controls and gotchas - `CLOUDFLARE_LOAD_DEV_VARS_FROM_DOT_ENV=false` stops `.env` files feeding `env` when there is no `.dev.vars`. - `CLOUDFLARE_INCLUDE_PROCESS_ENV=true`, with no `.dev.vars`, copies **every** shell environment variable into `env`: convenient, but it exposes unrelated credentials to the Worker. - `.env` files also **configure Wrangler itself** (for example `CLOUDFLARE_ACCOUNT_ID`). Without a `.dev.vars` file and without `secrets.required`, every key in them also becomes a Worker binding during local development, so a `CLOUDFLARE_API_TOKEN` kept there is readable from `env`. Keeping Worker secrets in `.dev.vars`, or declaring `secrets.required`, keeps tool settings and Worker secrets apart. - `--env-file <path>` (repeatable) points Wrangler at specific `.env` files; with it, `.dev.vars` is not consulted. - `vite build` with the Cloudflare Vite plugin writes the selected local vars into a `.dev.vars` file next to the built Worker so that `vite preview` can use them; keep the build directory out of version control and out of shared artifacts. - `wrangler dev --var KEY:value` injects a plain var from the command line and wins over the same key in `vars`. ## What a reviewer checks - No real credential in `vars`, and `.dev.vars*` and `.env*` ignored by version control. - Local values that are **development** credentials (a sandbox key, a test token), not copies of production secrets. - A `secrets.required` list, so a missing local or deployed secret is reported instead of surfacing as `undefined` at runtime.

  • Why can keeping a Cloudflare API token in .env be a problem during local development?
    Wrangler loads `.env` files to configure itself, and when no `.dev.vars` file exists and `secrets.required` is not declared, it also exposes every key in them to the Worker's `env`. A `CLOUDFLARE_API_TOKEN` there becomes readable by local Worker code and anything it logs. Put Worker secrets in `.dev.vars`, or declare `secrets.required`, so only named secrets reach the Worker.
  • How do the local files relate to secrets set with wrangler secret put?
    They are independent. `wrangler secret put` stores an encrypted secret on the deployed Worker; `.dev.vars` and `.env` values exist only in local sessions and have no effect on the deployed Worker. A Worker therefore needs both: the deployed secret for production and a local, ideally development-only, value in the file.

  • Puts real API keys in the Wrangler file's vars so local development works.
  • Expects .dev.vars.staging to inherit missing keys from .dev.vars.
  • Believes wrangler deploy uploads .dev.vars as the Worker's secrets.
  • Assumes values from .env and .dev.vars are merged when both exist.
  • Thinks the Wrangler file's vars beat .dev.vars for the same key locally.

Assumes Wrangler 4.149: .env files as a fallback source of local dev vars arrived in Wrangler 4.27, and the secrets configuration property with secrets.required was stabilised in Wrangler 4.88.