Configuration

All GioJS configuration lives in gio.toml at the project root. Every field is optional — defaults are production-ready.

Full reference

toml

[app]
name = "my-app"
router = "app"          # "app" | "pages"

[server]
host = "0.0.0.0"        # bind address
port = 3000

[server.tls]
enabled = false         # set true to terminate TLS in GioJS directly
cert = "/path/to/cert.pem"
key  = "/path/to/key.pem"

[cache]
memory_mb = 128         # in-process LRU size

[cache.redis]
enabled = false
url     = "redis://localhost:6379"
prefix  = "gio:prod:"

[compression]
enabled = true          # brotli + gzip negotiation

[metrics]
enabled = false         # expose /_gio/metrics (Prometheus); off by default
token = ""              # require "Authorization: Bearer <token>" when set
ip_allowlist = []       # restrict by client IP, e.g. ["10.0.0.5"]

[[images.remotePatterns]]
hostname = "images.example.com"
protocol = "https"

[[redirects]]
source      = "/old-path"
destination = "/new-path"
permanent   = true

[[rewrites]]
source      = "/api/:path*"
destination = "http://internal-api/:path*"

Health & metrics

GioJS serves two built-in observability endpoints directly from the Rust layer — no Node round-trip, so they stay responsive even under load:

Endpoint	Default	Description
`/_gio/health`	always on	Liveness probe — returns `200` once the server and the Node SSR worker are ready. Point your load balancer or container healthcheck here.
`/_gio/metrics`	off	Prometheus exposition (request counts, latency histograms, cache hit ratio, IPC timing). Returns `404` until enabled via `[metrics]`.

Metrics are opt-in so you never expose them by accident. Turn them on, and lock them down for anything beyond localhost:

toml

[metrics]
enabled = true          # serve /_gio/metrics

# Secure it for production — use either or both:
token        = "a-long-random-secret"     # require Authorization: Bearer <token>
ip_allowlist = ["10.0.0.5", "10.0.0.6"]   # only allow these client IPs

bash

# Scrape with a token:
curl -H "Authorization: Bearer a-long-random-secret" \
  http://localhost:3000/_gio/metrics

With enabled = true but no token orip_allowlist, GioJS logs a warning at startup — unauthenticated metrics are fine on localhost but should never face the public internet.

Environment variables

Environment variables override gio.toml at runtime:

Variable	Description	Default
`PORT`	HTTP listen port	3000
`NODE_ENV`	Runtime mode	development
`GIO_CACHE_REDIS_URL`	Redis connection URL	unset
`GIO_SOCKET_PATH`	IPC socket path (Linux/macOS)	/tmp/giojs.sock
`RUST_LOG`	Rust log level (info/debug/trace)	info

Static page caching

Export revalidate from any page module to control caching:

typescript

// Cache forever (ISR: never revalidate)
export const revalidate = false;

// Cache for 60 seconds, then revalidate
export const revalidate = 60;

// Never cache (default when not set)
// (omit the export)

revalidate = false maps to a one-year TTL (31536000 seconds) in the Rust cache layer — the standard sentinel for "cache indefinitely."