$env

Access environment variables with type safety.

Basic Usage

val apiUrl = $env.API_URL
val debug = $env.DEBUG

<Text>{$env.APP_NAME}</Text>

Environment Files

Define environment variables in .env files:

.env

API_URL=https://api.example.com
APP_NAME="My App"
DEBUG=false
MAX_RETRIES=3
TIMEOUT=1.5

.env.local

For local secrets (git-ignored by default):

API_KEY=secret-key-here
DATABASE_URL=postgres://localhost/mydb

.env.debug

Debug-specific overrides:

API_URL=https://staging.example.com
DEBUG=true

.env.release

Production-specific values:

API_URL=https://production.example.com
DEBUG=false

Load Order

Environment files are loaded in this order (later files override earlier ones):

1. .env - Base configuration
2. .env.local - Local secrets
3. .env.debug - Debug build overrides
4. .env.debug.local - Local debug overrides

For release builds, .env.release and .env.release.local are used instead of debug files.

Type Inference

Values are automatically typed based on their format:

Format	Type	Example
Quoted string	String	NAME="Alice"
Unquoted text	String	URL=https://example.com
true or false	Boolean	DEBUG=true
Integer	Int	MAX_RETRIES=3
Decimal	Double	TIMEOUT=1.5

Common Patterns

API Configuration

// .env
API_URL=https://api.example.com
API_TIMEOUT=30

// In code
val apiUrl = $env.API_URL
val timeout = $env.API_TIMEOUT

val response = $fetch.get(
  url = "$apiUrl/users",
  // Configure timeout using environment value
)

Feature Flags

// .env
FEATURE_DARK_MODE=true
FEATURE_ANALYTICS=false

// In code
@if ($env.FEATURE_DARK_MODE) {
  <Switch bind:checked={darkMode} label="Dark Mode" />
}

Build Configuration

// .env.debug
LOG_LEVEL=verbose
MOCK_API=true

// .env.release
LOG_LEVEL=error
MOCK_API=false

// In code
@if ($env.MOCK_API) {
  // Use mock data
} else {
  val data = $fetch($env.API_URL)
}

Configuration in whitehall.toml

Customize which env files are loaded:

[env]
debug = ".env.debug"
release = ".env.release"

See Also

• $import - Compile-time JSON imports
• Project Structure - File organization