useCapxul

Reads the bootstrap state of the surrounding CapxulProvider: a status, the bootstrap error (if any), and a retry function.

You rarely need it. Data hooks stay in isPending until the client is ready, so a plain app requires zero bootstrap awareness — render your normal loading states and everything resolves on its own. Reach for useCapxul only when you want an opt-in splash screen or a dedicated bootstrap-error panel with a retry button.

Import

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

Usage

"use client";

import type { ReactNode } from "react";
import { useCapxul } from "@capxul/sdk-react";

function BootstrapGate({ children }: { children: ReactNode }) {
  const { status, error, retry } = useCapxul();

  if (status === "bootstrapping") return <p>Starting up…</p>;
  if (status === "error") {
    return (
      <div>
        <p>{error?.message}</p>
        <button onClick={retry}>Try again</button>
      </div>
    );
  }
  return <>{children}</>;
}

Mount the gate directly under CapxulProvider and the rest of the tree only renders once the client is ready.

Parameters

The hook takes no parameters.

Return type

This is not a TanStack Query hook — it returns a plain CapxulBootstrapState object:

import { type CapxulBootstrapState, type CapxulBootstrapStatus } from "@capxul/sdk-react";
// { status: CapxulBootstrapStatus; error: CapxulError | null; retry: () => void }

status

• "bootstrapping" — the provider is creating the client (the initial state in bootstrap mode, and again after retry).
• "ready" — the client resolved; data hooks are live. In injected client mode this is the state from the first render.
• "error" — the bootstrap failed; error holds the CapxulError.

error

The bootstrap failure as a CapxulError, or null outside the "error" state. This is the bootstrap error only — per-query and per-mutation errors surface on each hook's own error field.

retry

Re-runs the bootstrap with the same provider props: status returns to "bootstrapping", and capxul-scoped queries from the previous attempt are cleared once the new client lands. In injected client mode there is no bootstrap to re-run, so retry is a no-op.

Errors

Calling the hook outside a CapxulProvider throws:

useCapxul must be used within <CapxulProvider>