App Facade API

primate/AppFacade is a type-only entrypoint for the value returned by config() and exported from config/app.ts.

import type AppFacade from "primate/AppFacade";

Application code normally imports the configured instance rather than this type. See the Application guide for usage patterns and the Configuration guide for creating the instance.

`AppFacade`

declare class AppFacade<
  T extends EnvSchema = EnvSchema,
  I extends I18NConfig | undefined = undefined,
  D extends DB = DB,
> {
  get i18n(): I18NRuntime<I>;
  config<P extends string>(path: P): ConfigValue<P>;
  migrate(value: MigrationDeclaration<D>): MigrationDeclaration<D>;
  env<K extends keyof T>(key: K): T[K]["infer"];
  get views(): ViewBag;
  get root(): FileRef;
  get log(): AppLogger;
}

ConfigValue, ViewBag, and AppLogger are readable representations of inferred supporting contracts; they are not exports from primate/AppFacade. The constructor and framework attachment symbols are internal and are omitted.

`app.i18n`

get i18n(): I18NRuntime<I>;

Localization facade inferred from input.i18n. This is the only facade member available in browser builds. Without i18n configuration, accessing localization operations uses the missing-i18n behavior. See the primate/i18n API and Internationalization guide.

`app.config()`

config<P extends string>(path: P): ConfigValue<P>;

Reads the parsed configuration through a dot-separated path. TypeScript infers the result for valid paths, including applied defaults. This method is server-only and throws when called from a browser build.

import app from "@/config/app";

const port = app.config("http.port"); // number

`app.migrate()`

migrate(
  value: MigrationDeclaration<D>,
): MigrationDeclaration<D>;

Validates and normalizes an application migration declaration while preserving the configured migration database type. It requires an eight-character lowercase hexadecimal id, unique valid parent IDs, and an optional function run. Invalid declarations throw migration diagnostics. This method is server-only and throws in browser builds.

`MigrationDeclaration`

Supporting input/output type for app.migrate().

type MigrationDeclaration<D extends DB = DB> = {
  id: string;
  parents: readonly string[];
  run?: (db: D) => MaybePromise<unknown>;
};

`app.env()`

env<K extends keyof T>(key: K): T[K]["infer"];

With env.schema, returns the parsed value for a declared key and throws when the key is missing from the parsed environment. Without a schema, it reads the named environment value as unknown. Invalid schema input fails when the server facade is attached. env() is server-only and throws in browser builds.

`app.views`

get views(): ViewBag;

The server's loaded view registry. It becomes available after the application facade is attached to the serving app; access before that point throws. This property is not available in browser builds.

const render = app.views.get<
  (props: { title: string }) => string | Promise<string>
>("docs/home/index.md");

`ViewBag`

Framework-owned supporting shape returned by app.views. It is not exported from primate/AppFacade.

type ViewBag = {
  get<T>(name: string): T;
  try(name: string): unknown | undefined;
  has(name: string): boolean;
  keys(): string[];
  values(): unknown[];
  entries(): [string, unknown][];
};

get() resolves registered frontend extensions and throws when no view exists. try() returns undefined instead. The collection methods return snapshots of the current registry.

`app.root`

get root(): FileRef;

Project-root filesystem reference from @rcompat/fs. It becomes available after server attachment and throws when used too early. In browser builds the getter always throws.

`app.log`

get log(): AppLogger;

Application logger attached to the serving app. It throws before server attachment and in browser builds.

`AppLogger`

Supporting shape returned by app.log.

type AppLogger = {
  readonly level: string;
  print(strings: TemplateStringsArray, ...params: unknown[]): void;
  system(strings: TemplateStringsArray, ...params: unknown[]): void;
  trace(strings: TemplateStringsArray, ...params: unknown[]): void;
  info(strings: TemplateStringsArray, ...params: unknown[]): void;
  warn(strings: TemplateStringsArray, ...params: unknown[]): void;
  error(error: unknown): void;
};

trace, info, and warn are tagged-template methods and notify registered module log hooks even when their level is below the console threshold. print and system write unclassified output. error() accepts an unknown thrown value.

Browser availability

The browser-conditioned AppFacade keeps the typed i18n getter. config(), migrate(), env(), root, and log throw explicit server-only errors; views is absent. Do not import server configuration or environment access into frontend code.

Module

Store