flare.json reference

Reference for config files, schema autocomplete, environment overrides, and the flareConfig API. For registration and reading patterns, see Configure your app.

Public API (@flare-ts/core)

Symbol	Kind	Role
flareConfig	function	Creates a config token for a top-level flare.json section
HOST_CONFIG	token	Built-in token for the host section (auto-registered)
LOG_CONFIG	token	Built-in token for the log section (auto-registered)
COOKIES_CONFIG	token	Built-in token for the cookies section (auto-registered)
WEBSOCKETS_CONFIG	token	Built-in token for the websockets section (auto-registered)
ConfigToken<T>	type	Token type; carries section type T via phantom _type
HostConfig	type	Resolved shape of host.config.host
LogConfig	type	Resolved shape of host.config.log

COOKIES_CONFIG and WEBSOCKETS_CONFIG are auto-registered in the same constructor as HOST_CONFIG and LOG_CONFIG, but their cookies and websockets sections have no entry in the bundled flare.schema.json, so those two sections get no schema autocomplete.

Descriptor primitives (str, int, bool, date, float, uuid, array, enums, optional, defaultTo) come from @flare-ts/lib/schema. Nested object shapes use schema({ … }) from @flare-ts/lib.

flareConfig(key, descriptor)

function flareConfig(
  key: string,
  descriptor: T,
): ConfigToken<InferConfigShape<T>>; // section shape inferred from descriptor

• key: top-level property name in flare.json (for example "db").
• descriptor: map of field names to schema primitives or nested schema({ … }).
• Return value: { key, descriptor? }. The same object reference must flow through host.cfg(), static config, and this.config() / scope.config().

Descriptor behavior

Call	Runtime token shape	Field validation at host.build()
flareConfig("db", { url: str, … })	{ key, descriptor } with your field map	Required fields must appear in merged config
flareConfig("empty", {})	{ key, descriptor: {} }	Runs field checks over zero keys
Falsy second argument (tests only)	{ key } only, no descriptor	Section key presence only; no per-field schema

There is no public overload that omits the second argument in TypeScript. For key-only validation in tests, use a manual { key } token or pass {} when you want an empty field map (not the same as key-only).

Example flare.json

{
  "$schema": "./node_modules/@flare-ts/core/flare.schema.json",
  "host": { "port": 4000, "env": "development" },
  "log": { "level": "debug", "format": "pretty" },
  "db": { "url": "postgres://localhost/app", "password": "${SECRET}" },
  "mixed": {
    "url": "https://x",
    "retries": 3,
    "opts": { "host": "x", "port": 9 }
  }
}

Schema autocomplete

Point $schema at the bundled file for editor hints on host and log:

{
  "$schema": "./node_modules/@flare-ts/core/flare.schema.json"
}

The schema is also addressable as @flare-ts/core/flare.schema.json.

Custom sections from flareConfig are validated at host.build() against your descriptors. They are not fixed properties in the published schema file. The root schema sets "additionalProperties": true so extra top-level keys do not break the editor.

Both host and log sections in the schema set "additionalProperties": false and list the same fields as HostConfig and LogConfig below.

HOST_CONFIG / HostConfig

Auto-registered in the FlareHost constructor. Resolved fields on host.config.host:

Field	Type	Default
env	string	"development"
port	number	3000
host	string	"localhost"
shutdownTimeout	number	10000 (ms)
maxBodyBytes	number	2097152 (2 MiB)
requestIdHeader	boolean	true
requestTiming	boolean	false
keepAliveTimeout	number	65000 (ms)
headersTimeout	number	60000 (ms)
requestTimeout	number	300000 (ms; 0 disables)

See Host for how Node and Cloudflare runtimes apply listen and timeout settings.

LOG_CONFIG / LogConfig

Auto-registered in the FlareHost constructor. Resolved fields on host.config.log:

Field	Type	Default
level	"trace" | "debug" | "info" | "warn" | "error" | "fatal"	"info" ("debug" when host.env is "development" and log.level is unset)
format	"pretty" | "json"	"json" ("pretty" when host.env is "development" and log.format is unset)
enableContext	boolean	false
unhandledErrors	boolean	true; logs errors that reach the framework’s fallback response (see Logging)
transports	Record<string, { level: LogLevel }>	optional; keys match a transport’s static transportName

LogLevel is exported from @flare-ts/core. See Logging.

Environment overrides (FLARE__*)

Set FLARE__section__field in the process environment (or adapter env on Workers) to override values before schema validation. Nested paths use extra __ segments:

FLARE__host__port=4000
FLARE__log__level=warn
FLARE__db__url="postgres://prod-host/app"
FLARE__mixed__opts__port=10

For registered sections, field names in the env path are matched case-insensitively to descriptor keys, so FLARE__db__URL sets db.url the same as FLARE__db__url.

Overrides for sections you never registered with host.cfg() are merged into the raw pre-parse object but omitted from host.config after parsing. The same applies to extra keys in flare.json with no matching host.cfg() token.

Env values are strings; the section schema parses them into numbers and booleans.

Missing file and empty sections

If the adapter cannot read flare.json (ENOENT), build continues with {} plus env overrides (a log line notes the missing file). Non-ENOENT read errors abort build.

For each token registered with host.cfg(), if the section is still missing after merge, the host inserts {} so descriptor defaultTo(...) and schema defaults can apply during parse.

Resolution order

At host.build(), config compilation applies layers in this order:

1. flare.json from the adapter (or {} when the file is missing).
2. FLARE__* env overrides merged into that raw object.
3. Each registered section still absent from the raw object is set to {}.
4. When merged host.env is "development", unset log.level / log.format become "debug" / "pretty" (only if those fields are still undefined after step 2).
5. Schema validation per registered descriptor (defaultTo(...) fills defaults here). The result becomes host.config.
6. Startup validation (for example undeclared tokens on classes). See Failure modes.

Invalid types or shapes in step 5 throw a plain Error with message Config validation failed: …. HOST_CONFIG and LOG_CONFIG receive framework defaults in step 5 when their sections are absent or partial.

Related

• Configuration overview
• Configure your app
• Schema primitives