Environment Variables

Radiant supports referencing environment variables directly in the DSL using the env() function. This lets you keep secrets and environment-specific configuration out of your schema files.

env() Function

The env() function takes two arguments:

env("VARIABLE_NAME", "default_value")

Argument	Required	Description
Variable name	Yes	The environment variable name (string literal).
Default value	No	Fallback value if the env var is not set. Can be a string, number, or boolean.

Example

config {
  security: {
    auth: {
      strategies: ["jwt"]
      jwt: {
        accessTokenExpiry: env("JWT_EXPIRY", "15m")
        refreshTokenExpiry: env("JWT_REFRESH_EXPIRY", "7d")
      }
      lockout: {
        maxAttempts: env("LOGIN_ATTEMPTS", 5)
        durationMinutes: env("LOCKOUT_DURATION", 15)
      }
    }
  }
}

How It Compiles

When the compiler encounters env("JWT_EXPIRY", "15m"), it produces a special object in the compiled schema:

{
  "accessTokenExpiry": {
    "$env": "JWT_EXPIRY",
    "$default": "15m"
  }
}

At runtime, the framework reads the $env key, looks up process.env.JWT_EXPIRY, and falls back to $default if the variable is not set.

Common Environment Variables

Variable	Purpose	Example
DATABASE_URL	Database connection string	file:./radiant.sqlite, postgres://user:pass@host:5432/db
JWT_SECRET	Secret key for JWT signing	Auto-generated by radiant init
JWT_EXPIRY	JWT access token expiry duration	15m
JWT_REFRESH_EXPIRY	JWT refresh token expiry duration	7d
LOGIN_ATTEMPTS	Max failed login attempts before lockout	5
LOCKOUT_DURATION	Account lockout duration in minutes	15
SMTP_PASS	SMTP password for email transport	your-smtp-password
SURREAL_USER	SurrealDB username	root
SURREAL_PASS	SurrealDB password	root
SURREAL_NS	SurrealDB namespace	test
SURREAL_DB	SurrealDB database name	test

.env File

The radiant init command creates a .env file with sensible defaults:

JWT_SECRET=<auto-generated-hex-string>
DATABASE_URL=file:radiant.sqlite

For other database adapters:

# PostgreSQL
DATABASE_URL=postgres://postgres:***@localhost:5432/radiant_app

# Redis
DATABASE_URL=redis://localhost:6379

# SurrealDB
DATABASE_URL=http://localhost:8000

The radiant db:sync command automatically loads .env if it exists in the project root.

Using env() in Different Contexts

The env() function works anywhere a value is expected — not just in config:

config {
  core: {
    api: {
      prefix: env("API_PREFIX", "/api")
    }
  }
  security: {
    cors: {
      origin: env("CORS_ORIGINS", "http://localhost:3000")
    }
  }
}

However, it is most commonly used in the security block for sensitive values that should differ between environments (development, staging, production).

Validation

The compiler validates that env() receives at least one string argument:

env()           // Error: requires at least one argument
env(123)        // Error: first argument must be a string
env("VAR")      // OK — no default (null if unset)
env("VAR", "x") // OK — default is "x"
env("VAR", 5)   // OK — default is 5
env("VAR", true) // OK — default is true

Related

• Config Block — Where env() is most commonly used
• CLI Reference — db:sync loads .env automatically