> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackra.figentra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 0146 — Package configuration: TypeScript files, layered overrides and secret references

> Accepted · 2026-10-20

> [!NOTE]
>
> Supersedes [0044](/adr/0044-laravel-style-package-config): the Laravel-style configuration is
> replaced by typed configuration files, with the layers below.

## Context

[0044](/adr/0044-laravel-style-package-config) 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](/adr/0144-metadata-registry-and-explorers)).
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](/adr/0044-laravel-style-package-config)): superseded for typed config.
* YAML for package config: kept only for tooling and on-prem operators.

## Supersedes and sources

Supersedes: [0044](/adr/0044-laravel-style-package-config). 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.