react

Every export of @kitr/react, read from the published type definitions. The guide shows them in use.

@kitr/react

createApp

function createApp(options?: CreateAppOptions): KitrApp;

Creates the app object that owns the container, config and providers. Call boot() on it before reading services; one app per client, per server process and per test.

KitrBoot

function KitrBoot({ app, children, fallback }: KitrProviderProps & {
  fallback?: ReactNode;
}): import("react").JSX.Element;

Boot an app inside React. Renders fallback until boot completes. Use in client-only apps; server-rendered apps boot before rendering.

KitrProvider

function KitrProvider({ app, children }: KitrProviderProps): import("react").JSX.Element;

Puts the app in context and renders every provider's wrap() around children. Boot the app first (await app.boot()) when you can; otherwise it suspends until boot completes.

useApp

function useApp(): KitrApp;

The app in context: its container, config, env, mode, environment and platform. Throws when the component is not rendered inside KitrProvider (or KitrBoot, or the router).

useConfig

function useConfig<K extends Parameters<KitrApp['config']['get']>[0]>(key: K): import("@kitr/core").ConfigOf<K>;

Read one package's config, as exported by config/<name>.ts, typed from ConfigRegistry. Throws when that config does not exist; use useApp().config.get(key, fallback) for optional config.

useService

function useService<K extends Parameters<KitrApp['container']['use']>[0]>(key: K): import("@kitr/core").Binding<K>;

Read a container binding from a component, typed from ContainerBindings (useService('http')). The binding must be resolved, which it is after boot; an unknown key throws.

KitrApp

class KitrApp {
  readonly container: Container;
  readonly config: ConfigStore;
  readonly environment: AppEnvironment;
  readonly mode: AppMode;
  readonly env: Record<string, unknown>;
  readonly providers: KitrProvider[];
  /** Native drivers registered by platform providers, resolved by capability packages. */
  readonly drivers: DriverRegistry;
  /** The platform name from kitrrc.ts this bundle runs as, when known. */
  readonly platform: PlatformName | undefined;
  /** This app's named queries and mutations. A fork reads through to its parent's. */
  readonly operations: OperationRegistry;
  private inputs;
  private phase;
  private readying;
  private booting?;
  constructor(options?: CreateAppOptions);
  get isClient(): boolean;
  get isServer(): boolean;
  get isDevelopment(): boolean;
  get isProduction(): boolean;
  /** Add a provider before boot. */
  use(provider: ProviderInput): this;
  /** register → boot. Idempotent: concurrent callers share one boot. */
  boot(): Promise<this>;
  /** Server only: tell providers the server is serving. Idempotent: runs each `ready` once. */
  ready(): Promise<this>;
  /** Server only: run providers' `shutdown` in reverse order. */
  shutdown(): Promise<void>;
  /** Compose every provider's `wrap`, outermost first. */
  wrap(children: KitrNode): KitrNode;
  /** A request- or test-scoped app that shares providers and config but has its own instances. */
  fork(): KitrApp;
  get status(): Phase;
}

The app object every provider sees. One per client, one per server process, one per test. It owns the container, the config and the provider list.

CreateAppOptions

interface CreateAppOptions {
  /** Providers to register, in order. Usually the list from `kitrrc.ts`. */
  providers?: ProviderInput[];
  /** Per-package config, keyed the way `config/<name>.ts` files are. */
  config?: Record<string, unknown>;
  /** client | server | test. Default: `test` under Vitest, `client` when `window` exists, otherwise `server`. */
  environment?: AppEnvironment;
  /** development | production | test. Default: from Vite's `import.meta.env.MODE` or `NODE_ENV`. */
  mode?: AppMode;
  /** Validated env object (from `createEnv`). Exposed as `app.env`. */
  env?: Record<string, unknown>;
  /** The platform name this bundle was built for (`kitr dev site` → `site`). Default: from `import.meta.env.KITR_PLATFORM`. */
  platform?: PlatformName;
  /**
   * Every named query and mutation, by name: the `operations` map `kitr types` writes to
   * `.kitr/actions.ts`. Registered on this app (and every fork of it), so `useQuery('projects.list')`
   * and `call(app, 'projects.update', input)` resolve through `app.operations`.
   */
  operations?: Record<string, OperationLike>;
}

Options for createApp(): the providers to register, their config and the runtime details.

KitrProviderProps

interface KitrProviderProps {
  /** The app from `app/app.ts`. Every provider's `wrap()` is rendered around `children`. */
  app: KitrApp;
  /** The tree that can call `useApp`, `useService` and `useConfig`. */
  children: ReactNode;
}

Props of KitrProvider and KitrBoot: the app to put in context and the tree that reads it.