Duolith docs

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 build and duolith dev read duolith.env (and duolith.<mode>.env, for example duolith.production.env) in the project root, plus process environment variables named DUOLITH_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_URL becomes apiUrl).
  • 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

OptionWhy not
Replace import.meta.env.X at build timeNeeds a rewrite in the emitter for every read, and hides which settings a page uses
Read values from the URL or a fetched config fileChanges 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.