Bindings, environments, and secrets
Separate resource bindings, plain variables, and secrets while avoiding non-inherited environment configuration.
Edited and verified by Orange Book Editorial Team ·
Keep three kinds of configuration separate
| Type | Examples | Commit it? |
|---|---|---|
| Resource binding | env.DB, env.BUCKET, env.AI | Binding names yes; real resource IDs depend on repository policy |
| Plain variable | Feature flag or public base URL | Yes, but treat it as public |
| Secret | API token or signing key | No; use wrangler secret or Secret Store |
A binding is a runtime-provided resource capability, not a secret copied into a global variable. In TypeScript projects, run wrangler types after changing Wrangler configuration so binding-name mistakes fail during development.
The environment inheritance trap
Wrangler environment bindings, vars, and secrets are non-inheritable. Declare what staging and production each need; never assume a top-level database automatically appears in a child environment.
{
"name": "notes-api",
"compatibility_date": "2026-08-25",
"vars": { "APP_MODE": "development" },
"env": {
"production": {
"vars": { "APP_MODE": "production" }
}
}
}This only illustrates plain variables. D1, R2, and AI bindings needed by production must still be declared explicitly for that environment.
Local secrets
Choose either .dev.vars or .env; do not maintain both. Ignore the chosen file and put placeholders only in .dev.vars.example.
Responding to a leak
Removing a committed token from the current file does not revoke it. Revoke or rotate first, then clean history and audit usage.
Checkpoint
pnpm wrangler types
pnpm wrangler dev --env productionUse the second command only with safe local or preview resources; local validation must not silently connect to production data.
Primary sources
Did this page help you complete your goal?
Beta feedback is generated in this browser and is never uploaded automatically.