gio.toml

The project-root file the Rust server reads at startup for every server setting: listen address, caching, security, images, fonts, limits and rules.

#:schema ./node_modules/@gio.js/server/gio.schema.json
[app]
name = "acme"

[server]
port = 3000   # GIO_PORT or PORT overrides it

[images]
allowed_widths = [640, 828, 1080, 1200, 1920]
quality = 80

Reference

File name and location

gio.toml in the project root, next to app/. The server looks for it in the parent of GIO_APP_DIR when that variable is set and the file exists there, else in the directory it was started in. The file is optional: without it every setting has its default.

Contents

TOML tables, one per section: [app], [server], [security], [cache], [images], [[fonts]], [[rate_limits]], [[redirects]] and the rest. Every key, its type, default and what turning it off costs is on gio.toml, with one page per section.

Behavior

• Read once, at startup, by the Rust server. A change takes effect when the server starts again, in development too: the dev watcher notices the edit but restarts only the Node worker, which does not read gio.toml. Stop gio dev and start it again after editing the file.
• Strict. An unknown section or key anywhere stops startup, with the line and the closest valid name:

gio.toml:4: unknown key [image] - did you mean [images]?

• Room for other tools. Top-level tables whose name starts with x- ([x-mytool]) are left alone.
• Environment variables win for the keys that have one (GIO_PORT, PORT, GIO_HOST, GIO_CACHE_DIR, ...). .env files are loaded before gio.toml is read, so they can set those variables too.
• Editor support. The #:schema first line points editors with a TOML language server (Even Better TOML / Taplo) at the schema @gio.js/server ships, for completion and hover docs.

Examples

Check the file without starting the server

npx giojs-server --check-config

pnpm exec giojs-server --check-config

yarn giojs-server --check-config

bunx giojs-server --check-config

It loads the .env files and gio.toml exactly as startup does, runs the same validation, and prints a JSON report (errors, warnings for protections you turned off, the listen address). It exits 1 when the server would refuse to start and never binds a port, so it works as a CI step:

{"configFile":"gio.toml","envFiles":[],"envFilesDisabledBy":null,"errors":["gio.toml:4: unknown key [image] - did you mean [images]?"],"mode":"production","ok":false}

Good to know

• Strictness is fixed: a misspelled security key that was silently ignored would leave a protection off. Use [x-...] tables for anything else you want in the file.
• Every protection is on by default. Turning one off or loosening it logs one startup warning naming the key, and --check-config reports the same text (see Turning Protections On and Off).
• gio build standalone copies gio.toml into the deploy folder, where the server reads it at every start.
• Node-side settings (plugins) are in gio.config.ts; computed rules can also go in middleware.ts.

Related

• gio.toml reference - every section and key.
• Strict by design and editor autocomplete
• Environment variables, .env files

Version history