Configuration
nexus.Boot and nexus.toml
Most apps start with one call:
func main() {
nexus.Boot(usersModule, ordersModule)
}nexus.Boot(opts...) loads nexus.toml from the working directory, then runs the app. It reads:
- the
[runtime]tables, which become the runtimeconfig.Runtime - every
[extensions.*]block - the
[env]bridge - the value store behind
config.Get
Before it expands ${VAR}s, the loader applies .env beside nexus.toml, or the files [runtime] dotenv lists (dotenv = ["!.env", ".env.local"]; a leading ! makes a file required). Real environment variables win over the file.
A missing nexus.toml is fine, and defaults apply. A malformed one — or one with a key nothing reads (see Strictness) — fails boot with the file, line and fix. Point at a different file with the NEXUS_CONFIG environment variable, or call nexus.BootFrom(path, opts...).
If you prefer to build the config in Go, use nexus.Run with a config.Runtime from the config package (github.com/paulmanoni/nexus/v2/config):
nexus.Run(config.Runtime{
Server: config.Server{Addr: ":8080"},
Dashboard: config.Dashboard{Enabled: true, Name: "Shop"},
Introspection: true,
}, usersModule)Boot is shorthand for nexus.Run(config.MustLoad(), append([]nexus.Option{nexus.MustLoadExtensions()}, opts...)...).
Runtime keys live under [runtime]
Every runtime key belongs in [runtime] or a [runtime.<sub>] table. A runtime key at the top level fails boot (environment at the top level → [runtime] environment). [databases.*], [extensions.*] and [env.*] are top-level tables of their own.
A typical file
[runtime]
environment = "development" # NEXUS_ENVIRONMENT overrides it
introspection = true # opens /__nexus (off by default)
[runtime.server]
addr = ":8080"
max_body_bytes = 104857600 # default 32MB; -1 turns the cap off
[runtime.dashboard]
enabled = true
name = "Shop"
[databases.main]
driver = "postgres"
host = "localhost"
port = "5432"
user = "postgres"
password = "${DB_PASSWORD}" # ${ENV} is expanded at load
name = "shop"
default = trueEvery key is documented in the nexus.toml reference.
Environment
environment is development, staging or production. Scaffolds ship environment = "development", which turns on dev-only behaviour:
- pages follow a running Vite dev server
- the typed client SDK is written into
web/sdk
Deployments set NEXUS_ENVIRONMENT=production, which overrides the file, so you never edit nexus.toml to ship. Go code can read the resolved value with nexus.ActiveEnvironment().
Strictness
nexus.toml is strict. Every table in it has an owner that declares it, and every key in a declared table is one its type has. Boot fails — in development and production alike — on:
- a key at the top level, outside any table:
environment = "production"above[runtime]reports did you mean [runtime] environment? - an unknown key in a declared table:
[runtime.server] adresslists what[runtime.server]accepts;enabeldsuggestsenabled - an unknown table under a declared one, such as
[runtime.inertia] - an undeclared section: a top-level table nobody declared, such as
[shop]before the app declares it - an
[extensions.x]block whose extension package isn't imported
The error is printed as a diagnostic block with each problem's file:line and fix.
The owners are nexus itself ([runtime], [databases], [env], [extensions], [decorators] and the deploy-manifest tables), the framework extensions ([cache], [storage], [mail] and [jobs], declared when the app imports extension/cache, extension/storage, extension/mail or extension/jobs), extension decoders for [extensions.<name>], and the app.
Your own sections: config.Section
An app declares its own tables with config.Section[T](name, default...), usually as a package-level variable:
[shop]
currency = "EUR"
page_size = 50
timeout = "30s"
[shop.payments]
provider = "card"import "github.com/paulmanoni/nexus/v2/config"
type ShopConfig struct {
Currency string `toml:"currency"`
PageSize int `toml:"page_size"`
Timeout time.Duration `toml:"timeout"` // a Go duration string
Payments struct {
Provider string `toml:"provider"`
} `toml:"payments"`
}
var Shop = config.Section[ShopConfig]("shop", ShopConfig{Currency: "USD", PageSize: 20})
func pageSize() int { return Shop.Get().PageSize }- The declaration is what makes
[shop]legal in the file, and the table is checked againstShopConfig: a key it has no field for fails boot like any other. Get()returns the table decoded over the default (a key missing from the file keeps its default).Present()reports whether the file has the table at all.- Keys come from
tomltags (else the lowercased field name).time.Durationfields read Go duration strings. Tmay be a map:config.Section[map[string]Store]("stores")declares[stores.<name>]tables.config.Section[map[string]any]("flags")declares a free-form table whose keys aren't checked.- A name may be declared once. Declaring a framework table (
jobs,cache, …) or a name declared elsewhere panics at init.
Reading values: config.Get
Any value in nexus.toml is also readable by its dotted path, with an environment override:
currency := config.Get[string]("shop.currency")
size := config.Get[int]("shop.page_size", 20) // second arg is the default
ttl := config.Get[time.Duration]("shop.timeout", 5*time.Minute)config.Get reads declared tables like any other; declaring a section is what lets it be in the file, and Get keeps working on it. (A key that comes only from an environment variable or the config server needs no declaration.)
Values resolve per key, highest priority first:
- An environment variable.
shop.page_sizeis overridden bySHOP_PAGE_SIZE. (A section handle'sGet()returns the file's values as decoded at boot.) - The config server snapshot, when
[extensions.config]is wired. Its values are hot-reloadable and can come from a remote server. nexus.toml.
Plain file reads need no extension. Wire extension/config only when you need hot reload, profiles or a remote config server.
The [env] bridge
Tables under [env] become process environment variables. The same values can also be used by the frontend:
[env.client]
id = "shop-web"
url = "${PUBLIC_URL}"- Go:
os.Getenv("client.id"). Nested tables flatten with dots. - Frontend:
import.meta.env.client.id. Whennexus devornexus buildstarts Vite, each exact reference like this is replaced with its value. Only keys you reference reach the browser. The values are never added to theimport.meta.envobject, so the bracket form (import.meta.env["client.id"]) and whole-object access see none of them.
Only public values
A value the frontend references ships in the JavaScript bundle. Reference client-public data only (an OAuth client id, a public URL). Never reference a server secret.
Checking a file
nexus config check # ./nexus.toml, or $NEXUS_CONFIG
nexus config check deploy/nexus.toml --jsonnexus config check applies the boot rules — undeclared tables, unknown and misplaced keys, value types, and bad addresses, CIDRs, durations or listener scopes — and exits 1 on an error, so it gates CI. It reads the app's own declarations from the Go module the file sits in: config.Section[T]("name") calls (with T's keys) and RegisterExtensionDecoder("name", …) calls. ${VAR} placeholders need not be set. nexus lint reports the same problems as errors.
Editor completion
nexus publishes a JSON schema for nexus.toml. Put this on the file's first line, and Taplo-based editors (VS Code's Even Better TOML, Zed, Helix) complete and check keys:
#:schema https://paulmanoni.github.io/nexus/nexus.toml.schema.jsonThe published schema covers the tables nexus declares. nexus config schema -o nexus.schema.json writes one that also includes your app's sections; point #:schema at that file instead.
From v1
v1 ignored keys nothing read. nexus migrate v2 moves the ones it recognises as real settings in the wrong table — a top-level environment, an addr under [runtime] — into the table they belong to. Run nexus config check afterwards for the rest: typos, and app sections to declare with config.Section.