offline

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

@kitr/offline

bindOnlineManager

function bindOnlineManager(platform: {
  isOnline(): boolean;
  onOnline(l: (online: boolean) => void): () => void;
}): void;

Let TanStack Query's online state follow the platform driver (native shells report it better than navigator.onLine).

createOffline

function createOffline(client: QueryClient, config?: OfflineConfig, app?: KitrApp): Offline;

Build the offline service for a QueryClient: it saves successful queries and paused mutations to storage on a throttle (and when the page is hidden), and can restore them into the client.

registerMutationDefaults

function registerMutationDefaults(client: QueryClient, operations: OperationRegistry): void;

A mutation restored from a snapshot has its key and input but no mutationFn: functions do not survive a reload. Give every named mutation (defineMutation('projects.rename', ...) in

useOffline

function useOffline(app: KitrApp): Offline;

The offline service from an app's container, for code outside React. Bound on the client only.

defineConfig

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

Type-checks config/offline.ts. Returns the object unchanged.

Offline

interface Offline {
  /** Load a stored snapshot into the client, if fresh. Resolves with whether one was found. */
  restore(): Promise<boolean>;
  /** Write the current cache now (the provider does it on a throttle). */
  persist(): void;
  /** Forget the snapshot. */
  clear(): void;
  /** Mutations waiting for the network. */
  pendingMutations(): number;
  /** Whether TanStack Query's `onlineManager` currently says online. */
  isOnline(): boolean;
  /** Called after a restore, after each throttled save, and when online state changes. Returns an unsubscribe function. */
  subscribe(listener: () => void): () => void;
  /** True once `restore()` loaded a snapshot into the client. */
  readonly restored: boolean;
}

The offline service: restores and saves the query cache snapshot and reports network state.

OfflineConfig

interface OfflineConfig {
  /** Storage key for the cache snapshot. Default `kitr:query-cache`. */
  key?: string;
  /** Milliseconds a snapshot stays usable. Default 24 hours. */
  maxAge?: number;
  /** Persist only queries whose key passes; default: every successful query. */
  include?: (queryKey: QueryKey) => boolean;
  /** Milliseconds to wait after a change before writing. Default 1000. */
  throttle?: number;
  /** Where the snapshot lives. Default: the app's local storage driver (native on desktop/mobile). */
  storage?: StorageDriver;
  /** A string that invalidates old snapshots when the data shape changes (app version). */
  buster?: string;
}

Options for config/offline.ts: how long, where and what of the query cache is kept on the device.

@kitr/offline/react

useOffline

function useOffline(): {
  online: boolean;
  pending: number;
  restored: boolean;
  clear: (() => void) | (() => void);
  persist: (() => void) | (() => void);
};

{ online, pending, restored }: whether the network is up, how many mutations wait for it, and whether the cache came from a stored snapshot. Hydration-safe: the server says online.

@kitr/offline/provider

offlineProvider

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

Persists the query cache and paused mutations, restores them before the first render and replays the mutations when the network returns (TanStack Query resumes paused mutations on its own once onlineManager says online). Put it after the query provider in kitrrc.ts.