Author stable config, keep secrets and generated output in their own lanes
Write for humans first, let Devflare merge environments and resolve names later, and treat generated Wrangler-facing files as outputs rather than authoring surfaces.
The easiest way to keep Devflare predictable is to keep stable intent in authored config and let build or deploy flows resolve the noisy details. That applies to environment overlays, stable resource names, secrets, and generated output.
- Best for
- Anyone authoring or reviewing
- Source of truth
- Authored config plus source files
- Escape hatch
A simple config flow
- 1
Author stable intent in .
- 2
Optionally merge a named Devflare environment with .
- 3
Resolve account ids or resource ids only in flows that truly need them.
- 4
Emit Wrangler-compatible output as generated artifacts.
- 5
Build or deploy from generated output without hand-editing it.
If a generated file feels hand-maintained, move the intent back up
That usually means the authored config is missing a real source-of-truth value or needs a passthrough key.
Keep vars, secrets, and separate
Devflare prefers a workspace-root when it finds a workspace ancestor; otherwise it falls back to the nearest ancestor before evaluating config. That is useful for config-time values, but it does not make the source of truth for worker-only dev or tests.
Stable infrastructure names belong in authored config. Do not hide them in secrets just because another tool happens to like environment variables.
| Layer | Use it for |
|---|---|
| String config that compiles into generated Wrangler output. | |
| Declaring which runtime secret bindings should exist. The schema accepts , but generated env typing still treats declared secrets as present either way today. | |
| Inputs used while evaluating at config time. | |
| Documenting config-time variables for the team. |
Generated artifacts are outputs, not contracts
is a shallow top-level override. Use it when Devflare does not model a Wrangler key yet, not as a place to mirror the whole generated config by habit.
Devflare only generates when it needs to wrap or compose the worker surfaces it discovered. If is set, or the fetch worker already lives at , Devflare can skip that generated main entry and use the explicit worker instead.
- and when Devflare needs wrapper glue around the worker surfaces it discovered
Passthrough is an explicit escape hatch
It wins on top-level key conflicts, so use it deliberately instead of turning it into a second config language.
Use passthrough for unsupported Wrangler keys
Previous
Routing
Use for request-wide behavior, for leaf handlers, and when you need a custom root, prefix, or route-only app.
Next
Full config
See one canonical that touches the main current config lanes in a single file, with hover coverage on every property shown in the example.