Function createApp

packages/core/src/app/createApp.ts:132–1172

(opts: CreateAppStateOptions<S> | CreateAppRoutesOnlyOptions)

export function createApp(opts: CreateAppRoutesOnlyOptions): App<Record<string, never>>;
export function createApp<S>(opts: CreateAppStateOptions<S>): App<S>;
export function createApp<S>(opts: CreateAppStateOptions<S> | CreateAppRoutesOnlyOptions): App<S> {
  const backend = opts.backend;
  const config = resolveAppConfig(opts.config);

  const backendDrawlistVersion = readBackendDrawlistVersionMarker(backend);
  if (backendDrawlistVersion !== null && backendDrawlistVersion !== 1) {
    invalidProps(
      `backend drawlistVersion=${String(
        backendDrawlistVersion,
      )} is invalid. Fix: set backend drawlist version marker to 1.`,
    );
  }

  const backendMaxEventBytes = readBackendPositiveIntMarker(
    backend,
    BACKEND_MAX_EVENT_BYTES_MARKER,
  );
  if (backendMaxEventBytes !== null && backendMaxEventBytes !== config.maxEventBytes) {
    invalidProps(
      `config.maxEventBytes=${String(config.maxEventBytes)} must match backend maxEventBytes=${String(
        backendMaxEventBytes,
      )}. Fix: align maxEventBytes between app config and backend, or prefer createNodeApp({ config }) for Node/Bun apps to keep them aligned automatically.`,
    );
  }

  const backendFpsCap = readBackendPositiveIntMarker(backend, BACKEND_FPS_CAP_MARKER);
  if (backendFpsCap !== null && backendFpsCap !== config.fpsCap) {
    invalidProps(
      `config.fpsCap=${String(config.fpsCap)} must match backend fpsCap=${String(
        backendFpsCap,
      )}. Fix: align fpsCap between app config and backend, or prefer createNodeApp({ config }) for Node/Bun apps to keep them aligned automatically.`,
    );
  }

  let theme = compileTheme(opts.theme ?? defaultTheme.definition);
  let themeTransition: ThemeTransitionState | null = null;
  let terminalProfile: TerminalProfile = DEFAULT_TERMINAL_PROFILE;

  const sm = new AppStateMachine();

  const routes = opts.routes as readonly RouteDefinition<S>[] | undefined;
  if (routes !== undefined && routes.length === 0) {
    invalidProps("routes must contain at least one route");
  }
  if (routes === undefined && opts.initialRoute !== undefined) {
    invalidProps("initialRoute requires routes");
  }
  if (routes !== undefined && opts.initialRoute === undefined) {
    invalidProps("initialRoute is required when routes are provided");
  }
  if (opts.routeHistoryMaxDepth !== undefined) {
    requirePositiveInt("routeHistoryMaxDepth", opts.routeHistoryMaxDepth);
  }

  let mode: Mode | null = null;
  let drawFn: DrawFn | null = null;
  let viewFn: ViewFn<S> | null = null;
  let topLevelViewError: TopLevelViewError | null = null;