React

All React-based frameworks (Vite, Next.js, Remix, TanStack Start) share the same adapter layer — the CLI generates 16 React hooks into swoff/adapters/. The only differences are config values in swoff.config.json.

Astro with React islands: See the dedicated Astro page if you're using Astro (with or without React). The React hooks are still available for client:load React components.

Config per flavor

| navigation.mode | "spa" | "spa" | "spa" | "spa" | | navigation.fallback | "/index.html" | "/index.html" | "/index.html" | "/index.html" | | navigation.preload | true | true | true | true | | strategy.ignoreQueryParams | [] | ["_rsc"] | ["_data"] | [] |

All other config fields (strategy.default, strategy.patterns, features.*) are the same across flavors.

For detailed setup guides, see React SPA, TanStack Start, and Next.js.

Generated adapters

The CLI generates these hooks into swoff/adapters/. Import them directly:

import { useSwoffFetch } from "./swoff/adapters/useSwoffFetch";

Hook API

useSwoffFetch<T>(url, options?)

const { data, error, loading, refetch } = useSwoffFetch<Todo[]>("/api/todos");
const { data: posts } = useSwoffFetch<Post[]>("/api/posts", {
  enabled: !!user,
});

Returns { data: T \| null, error: unknown, loading: boolean, refetch: () => void }.

• Auto-refetches on cache-invalidated events matching the URL
• Dependent queries: pass enabled: false or a nullable URL to skip until a condition is met
• Stale data is automatically refreshed in the background by the SW (batched & rate-limited) when using the reactive strategy. On online event, reactive entries with refetchOnReconnect are recovered.

useSwoffMutation<TData>(url, options?)

const {
  mutate,
  isLoading,
  isError,
  isSuccess,
  data,
  error,
  reset,
  mutationId,
} = useSwoffMutation<{ id: number }>("/api/todos", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  auth: true,
  onSuccess: (data) => navigate(`/item/${data.id}`),
  onError: (err) => console.error(err),
  onMutate: () => {
    /* optimistic update */
  },
});
mutate(JSON.stringify({ title: "New" }));

The endpoint and request config (method, headers, auth) are fixed at the hook level. All calls to mutate share the same isLoading, error, data, and isSuccess state.

mutate() returns a MutateResult<T>:

useSwoffPrefetch()

const prefetch = useSwoffPrefetch();
<a onMouseEnter={() => prefetch("/api/todos")}>Todos</a>

Returns a stable prefetch(input, options?) callback. Internally tracks a prefetchList (string array of prefetched URLs) which is accessible for debugging. Call clear() to reset the list.

useSwoffReset()

const { reset, isResetting, error } = useSwoffReset();

useSwoffMutationState(id)

const mutation = useSwoffMutationState(mutationId);
if (mutation?.status === "error") {
  /* show error */
}

Returns MutationState | null. Subscribes to a specific mutation's state changes. Pass null or empty string to disable.

useSwoffQueue()

const { pending, items, lastSync, isProcessing, retryAll } = useSwoffQueue();

useSwoffNetwork()

const { online, wasOffline, lastChangedAt, effectiveType, downlink } =
  useSwoffNetwork();

useSwoffAuth()

const {
  authenticated,
  auth,
  online,
  isLoading,
  error,
  setAuth,
  clearAuth,
  ensureValid,
} = useSwoffAuth();

Reacts to sw-auth-state-change events dispatched by clearAuth(), setAuth(), or the SW's AUTH_CLEARED broadcast for cross-tab sync.

useSwoffPrecache()

const { progress } = useSwoffPrecache();

Returns progress (0–100) from the background precache phase. Show the indicator when progress > 0 && progress < 100.

useSwoffPush()

const {
  subscribed,
  subscription,
  permission,
  loading,
  subscribe,
  unsubscribe,
} = useSwoffPush();

Generated when features.pushNotifications is true.

useSwoffSync()

const { supported, registered, lastSync, triggerSync } = useSwoffSync();

Generated when features.mutationQueue.backgroundSync.

useSwoffPwa()

const { isInstallable, promptInstall } = useSwoffPwa();

Generated when features.pwa.enabled.

useSwoffAnalytics(callback?)

const { lastEvent, events, clear } = useSwoffAnalytics();

Tracks offline navigation fallback events. Optionally pass a callback that fires on each event. clear() resets the event list.

useSwoffStorage()

const {
  usage,
  quota,
  percentUsed,
  formattedUsage,
  formattedQuota,
  loading,
  error,
} = useSwoffStorage();

By default, re-checks on every visibilitychange to "visible" (pass false to disable auto-refresh).

Entry point

For all React flavors, import initServiceWorker in your root component:

import { useEffect } from "react";
import { initServiceWorker } from "./swoff/client-injector";

function App() {
  useEffect(() => {
    initServiceWorker();
  }, []);
  return <YourApp />;
}

See the Next.js guide for App Router and Pages Router setup. Remix: call in app/root.tsx client entry.

Build script

Run the SW generator after your build:

node swoff/sw/generator.mjs

Or add it to package.json:

{
  "scripts": {
    "build": "your-framework-build && node swoff/sw/generator.mjs"
  }
}

Next.js static export output goes to out/ — the SW generator reads build.swOutput from config and writes there automatically.