Examples
EN

Environment Variables

Hwaro supports environment variable substitution in both config.toml and templates, enabling dynamic configuration for CI/CD pipelines, secret management, and per-developer settings.

Config Substitution

Environment variables in config.toml are resolved before TOML parsing.

A value placed inside a double-quoted string is inserted as exactly the characters the variable holds: quotes, backslashes and newlines are escaped for you, so SITE_TITLE='Say "hi"' or a Windows path loads verbatim. A placeholder outside any string (paginate = ${PER_PAGE}) is inserted as TOML, so numbers and booleans work, and a ${VAR:-default} default is used exactly as written in the file. Placeholders inside # comments are left alone.

Syntax

Pattern Description
${VAR} Replace with the value of VAR
$VAR Same (bare form)
${VAR:-default} Use default if VAR is unset or empty

Examples

# Dynamic base URL for CI/CD
base_url = "${SITE_URL:-http://localhost:3000}"

# Bare form
title = "$SITE_TITLE"

# Default values
description = "${SITE_DESC:-My awesome site}"

[og]
fb_app_id = "${FB_APP_ID:-}"

Missing variables without a default value are left unchanged and produce a build-time warning:

[WARN] Environment variable 'SITE_URL' is not set (referenced in config.toml)

Template Function

Use the env() function to read environment variables inside templates.

{{ env("ANALYTICS_ID") }}
{{ env("API_KEY", default="none") }}
Parameter Type Description
name String Variable name
default String? Fallback if unset or empty, matching ${VAR:-default} (optional)

If the variable is not set and no default is provided, an empty string is returned and a warning is logged (once per variable per build).

Examples

Conditional analytics snippet:

{% if env("GA_ID") %}
<script async src="https://www.googletagmanager.com/gtag/js?id={{ env("GA_ID") }}"></script>
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date());
  gtag('config', '{{ env("GA_ID") }}');
</script>
{% endif %}

API endpoint with fallback:

<script>
  const API_URL = "{{ env("API_URL", default="https://api.example.com") }}";
</script>

Use Cases

CI/CD Pipelines

Set the base URL per deployment environment:

SITE_URL=https://staging.example.com hwaro build
SITE_URL=https://example.com hwaro build

Secret Management

Keep API keys and tracking IDs out of version control:

# config.toml
[og]
fb_app_id = "${FB_APP_ID}"

export FB_APP_ID="123456789"
hwaro build

Per-Developer Settings

Each developer can override values locally via their shell environment without modifying config.toml:

export SITE_URL="http://localhost:3000"
hwaro serve

See Also