React SDK Implementation Recipes & Patterns

Recipes for the React SDK: HumanityProvider config, HumanityGate patterns, popup vs redirect auth, protected routes, and token storage options.

Task-based recipes built on top of @humanity-org/react-sdk

Prerequisites

• @humanity-org/react-sdk installed
• A Humanity clientId and registered redirectUri from the Developer Portal
• HumanityProvider at the root of your app (Recipe 1 covers setup)

npm install @humanity-org/react-sdk

Recipe 1 — Wrap your app with HumanityProvider

Every component and hook in the React SDK must be inside HumanityProvider. It goes at the root of your app, before your router, before anything else.

import { HumanityProvider } from '@humanity-org/react-sdk';

function App() {
  return (
    <HumanityProvider
      clientId={import.meta.env.VITE_HUMANITY_CLIENT_ID}
      redirectUri={import.meta.env.VITE_HUMANITY_REDIRECT_URI}
      environment="sandbox"
      storage="memory"
    >
      {/* rest of your app */}
    </HumanityProvider>
  );
}

environment: Use "sandbox" during development. Switch to "production" before going live — this points the SDK at the production Humanity API.

storage: "memory" (the default) keeps tokens in JS memory only — they don't survive a page refresh. See Recipe 12 for when to change this.

Full prop reference: HumanityProvider

Recipe 2 — Sign out

import { useAuth } from '@humanity-org/react-sdk';

function SignOutButton() {
  const { logout } = useAuth();
  return <button onClick={logout}>Sign out</button>;
}

To navigate after signing out, call logout() then redirect with your router:

import { useAuth } from '@humanity-org/react-sdk';
import { useNavigate } from 'react-router-dom';

function SignOutButton() {
  const { logout } = useAuth();
  const navigate = useNavigate();

  const handleSignOut = () => {
    logout();
    navigate('/');
  };

  return <button onClick={handleSignOut}>Sign out</button>;
}

Full prop reference useAuth()

Recipe 3 — Protect a route with React Router

Check isAuthenticated from useAuth and redirect before rendering protected content.

import { Navigate, Outlet } from 'react-router-dom';
import { useAuth } from '@humanity-org/react-sdk';

function ProtectedRoute() {
  const { isAuthenticated, isLoading } = useAuth();

  if (isLoading) return <div>Loading...</div>;
  if (!isAuthenticated) return <Navigate to="/login" replace />;

  return <Outlet />;
}

Wire it into your router:

import { BrowserRouter, Routes, Route } from 'react-router-dom';

<BrowserRouter>
  <Routes>
    <Route path="/login" element={<LoginPage />} />
    <Route element={<ProtectedRoute />}>
      <Route path="/dashboard" element={<Dashboard />} />
      <Route path="/profile" element={<Profile />} />
    </Route>
  </Routes>
</BrowserRouter>

Any route nested under <ProtectedRoute /> redirects to /login if the user isn't authenticated.

Recipe 4 — Choose a token storage strategy

Set storage on HumanityProvider. The choice affects security and session persistence.

<HumanityProvider
  clientId="hp_xxx"
  redirectUri="https://app.com/callback"
  storage="memory"
>
  <App />
</HumanityProvider>

Strategy	Security	Survives refresh	When to use
memory	Highest	No	Default. Tokens live in JS memory only. Right for most apps.
sessionStorage	Medium	No	Tokens persist across React re-renders but clear when the tab closes.
localStorage	Lower	Yes	Only when persistence across browser restarts is a hard requirement. Understand the XSS risk first.

Start with memory. Switch to sessionStorage if users are losing their session on page reload in a way that disrupts the experience. Use localStorage only when persistence across browser restarts is a hard requirement — and not before checking your XSS exposure.

localStorage tokens are readable by any JS on the page. If you load third-party scripts (analytics, ads, widgets), that's a real risk.

⚠️ Firefox and Safari: both browsers clear sessionStorage during cross-domain OAuth redirects, which can cause silent auth failures in redirect mode. If you need to support these browsers with redirect mode, test this flow before shipping.

Full prop reference HumanityProvider