Skip to main content
Supersedes 0044: the Laravel-style configuration is replaced by typed configuration files, with the layers below.

​
Context

0044 chose Laravel-style package configuration. The owner’s configuration answers CF1 to CF4 (mem L846–850, 2026-10-20) and the framework answer FW3 a (mem L354) replace it. Secrets are referenced by name, and gen turns those references into Encore secret() declarations.

​
Decision

  1. Format (CF1). Package and host configuration is TypeScript, in config/<pkg>.config.ts, using defineConfig<Schema>, with secret('Name') references and Zod validation at boot. YAML serves tooling and operations. An optional YAML loader serves on-prem operators.
  2. Commands (CF2). stackra config:publish <pkg> and stackra config:diff are contributed by @stackra/config and found by the CLI through discovery (0144).
  3. Layers (CF3). Package defaults, then the host file, then the env file, then the env vars STACKRA_<PKG>__<PATH>, then runway.yaml overrides. Plain objects deep-merge. Arrays, secrets and instances replace. The result is validated, frozen, and config:show masks secrets.
  4. Scope (CF4). Config is deploy-time. It is read by developers and operators, applied by a restart, and is never per tenant. Settings are runtime and per scope chain. A lint flags tenant-dependent config.
  5. Secrets (FW3 a). Gen turns config secret references into Encore secret() declarations in the generated app.

​
Consequences

  • Config errors fail at boot, with the path of the bad value.
  • A secret value never appears in a config file. The file names it.

​
Enforcement

planned — boot validation of each config/<pkg>.config.ts with Zod, the masked config:show output, and the lint for tenant-dependent config. Gen’s secret() output is checked by stackra gen --check.

​
Alternatives

  • Laravel-style arrays (0044): superseded for typed config.
  • YAML for package config: kept only for tooling and on-prem operators.

​
Supersedes and sources

Supersedes: 0044. Sources: owner configuration answers CF1 to CF4 (stackra-decisions-2026-10-19.md L846–850, 2026-10-20), framework answer FW3 a (L354), gap C42.