platform

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

kitr/platform

createPlatform

function createPlatform(app: KitrApp, driver?: PlatformDriver): Platform;

deepLinkPath

function deepLinkPath(url: string, prefixes?: string[]): string;

Strip a configured prefix from a deep link so it can be handed to the router.

defaultDriver

function defaultDriver(): PlatformDriver;

The browser (or server) driver used when no platform package registered one.

osFromUserAgent

function osFromUserAgent(ua: string): PlatformOs;

perPlatform

function perPlatform<T>(platform: Pick<Platform, 'type' | 'os' | 'native'>, impls: Partial<Record<PlatformType | PlatformOs | 'native', () => T>> & {
  default: () => T;
}): T;

Pick an implementation per platform without branching in components:

const save = perPlatform(platform, { web: () => download, mobile: () => share, desktop: () => saveDialog })

Keys are platform types or OS names; native covers every native shell; default is required.

defineConfig

const defineConfig: <const C extends PlatformConfig>(config: C) => C;

Platform

interface Platform {
  readonly type: PlatformType;
  readonly native: boolean;
  readonly os: PlatformOs | string;
  readonly standalone: boolean;
  /** The platform name from kitrrc.ts the bundle was built for, when known. */
  readonly name: string | undefined;
  readonly driver: PlatformDriver;
  isOnline(): boolean;
  appVersion(): Promise<string>;
  onAppState(listener: (active: boolean) => void): () => void;
  onBackButton(listener: (info: {
    canGoBack: boolean;
  }) => void): () => void;
  onDeepLink(listener: (url: string) => void): () => void;
  onOnline(listener: (online: boolean) => void): () => void;
  safeArea(): SafeArea;
  openExternal(url: string): Promise<void>;
  exit(): Promise<void>;
  /** `platform.is('mobile')`, `platform.is('ios')`: matches the type or the OS. */
  is(what: PlatformType | PlatformOs): boolean;
}

The platform service: the active driver plus safe defaults for everything it leaves out.

PlatformConfig

interface PlatformConfig {
  /** Route deep links by stripping this prefix (`myapp://` or `https://app.example.com`) before navigating. */
  deepLinkPrefixes?: string[];
}

PlatformDriver

interface PlatformDriver {
  /** `web`, `mobile`, `desktop`, `server` or a custom platform type. */
  type: PlatformType;
  /** True inside a native shell (Capacitor, Tauri, Electron). */
  native: boolean;
  os(): PlatformOs | string;
  /** Installed as an app (PWA standalone, native shell). */
  standalone?(): boolean;
  appVersion?(): Promise<string>;
  /** Foreground/background. */
  onAppState?(listener: (active: boolean) => void): () => void;
  /** Hardware or window back button. */
  onBackButton?(listener: (info: {
    canGoBack: boolean;
  }) => void): () => void;
  /** Deep links and custom-scheme URLs opened while the app runs. */
  onDeepLink?(listener: (url: string) => void): () => void;
  onOnline?(listener: (online: boolean) => void): () => void;
  isOnline?(): boolean;
  safeArea?(): SafeArea;
  /** Open a URL in the system browser (native) or a new tab (web). */
  openExternal?(url: string): Promise<void>;
  /** Exit the app where the platform allows it (Android back at root, desktop). */
  exit?(): Promise<void>;
}

SafeArea

interface SafeArea {
  top: number;
  right: number;
  bottom: number;
  left: number;
}

PlatformOs

type PlatformOs = 'ios' | 'android' | 'macos' | 'windows' | 'linux' | 'server' | 'unknown';

PlatformType

type PlatformType = 'web' | 'mobile' | 'desktop' | 'server' | (string & {});

Where the app runs, as one API. Platform packages register a PlatformDriver; the platform service wraps whichever is active, with a browser/server default.

kitr/platform/react

useAppState

function useAppState(): boolean;

Foreground (true) or background. Backed by Capacitor App on mobile, window focus on desktop, visibility on the web.

useBackButton

function useBackButton(handler: (info: {
  canGoBack: boolean;
}) => void): void;

Android hardware back button, desktop window close. Return nothing to let the default run.

useDeepLink

function useDeepLink(handler: (url: string) => void): void;

Deep links opened while the app runs. Pair with deepLinkPath() to hand them to the router.

useOnline

function useOnline(): boolean;

true while the device reports a connection. Hydration-safe: the server and first render say online.

usePlatform

function usePlatform(): Platform;

The platform service from the container.

useSafeArea

function useSafeArea(): SafeArea;

Safe-area insets (notch, home indicator). Zero on the server and first render.

kitr/platform/provider

platformProvider

const platformProvider: import("@kitr/core").KitrProvider;

Binds the platform service from the active platform driver. Platform packages (kitr/mobile/provider, kitr/desktop/provider...) register their driver in register(), so list them before this provider in kitrrc.ts; kitr add keeps that order.

kitr/platform/devtools

panels

function panels(app: KitrApp): DevtoolsPanel[];

The Platform panel: active platform, OS and which package supplies each capability driver.