useOfflineFirst

Reactive offline-first data binding powered by Legend-State’s sync engine.

Combines remote sync with local persistence and automatic retry. Data is available immediately from local cache, then updated from the remote source. Failed remote operations are persisted locally and retried automatically.

Demo

persistloading...

remotesyncing...

count0

+1SyncClear Cache

Usage

import { useOfflineFirst } from "@usels/web";
import { ObservablePersistLocalStorage } from "@legendapp/state/persist-plugins/local-storage";

interface Settings {
  theme: string;
  language: string;
}

function Component() {
  const { data$, isLoaded$, isPersistLoaded$, refetch } = useOfflineFirst<Settings>({
    get: () => fetch("/api/settings").then((r) => r.json()),
    set: ({ value }) =>
      fetch("/api/settings", {
        method: "PUT",
        body: JSON.stringify(value),
      }),
    persistKey: "settings",
    persistPlugin: ObservablePersistLocalStorage,
    initial: { theme: "light", language: "en" },
  });

  return (
    <div>
      {isPersistLoaded$.get() ? (
        <>
          <span>{isLoaded$.get() ? "synced" : "from cache"}</span>
          <span>{data$.theme.get()}</span>
          <button onClick={() => data$.theme.set("dark")}>Dark mode</button>
          <button onClick={refetch}>Sync now</button>
        </>
      ) : (
        <div>Loading cache...</div>
      )}
    </div>
  );
}

Custom retry

import { useOfflineFirst } from "@usels/web";
import { ObservablePersistLocalStorage } from "@legendapp/state/persist-plugins/local-storage";

function Component() {
  const { data$, clearPersist } = useOfflineFirst<string[]>({
    get: () => fetch("/api/items").then((r) => r.json()),
    persistKey: "items",
    persistPlugin: ObservablePersistLocalStorage,
    initial: [],
    retry: {
      infinite: false,
      backoff: "constant",
      maxDelay: 5000,
    },
  });
}

Type Declarations

export interface UseOfflineFirstOptions<T> {
    get: () => Promise<T> | T;
    set?: (params: {
        value: T;
        changes: object[];
    }) => Promise<void> | void;
    initial?: T;
    persistKey: string;
    persistPlugin: PersistOptions["plugin"];
    mode?: "set" | "assign" | "merge" | "append" | "prepend";
    debounceSet?: number;
    transform?: {
        load?: (value: any) => T;
        save?: (value: T) => any;
    };
    retry?: {
        infinite?: boolean;
        backoff?: "constant" | "exponential";
        maxDelay?: number;
    };
}
export interface UseOfflineFirstReturn<T> {
    data$: Observable<T>;
    isLoaded$: ReadonlyObservable<boolean>;
    isFetching$: ReadonlyObservable<boolean>;
    isPersistLoaded$: ReadonlyObservable<boolean>;
    error$: ReadonlyObservable<Error | undefined>;
    lastSync$: ReadonlyObservable<number | undefined>;
    refetch: () => void;
    clearPersist: () => void;
}
export declare function useOfflineFirst<T>(options: UseOfflineFirstOptions<T>): UseOfflineFirstReturn<T>;

Source

View on GitHub

Contributors

• tigerwest

Changelog

• a7392ab 2026-03-06 - feat(core,browser): add sync strategy hooks (tigerwest)