Duolith docs

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 build and duolith dev read duolith.env, then duolith.<mode>.env, then the process environment's DUOLITH_PUBLIC_* variables; a later one wins. The mode is production for a build and development for duolith dev, or --mode <name>.
  • Each file holds NAME=value lines, # comments and blank lines; export and quotes are allowed. Any other line is E0513.
  • Only DUOLITH_PUBLIC_* values reach the app: DUOLITH_PUBLIC_API_URL is apiUrl. true and false become 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 the DuolithEnvironment interface 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

OptionWhy not
Expose every name in the filesA secret written to duolith.env by habit would reach every user
import.meta.envNeeds 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.