Configuration Devflare

Resolve values through typed config vars instead of scattering process env reads

Use descriptors inside , parse or default them in config, and read the resulting typed values at runtime with .

Devflare vars can now be a typed bridge from local files into Worker runtime code. The config owns which variables are required, optional, parsed, or dev-only, while application code reads the resolved shape through the runtime helper.

Config import
Runtime import
File order: Parents first, then closer directories; first, last
Missing build vars: Build fails with a nested missing-variable report

Declare the runtime shape in config

The export from does not read the variable immediately. It creates a descriptor that Devflare resolves when it starts dev, builds artifacts, or prints a phase-resolved config.

That keeps config import cheap and lets Devflare report every missing variable at once, using the nested path from instead of a generic process-env crash.

Nested vars with required, optional, parsed, defaulted, and dev-only values

import { defineConfig, env } from 'devflare/config'

export default defineConfig({

name: 'voices-api',

vars: {

secret: env.SECRET,

mongo: {

uri: env.MONGOURI,

database: env.MONGODATABASE

retries: env.RETRIES.parse(Number),

optionalLabel: env.OPTIONAL_LABEL.optional(),

mode: env.APP_MODE.default('local'),

mockTenantId: env.MOCK_TENANT_ID.dev(123)

}

})

Read resolved values through the runtime helper

At runtime, Devflare exposes the resolved values on the Worker environment and through the helper. The helper is typed from , so parser return values and nested objects stay visible to TypeScript.

Unparsed environment descriptors resolve to strings. Parsed descriptors use the parser return type, defaults contribute their value type, and optional descriptors become optional properties.

Runtime code can use the nested shape directly

import { vars } from 'devflare'

export default {

async fetch() {

return Response.json({

database: vars.mongo.database,

retries: vars.retries

})

}

Let Devflare parse files itself

Devflare reads and from the config directory and every parent directory. Parent files load first, then closer files override them. Within one directory, loads first and wins last.

The parser does not expand references. Values such as passwords, MongoDB connection strings, and shell-looking fragments are read as written instead of being interpreted by Bun.

Process env still wins over files

CI-provided environment variables and explicit shell exports override file values. Dotenv files fill in missing process variables; they do not stomp values the process already had.

The later `.env` value overrides the earlier `.env.dev` value

# .env.dev

SECRET=local-secret

MONGOURI=mongodb://127.0.0.1:27017

MONGODATABASE=voices_dev

RETRIES=1

# .env

MONGODATABASE=voices

Missing required values fail build and pause dev

Required is the default because a config variable usually means the Worker cannot run honestly without that value. Build and config-inspection commands fail with a grouped report that points at the nested path and the missing environment variable name.

Dev mode is gentler. It prints the same report, waits for or to change, and then retries startup. That makes the local loop fixable without restarting the command.

Missing variables are grouped by the config path that required them

These environment variables are missing:

secret: SECRET

mongo:

uri: MONGOURI

Use helpers to make intent explicit

Helper	Meaning	Example
	Required string value.
	Missing value is allowed and omitted.
/	Transform the string from env files into a typed runtime value.
	Use a fallback in every mode when the env value is missing.
	Use a fallback only in dev when the env value is missing.

Dev-only defaults are still required in build

is intentionally local-only. If the same variable may be missing in build too, use or instead.

Environments

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.

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.