pbvex-react

name	pbvex-react
description	Build, review, or test React integrations using @pbvex/react, including PBVexProvider, typed query/mutation/action hooks, realtime lifecycle, error handling, and mock-client tests. Use for React components that consume PBVex.

PBVex React

Install @pbvex/react and its @pbvex/client peer separately. Create one client for the application owner and provide it near the root:

import { Client } from '@pbvex/client';
import { PBVexProvider } from '@pbvex/react';

const client = new Client('http://localhost:8090');
export function Root({ children }: { children: React.ReactNode }) {
  return <PBVexProvider client={client}>{children}</PBVexProvider>;
}

Use generated public api references with useQuery, useQueryResult, useMutation, and useAction. useQuery returns undefined while loading and throws query errors to an error boundary; use useQueryResult for explicit { data, error, isLoading } rendering. Pass 'skip' to disable a conditional query. Canonically equal inline arguments do not resubscribe, so do not add useMemo solely for PBVex. useSubscription is a compatibility alias for useQuery.

useMutation and useAction return stable typed async callables. usePBVexClient exposes the provider client and throws outside the provider. The provider does not close a client: the owning application/test must close it.

Server rendering receives the initial loading snapshot and does not open a subscription; hydrate live data on the client. PBVex has no built-in optimistic cache mutation layer, so model explicit local optimistic state only when needed. Use pbvex-auth for browser auth-store initialization and pbvex-realtime for transport behavior.

Test lifecycle, not implementation details

Use Vitest, renderHook, a PBVexProvider wrapper, and a mock RealtimeTransport injected into Client. Assert loading/data/error, argument changes, stable mutation callable identity, and cleanup (including React StrictMode double subscriptions). Prefer generated references in app tests; synthetic typed refs are appropriate only for isolated SDK-hook tests.

pnpm --filter @pbvex/react test
sed -n '1,240p' docs/guides/react/testing.md
rg -n "useQuery|PBVexProvider" packages/react/src

Do not call hooks conditionally or let a short-lived component silently own a shared client. Authorization remains server-side even when UI state hides controls.