0105. Environment files, and a typed environment()
- Status: Accepted (Mik, 16 Nov 2026)
- Date: 2026-11-15
- Decided by: domain E implementer (internal only)
- Planning item: wave 5, env files
Context
Decision 0021 set the contract (globalThis.__duolith_environment, DUOLITH_PUBLIC_* names, prefix removed, camel case) but no build provided values, so every page used its defaults.
Decision
duolith buildandduolith devreadduolith.env, thenduolith.<mode>.env, then the process environment'sDUOLITH_PUBLIC_*variables; a later one wins. The mode isproductionfor a build anddevelopmentforduolith dev, or--mode <name>.- Each file holds
NAME=valuelines,#comments and blank lines;exportand quotes are allowed. Any other line is E0513. - Only
DUOLITH_PUBLIC_*values reach the app:DUOLITH_PUBLIC_API_URLisapiUrl.trueandfalsebecome booleans and numbers numbers. On the web the page sets them in an inline script before its module script; on native the bundle's first module (src/environment.ts) sets them. In both, values already set (by a host page or a native shell, as decision 0021 lets the shells do) win. environment()with no argument returns those values, typed: the type check adds them to theDuolithEnvironmentinterface for each page that calls it. A name no file defines is E0514; a name an environment file defines without the prefix is E0515.environment({ name: default })keeps working as before.
Alternatives considered
| Option | Why not |
|---|---|
| Expose every name in the files | A secret written to duolith.env by habit would reach every user |
import.meta.env | Needs a rewrite of every read in both emitters, as decision 0021 says |
Consequences
The language server does not read the environment files yet, so an editor shows environment().apiUrl as unknown until the build has run; the build is right. The shells' own DUOLITH_PUBLIC_* passing keeps the same names, and wins.