React & Next.js

Foir ships the client layer so you don’t hand-roll it. @foir/sdk/react gives you a provider, hooks, and drop-in components; @foir/sdk/next handles server-side sessions and route protection for the Next.js App Router. Both are built on @foir/sdk/auth, so you can drop down to the raw flows any time.

Note: These are entry points of the @foir/sdk package — @foir/sdk/react needs react, and @foir/sdk/next targets the Next.js App Router. You’ll also need a project, a registered relying party, and a publishable API key — see the Quickstart.

React

Wrap your app in FoirProvider, then read the session with hooks or drop in the components. The default session store is the browser’s localStorage; pass your own adapter for a cookie store.

Note: localStorage is the simplest option, not the safest one — a token in localStorage is readable by any script on the page. If you have a backend, use the Next.js adapter below. If you don’t, but you can add a custom login domain, pass hostedSession instead of adapter and the tokens never touch JavaScript at all.

'use client';
import { FoirProvider, SignIn, UserButton, useFoirSession } from '@foir/sdk/react';
 
const env = {
  PLATFORM_API_URL: process.env.NEXT_PUBLIC_PLATFORM_API_URL,
  PLATFORM_API_KEY: process.env.NEXT_PUBLIC_PLATFORM_API_KEY, // a publishable pk_ key
};
 
export function App() {
  return (
    <FoirProvider env={env}>
      <Header />
      <SignIn afterSignInUrl="/dashboard" />
    </FoirProvider>
  );
}
 
function Header() {
  const { isAuthenticated, isLoading } = useFoirSession();
  if (isLoading) return null;
  return isAuthenticated ? <UserButton afterSignOutUrl="/" /> : null;
}

• <FoirProvider> hydrates the stored session on mount and provides it to the tree.
• useFoirSession() returns { status, customer, isAuthenticated, isLoading }; useFoirUser() returns the customer ({ id, email }) or null.
• <SignIn> renders an email/password (or OTP) form plus OAuth buttons, or a hosted-redirect button when you pass hostedUrl.
• <OAuthButtons> discovers the project’s providers and starts the redirect flow; <UserButton> shows the email and a sign-out button.

For a fully custom UI, drive it with useFoirAuth() — signIn, register, signInWithOtp, requestOtp, signInWithProvider, signOut, getToken.

The components are unstyled by default (they carry data-foir-* attributes and accept a className), so you own the look.

Next.js (App Router)

For a server-rendered app, @foir/sdk/next keeps the tokens in HttpOnly cookies — the backend-for-frontend pattern from First-Party Sessions, without the boilerplate.

Protect routes with the middleware:

// middleware.ts
import { createFoirMiddleware } from '@foir/sdk/next';
 
export const middleware = createFoirMiddleware({ signInUrl: '/sign-in' });
export const config = { matcher: ['/dashboard/:path*'] };

Read the session in a server component:

// app/dashboard/page.tsx
import { cookies } from 'next/headers';
import { getFoirSession } from '@foir/sdk/next';
 
export default async function Dashboard() {
  const customer = await getFoirSession(await cookies());
  if (!customer) return null; // middleware already redirected
  return <p>Signed in as {customer.email}</p>;
}

Sign in from a route handler (the tokens are written to HttpOnly cookies):

// app/sign-in/route.ts
import { cookies } from 'next/headers';
import { foirSignInWithPassword } from '@foir/sdk/next';
 
export async function POST(req: Request) {
  const { email, password } = await req.json();
  await foirSignInWithPassword({ env, store: await cookies(), email, password });
  return Response.json({ ok: true });
}

Other server helpers: foirSignInWithOtp, foirRegisterWithPassword, completeFoirProviderLogin (exchange an OAuth callback’s code/state), getFoirToken, and foirSignOut.

Note: The middleware only checks for the session cookie’s presence — it’s edge-safe and fast. The access token itself is validated by the Foir API when you call it, so keep the real gate in your route handlers and server components via getFoirSession.

Going lower

Both packages sit on @foir/sdk/auth, the framework-agnostic layer — customerLogin, customerRegister, OTP and provider flows, and a SessionAdapter token lifecycle. Reach for it directly when you’re not on React or Next, or when you want full control of the session store. See Customer Authentication for the underlying flows and the token model.