0021. Environment values reach a page as a global set by the build
- Status: Proposed
- Date: 2026-11-14
- Decided by: integrator (internal only)
- Planning item: none
Context
An app needs settings that differ per build: the API address for development and for production, feature switches. The page must not read the build machine's environment at run time, and secrets must never reach the browser.
Decision
A page declares the settings it uses, each with a default: environment({ apiUrl: "http://localhost:4480" }). At run time the values come from globalThis.__duolith_environment, a plain object; a provided value is converted to the type of its default, and the default is used when a value is missing or cannot be converted.
The CLI part is proposed for the Tooling context and is not built in WP8:
duolith buildandduolith devreadduolith.env(andduolith.<mode>.env, for exampleduolith.production.env) in the project root, plus process environment variables namedDUOLITH_PUBLIC_*.- Only names in those files, or with that prefix, are exposed; the prefix is removed and the rest turned to camel case (
DUOLITH_PUBLIC_API_URLbecomesapiUrl). - The emitter writes
<script>globalThis.__duolith_environment = {...}</script>before the page's module script, with the same JSON escaping the template already uses. On native targets the shell sets the same global before the screen runs.
Alternatives considered
| Option | Why not |
|---|---|
Replace import.meta.env.X at build time | Needs a rewrite in the emitter for every read, and hides which settings a page uses |
| Read values from the URL or a fetched config file | Changes at run time, can be tampered with, and costs a request before the first screen |
Consequences
Pages can use environment() today and get their defaults. Once the CLI writes the global, the same pages get per-build values with no change. Anything exposed this way is public: the docs say so, and only DUOLITH_PUBLIC_* names are exposed automatically.