Skip to main content

HolonClient Production Runtime Env

This guide explains how HolonClient resolves runtime configuration in production builds and what patterns MUST NOT be used. Read this before adding or changing environment variables in the HolonClient renderer.

Source Of Truth​

Frontend/HolonClient/public/runtime-config.js is the single canonical production source for HolonClient runtime configuration. It sets window.__ENV__ before the app bootstraps and carries the real Firebase config, API base URLs, and desktop feature flags.

The runtime fallback chain in src/Infrastructure/auth/firebase.ts is:

  1. window.__ENV__ (from public/runtime-config.js) — preferred first
  2. import.meta.env.* (Vite build-time inlining) — used only when window.__ENV__ is missing

Forbidden: Committed .env.production​

Do not commit a Frontend/HolonClient/.env.production file to the repository.

Vite inlines .env.production values into the production bundle at compile time. These values shadow window.__ENV__ because import.meta.env.* is not empty and firebase.ts checks for emptiness, not validity. A file with placeholder values produces a build that passes packaging readiness but silently fails at runtime.

.gitignore already ignores .env.production, .env, and .env.*.local. These gitignore entries are necessary but are not a complete guardrail — a force-add or a prior commit can still introduce the file.

The Grey-Screen Incident (0.1.x)​

A committed .env.production contained:

VITE_FIREBASE_API_KEY=your-production-api-key
VITE_FIREBASE_AUTH_DOMAIN=your-production-auth-domain
VITE_FIREBASE_PROJECT_ID=sfrshauthentication
VITE_FIREBASE_STORAGE_BUCKET=sfrshauthentication.appspot.com
VITE_FIREBASE_MESSAGING_SENDER_ID=your-production-sender-id
VITE_FIREBASE_APP_ID=your-production-app-id
VITE_ACCOUNT_MANAGER_API_BASE_URL=https://api.saastools.com/accountmanager
VITE_ENABLE_DESKTOP_AUTH_TOPBAR=true

What happened:

  1. Vite inlined these placeholder values into the production bundle.
  2. firebase.ts:64-78 checked that values were non-empty — placeholders are truthy, so the check passed.
  3. Firebase initialized with invalid credentials and failed silently at runtime.
  4. The React tree never resolved past auth initialization.
  5. The Tauri shell loaded but displayed a blank (grey) screen.

The fix: Removed the file in c6bf282b. The real values are and always were in public/runtime-config.js.

Release Guardrail​

Run this check before pushing a release tag:

pwsh -File scripts/check-no-committed-env.ps1

The script exits with a non-zero code when a forbidden .env.production or .env file is tracked or staged under Frontend/HolonClient/. Include it in your local release prep alongside verify-version.ps1 and packaging-readiness.

The release-and-versioning guide includes this step in the recommended pre-release validation list.

Validating runtime-config.js​

Before a production build, confirm that public/runtime-config.js contains real values:

  • VITE_FIREBASE_API_KEY — not a placeholder like your-production-api-key
  • VITE_FIREBASE_AUTH_DOMAIN — a real Firebase domain
  • VITE_FIREBASE_PROJECT_ID — a real project id
  • VITE_ACCOUNT_MANAGER_API_BASE_URL — a reachable API host

The dev-mode demo fallback in firebase.ts:36-61 is intentional and safe — it only activates in import.meta.env.DEV mode. Production builds never enter that branch.