Skip to main content

Concern

Application configuration and environment-specific settings for the frontend (build-time and dev).

Technology

Vite environment variables (import.meta.env), env loading from root .env with prefix mapping

Documentation​

Integration

vite / build​

Only variables prefixed with VITE_ are exposed to client code via import.meta.env; they are inlined at build time. Root .env uses FRONTEND_DESKTOP_ for the desktop app; a Vite plugin maps them to VITE_* so app code uses a single set of names.

http-client​

API base URL and other client config come from import.meta.env.VITE_* (e.g. VITE_BACKEND_URL). See http-client for usage.

Configuration

  • Root .env: At monorepo root, desktop-related vars use the FRONTEND_DESKTOP_ prefix for any vars other than the API URL. VITE_BACKEND_URL is not set in root; the desktop Vite config derives it as http://localhost:BACKEND_PORT only when VITE_BACKEND_URL is not already set (dev default; deployed sets it at build time). FRONTEND_DESKTOP_PORT maps to VITE_PORT (dev server port; default 5173) via the generic FRONTEND_DESKTOP_* → VITE_* mapping. The desktop app’s Vite config sets envDir to the monorepo root, loads root .env, maps FRONTEND_DESKTOP_* → VITE_*, and sets VITE_BACKEND_URL to http://localhost:${BACKEND_PORT || '3000'} only when unset. App code only uses import.meta.env.VITE_BACKEND_URL etc.
  • Optional overrides: A .env in frontends/desktop/ with VITE_* if needed (e.g. for worktrees).
  • Deployment: The platform sets VITE_* at build time (e.g. VITE_BACKEND_URL, VITE_ENVIRONMENT); root .env is for local dev.

Environment variables​

  • VITE_BACKEND_URL — API base URL for the frontend. Build-time (inlined). Dev: derived from BACKEND_PORT only when unset (http://localhost:BACKEND_PORT); deployed: set at build (e.g. /api for same-origin)—never overridden when already set. See http-client.
  • VITE_PORT — Dev server port (Vite server.port). FRONTEND_DESKTOP_PORT in root .env maps automatically to VITE_PORT via the FRONTEND_DESKTOP_* → VITE_* mapping; default 5173.
  • VITE_ENVIRONMENT — Optional; values development, acceptance, production; build-time. Used by getEnvironment() in frontends/shared; when unset and not dev server, treated as development. See pattern environments.

App code reads only import.meta.env.VITE_*. Declare these in frontends/shared/src/env.d.ts so TypeScript and consumers (e.g. lib/api.ts, lib/environment.ts) are typed.

Implementation

The desktop app’s vite.config.ts sets envDir to the monorepo root and, at config load time, loads the root .env with dotenv, maps each FRONTEND_DESKTOP_* key to VITE_* (so FRONTEND_DESKTOP_PORT → VITE_PORT for the dev server), and sets VITE_BACKEND_URL to http://localhost:${BACKEND_PORT || '3000'} only when VITE_BACKEND_URL is undefined (dev default; deployed sets it at build time). server.port is set from VITE_PORT (default 5173). frontends/shared/src/env.d.ts declares VITE_BACKEND_URL, VITE_ENVIRONMENT, and other VITE_* vars. Root .env.example documents FRONTEND_DESKTOP_* vars; backend and frontend stack configuration and pattern configuration describe the overall convention.

References

  • Pattern: configuration (root .env, prefixes, strip/map), environments (VITE_ENVIRONMENT).
  • Stack: vite, http-client, hosting.