Use overlays to change only what differs between local, preview, and production
Keep one base config, layer environment-specific overrides with , and let Devflare resolve preview or production details only in the commands that actually need them.
Devflare environments are an overlay system, not a second copy of the whole config file. The base config should hold the stable project story, and should only override the parts that genuinely differ by environment.
- Best for
- Projects that need different bindings or runtime behavior in preview and production
- Merge model
- Base config first, then , then preview materialization when relevant
- Main habit
- Repeat only the keys that actually differ by environment
Keep one base config and let the overlay change only the deltas
The main config should describe the stable project: the worker name, the usual file surfaces, and the bindings or defaults that exist regardless of environment. is where you change only the parts that diverge for preview, production, or another named lane.
That is why the overlay model feels calmer than copying whole config files around. The shared story stays in one place, while the environment-specific differences stay small enough to review honestly.
A smaller overlay is usually a better overlay
If an environment block starts to repeat most of the base config, that is usually a sign the base config should be refactored instead of duplicated.
Use `config.env` for targeted overrides instead of a second full config
Know what environment overlays are actually allowed to change
This is why is more than a raw Wrangler mirror. It can change the Devflare-owned parts of the project too, as long as those differences are still part of the same package story.
| Override lane | Typical reason to change it |
|---|---|
| , compatibility settings | The environment truly needs a different runtime identity or compatibility posture. |
| , , | Preview or production uses different surfaces, resources, or schedules. |
| , | Runtime strings or secret-binding declarations differ by environment. |
| , , , | Deployment routing, static assets, CPU limits, or observability should differ by lane. |
| , , | The build host or the passthrough escape hatch needs environment-specific behavior. |
Choose the environment where it matters, and let explicit deploy targets do the rest
- 1
Use commands like or when you want to inspect or compile one named environment intentionally.
- 2
Let explicit preview deploys target the preview environment instead of also layering on an unrelated decision.
- 3
Let explicit production deploys stay pinned to production so the deployment target is never ambiguous.
- 4
Keep preview-only resource naming and preview lifecycle behavior inside the preview lane instead of leaking it into the base config.
Environment choice and deploy target are related, but not identical
chooses a config overlay for commands that resolve config environments. Explicit preview and production deploy flags choose the deployment destination itself.
Keep , , and in separate jobs
- Use for inputs that exist while is being evaluated. Devflare prefers a workspace-root when it finds a workspace ancestor, otherwise it falls back to the nearest ancestor .
- Use for string values that should compile into generated Worker-facing output.
- Use to declare runtime secret binding names, not to store those secret values in config. Today that is mostly schema and type metadata: the schema accepts , but generated env typing still treats declared secrets as present and Devflare does not currently turn that flag into a separate deploy-time guarantee.
- Use to document config-time inputs for the team instead of leaving those values to memory or chat scrollback.
Do not let every string become an environment variable by reflex
Stable infrastructure names and intentional runtime strings usually belong in authored config. Save secrets for the values that are actually secret.
Previous
Generated types
turns config, discovered Durable Objects, named entrypoints, and cross-worker references into one generated TypeScript contract instead of a pile of hand-maintained env guesswork.
Next
Previews
Use for bindings that should belong to one preview scope. Devflare materializes names like , provisions or reuses the preview-only resources it can manage, and lets you clean them up by the same scope later without touching production resources.