Wraps a FaableAuthClient in a React context, exposes the current session to your component tree, and keeps it in sync with onAuthStateChange events (sign-in, sign-out, token refresh, user updates).

Install

npm install @faable/auth-helpers-react @faable/auth-js

Peer dependencies: react ^18.0.0, @faable/auth-js ^1.6.1.

Usage

1. Wrap your app with SessionContextProvider

import { FaableAuthClient } from "@faable/auth-js";
import { SessionContextProvider } from "@faable/auth-helpers-react";

const faableauthClient = new FaableAuthClient({
  domain: "https://<team>.auth.faable.com",
});

export function App({ children }: { children: React.ReactNode }) {
  return (
    <SessionContextProvider faableauthClient={faableauthClient}>
      {children}
    </SessionContextProvider>
  );
}

If you have a session available at render time (e.g. from SSR), pass it as initialSession to avoid the initial loading flash.

2. Read the session from any component

import {
  useSession,
  useUser,
  useSessionContext,
  useFaableAuthClient,
} from "@faable/auth-helpers-react";

function Profile() {
  const { isLoading, session, error } = useSessionContext();
  const user = useUser();
  const client = useFaableAuthClient();

  if (isLoading) return <p>Loading…</p>;
  if (error) return <p>Error: {error.message}</p>;
  if (!session) return <button onClick={() => client.signIn()}>Sign in</button>;

  return (
    <div>
      <p>Hello {user?.email}</p>
      <button onClick={() => client.signOut()}>Sign out</button>
    </div>
  );
}

API

<SessionContextProvider>

| Prop | Type | Required | Description | | ------------------ | ------------------- | -------- | -------------------------------------------------------------------------------------- | | faableauthClient | FaableAuthClient | yes | Instance from @faable/auth-js — share the same instance across your whole app. | | initialSession | Session \| null | no | Pre-loaded session (e.g. from SSR or a cookie) used to skip the initial fetch. |

Hooks

| Hook | Returns | Description | | ----------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | | useSessionContext() | { isLoading, session, error, faableauthClient } | Full context tuple — use this when you need the loading or error state. | | useSession() | Session \| null | Current session, or null when signed out / still loading. | | useUser() | User \| null | Shortcut for session?.user ?? null. | | useFaableAuthClient() | FaableAuthClient | The underlying client — use it to call signIn, signOut, etc. |

All hooks must be used inside a SessionContextProvider and will throw otherwise.

License

MIT