Workers environments: staging and production from one config

Wrangler environments

One Wrangler file, multiple deployments. Environments override top-level config per named environment.

{
  "name": "my-worker",
  "route": "dev.example.com/*",
  "vars": { "ENVIRONMENT": "dev" },
  "env": {
    "staging": {
      "vars": { "ENVIRONMENT": "staging" },
      "route": "staging.example.com/*"
    },
    "production": {
      "vars": { "ENVIRONMENT": "production" },
      "routes": ["example.com/*"]
    }
  }
}

Deploy with wrangler deploy --env staging. The Worker name becomes my-worker-staging (name plus env suffix), and each environment can carry its own routes, KV namespaces, D1 databases, and other bindings.

The traps

• vars are non-inheritable. Top-level vars do not flow into environments; every environment must define its own. The config above repeats ENVIRONMENT in each env for exactly this reason.
• Custom domains and routes need per-env values. If you deploy to a custom domain or route, each environment needs its own route/routes key. A staging deploy without one goes to workers.dev (or fails, depending on the rest of the config).
• workers_dev per environment. To give staging a *.workers.dev subdomain, set workers_dev = true inside that environment's block.
• With the Vite plugin, select the environment with CLOUDFLARE_ENV, not --env; the build flattens to a single config for that environment.

Checklist

• Give each environment its own backing resources (separate KV namespaces, D1 databases); sharing production data with staging is how staging writes end up in prod.
• wrangler dev --env staging for local work against the staging config.
• Name environments staging and production, not dev2 and final; future you will thank present you.

Verified against the live Wrangler Environments doc: --env flag, name mangling (my-worker-staging), vars non-inheritable, per-env route requirement, workers_dev per env. Ref: https://developers.cloudflare.com/workers/wrangler/environments/