React

Bind FFDB state to React

The React SDK package provides FFDB context, auth state, query lifecycle, sync state, and storage-upload hooks.

Shared providers centralize client identity and prevent components from creating inconsistent session or request state.

Use it in React applications after constructing one @ffdb/client instance.

Requirements for React

• Prerequisite — Version-matched @ffdb/client and @ffdb/react SDK packages.
• Prerequisite — A stable FFDBClient instance and an application error/loading strategy.
• Required value — client prop, provider order, query request, dependency list, and optional OfflineSyncClient.
• Required value — Accessible UI states for loading, anonymous, authenticated, empty, and error results.

Install the matched packages

Install @ffdb/react and @ffdb/sync-client from npm at the exact @ffdb/client and server version. The matching GitHub tag also contains checksum-listed tarballs for verified offline installation.

VERSION=0.3.0
npm install --save-exact "@ffdb/client@$VERSION" \
  "@ffdb/sync-client@$VERSION" "@ffdb/react@$VERSION"

Providers and hooks

• useAuth manages current session, sign-in, sign-out, and refresh.
• useQuery cancels superseded HTTP work with AbortController.
• useSync subscribes to an OfflineSyncClient.
• useStorageUpload tracks direct provider upload state.

import { AuthProvider, FFDBProvider, useQuery } from "@ffdb/react";

function App() {
  return (
    <FFDBProvider client={ffdb}>
      <AuthProvider><Documents /></AuthProvider>
    </FFDBProvider>
  );
}

function Documents() {
  const query = useQuery({ sql: "select id, title from documents" }, []);
  // Render query.status, query.data, and query.error.
}

React workflow

• 1. Place FFDBProvider around the application.
• 2. Nest AuthProvider where session state is needed.
• 3. Call hooks only below their providers.
• 4. Render status before data and cancel superseded work.
• 5. Test unmount, refetch, sign-out, and error recovery.

Verify react

Components observe one consistent client/session and do not commit stale request state after unmount or dependency changes.

Troubleshoot react

• A hook reports a missing provider — correct the provider boundary instead of constructing a hidden client.
• A query loops — stabilize request inputs and dependency values.

Continue from React

• Add RLS-aware application screens.
• Connect useSync for offline state if needed.