Configure your app

Use this guide to wire config from declaration through host.build(). For flare.json shape, schema autocomplete, and FLARE__* overrides, see flare.json reference.

1. Define a config token

Declare tokens at module scope with flareConfig and schema primitives from @flare-ts/lib/schema:

config.ts

import { flareConfig } from "@flare-ts/core";
import { bool, defaultTo, int, schema, str } from "@flare-ts/lib/schema";

export const DbConfig = flareConfig("db", {
  url: str,
  password: str,
});

export const FeatureConfig = flareConfig("feature", {
  enabled: defaultTo(false, bool),
  motd: str,
});

export const MixedConfig = flareConfig("mixed", {
  url: str,
  retries: int,
  opts: schema({ host: str, port: int }),
});

TypeScript infers the section type from the descriptor. DbConfig resolves to { url: string; password: string } wherever you call this.config(DbConfig).

Add matching sections to flare.json (or set FLARE__* env vars). Required descriptor fields must be present after merge unless you used defaultTo or optional.

2. Register tokens on the host

Every token a class lists in static config must be registered before host.build():

import { FlareHost } from "@flare-ts/core";
import { node } from "@flare-ts/core/node";
import { DbConfig, FeatureConfig, MixedConfig } from "./config.js";

const host = new FlareHost(node);
host.cfg(DbConfig, FeatureConfig, MixedConfig);

host.cfg is variadic. Call it once with several tokens or call it again to add more. HOST_CONFIG, LOG_CONFIG, COOKIES_CONFIG, and WEBSOCKETS_CONFIG are registered automatically in the FlareHost constructor.

3. Read config from a service

List tokens on the class and resolve them with this.config():

import { FlareService } from "@flare-ts/core";
import { DbConfig } from "./config.js";

class Db extends FlareService {
  public static override deps = [];
  public static override config = [DbConfig];

  getUrl() {
    return this.config(DbConfig).url;
  }
}

The same static config + this.config() pattern works on ControllerBase, MiddlewareBase, and ErrorHandlerBase.

Runtime guard: if you call this.config(Token) with a token not in static config, Flare throws before resolution.

Build guard: if a class lists a token in static config but you never called host.cfg(Token), host.build() fails with UNREGISTERED_CONFIG_TOKEN. See Failure modes.

4. Read config from an inline route

Inline handlers have no static config array. Use scope.config() instead:

import { FlareHost, FlareResponse } from "@flare-ts/core";
import { node } from "@flare-ts/core/node";
import { DbConfig } from "./config.js";

const host = new FlareHost(node);
host.cfg(DbConfig);

host.http.get("/db", (_ctx, scope) =>
  new FlareResponse(200, { url: scope.config(DbConfig).url }),
);

const app = host.build();
app.run();

scope.config(Token) does not check static config, but the token must still be registered with host.cfg() so the section exists after build.

5. Inspect resolved config on the host

After host.build(), read any registered section from host.config:

const app = host.build();
console.log(host.config.db?.url);
console.log(host.config.host.port);

Before build, host.config is {}.

Checklist

Step	Action
Define	flareConfig("section", { field: primitive, … }) at module scope
Register	host.cfg(Token, …) before the first build()
Declare	static config = [Token, …] on every class that calls this.config()
Resolve	this.config(Token) in classes, scope.config(Token) in inline routes
Override	FLARE__section__field or keys in flare.json (see reference page)

Related

• Configuration overview: why tokens and merge order.
• flare.json reference: built-in sections, schema, env paths.
• Failure modes: config validation codes.