@capxul/sdk-react

The React projection over @capxul/sdk. It owns provider lifecycle, TanStack Query bindings, cache invalidation, and React-friendly error state while the Core SDK remains the domain and transport boundary.

"use client";

import { CapxulProvider } from "@capxul/sdk-react";

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <CapxulProvider publishableKey={process.env.NEXT_PUBLIC_CAPXUL_PUBLISHABLE_KEY!}>
      {children}
    </CapxulProvider>
  );
}

Public shape

• CapxulProvider creates or accepts one CapxulClient and owns the React query boundary.
• useCapxul exposes bootstrap status, failure, and retry.
• useCapxulOrgLifecycle(orgId) exposes one Organization's durable setup and retry state; Organization data hooks wait for that same scope to be ready.
• useCapxul* hooks project SDK method bundles into TanStack queries and mutations.
• The root export also contains selected headless slot components. They are a separate public surface, not a substitute for the hook catalog.

The packed npm package exposes only @capxul/sdk-react. The workspace-only @capxul/sdk-react/headless subpath is not present in publishConfig.exports; consumer examples must import packed symbols from the root.

Documentation

• Maintainer context — ownership, invariants, proof, and update triggers.
• Architecture — provider, client, hook, and cache execution paths.
• Proof map — what package checks prove and what remains a live-system claim.
• React SDK guide — tutorials, how-to guides, reference, and explanation.
• Hook catalog — one reference page per public hook.

Development

Run package checks through Vite+:

vp run --filter @capxul/sdk-react check-types
vp run --filter @capxul/sdk-react test
vp pack --filter @capxul/sdk-react