Variable Expansion
Compute values from other values with a tiny template language.
Enable ${...} expansion by setting expand: true on defineConfig. You can optionally allow assignments to write back to process.env or a file cache.
Enable Expansion
export const config = defineConfig({
sources: [source().env()],
schema: { /* ... */ },
expand: true,
// expandAssign: 'env' | 'cache' | false
expandAssign: 'cache',
});Patterns
${VAR}— substitute value${VAR:-fallback}— use fallback when unset/empty${VAR:?message}— throw when missing${VAR:+alt}— use alt when set/non‑empty${VAR:=value}— assign when missingjson(...)helper inside patterns —${VAR:=json({"a":1})}; body is recursively expanded, then parsed as JSON
PORT=${PORT:-3000}
DATABASE_URL=${DATABASE_URL:?Set DATABASE_URL}
FEATURES=${FEATURES:=json({"flags":{"newCheckout":false}})}
AUTH_URL=${AUTH_URL:-${BASE_URL}/auth}Whole‑value vs inline
When the entire string is a single ${...} expression, Confkit returns the computed value as a native type (e.g., an object for json(...)). Otherwise, the result is a string with substitutions applied.
Assignment Modes
expandAssign: 'env'—${VAR:=...}writes toprocess.envexpandAssign: 'cache'— also persists to.confkit/cache.json(best‑effort)expandAssign: false(default) — compute‑only, no writes
Useful in short‑lived processes where you want defaults materialized in process.env.
Useful for local dev to persist computed values across reloads.
Safer for CI and production; no side‑effects.