Add your first Capxul provider
Bootstrap the React SDK and display its real readiness states.
This tutorial mounts CapxulProvider, renders its startup states, and reads the
current session. You need a Capxul publishable key and an existing React
application. The examples use a Next.js client boundary; other React frameworks
can pass the same public key into the provider.
Install the Core and React packages together, plus the React SDK's TanStack Query peer dependency:
npm install --save-exact @capxul/sdk@alpha @capxul/sdk-react@alpha @tanstack/react-query1. Add the provider
Create a client component at the root of your application:
"use client";
import { CapxulProvider } from "@capxul/sdk-react";
export function CapxulProviders({
publishableKey,
children,
}: {
publishableKey: string;
children: React.ReactNode;
}) {
return <CapxulProvider publishableKey={publishableKey}>{children}</CapxulProvider>;
}Read the publishable key at your framework's configuration boundary, pass it as
a prop, and mount CapxulProviders above every component that calls a Capxul
hook. Do not create another client inside individual components.
2. Show bootstrap state
useCapxul() reports bootstrapping, ready, or error:
"use client";
import { useCapxul } from "@capxul/sdk-react";
export function CapxulGate({ children }: { children: React.ReactNode }) {
const { status, error, retry } = useCapxul();
if (status === "bootstrapping") return <p>Connecting to Capxul…</p>;
if (status === "error") {
return (
<section>
<p>{error?.message ?? "Capxul could not start."}</p>
<button onClick={retry}>Try again</button>
</section>
);
}
return children;
}The gate is optional. Query hooks remain pending until the client exists, but an explicit gate lets the application distinguish SDK startup from a domain query that is still loading.
3. Read the session
Render a query hook below the provider:
"use client";
import { useCapxulIdentity } from "@capxul/sdk-react";
export function SessionState() {
const identity = useCapxulIdentity();
if (identity.phase === "faulted") return <p>{identity.failure.message}</p>;
if (identity.phase !== "authenticated") return <p>Signed out</p>;
return <p>Signed in as {identity.session.email}</p>;
}You now have one provider-owned client, visible startup recovery, and a React query backed by the Core SDK. Continue with the complete Next.js quickstart to add OTP and Account readiness, or use the hook catalog to choose the next operation.