@prex0/v3-react

@prex0/v3-react provides React bindings and hooks for building Prex v3 apps on top of Alchemy Account Kit. The package bundles common data-fetching hooks, mutation helpers, and providers so your app can authenticate users, talk to the Prex API/graph, and orchestrate user operations with minimal boilerplate.

Installation

npm install @prex0/v3-react

Peer requirements:

• React 19
• react-dom 19

The package depends on @account-kit/*, @tanstack/react-query, and viem; they install automatically as dependencies of @prex0/v3-react.

Configure Alchemy Account Kit

Use the helper exported from @prex0/v3-react/server to create an Alchemy config tuned for Prex:

import { getAlchemyConfig, cookieToInitialState } from '@prex0/v3-react/server';

const config = getAlchemyConfig({
  policyId: '<ALCHEMY_POLICY_ID>',
  apiKey: process.env.ALCHEMY_API_KEY!,
  sessionKey: 'prex-session',
  chainEnv: 'testnet', // or "mainnet"
});

// Optional: hydrate the initial account state when using SSR
const initialState = cookieToInitialState(req.headers.cookie ?? '');

getAlchemyConfig wraps createConfig from Account Kit and sets defaults for Optimism/Optimism Sepolia, SSR-safe cookie storage, popup OAuth, and a long-lived session key. You can also pass a UI config object to override default UI components if needed.

App providers

Wrap your React tree with PrexFullProvider to connect Account Kit, React Query, and the Prex client:

import { PrexFullProvider } from '@prex0/v3-react';

<PrexFullProvider
  config={config}
  initialState={initialState}
  alchemyPolicyId="<ALCHEMY_POLICY_ID>"
  apiEndpoint="https://api.prex.example"
  graphEndpoint="https://graph.prex.example"
>
  <App />
</PrexFullProvider>;

Provider props:

• config: AlchemyAccountsConfigWithUI created with getAlchemyConfig (or manually via Account Kit).
• initialState (optional): server-derived state from cookieToInitialState for seamless SSR hydration.
• alchemyPolicyId: passed to useSmartAccountClient to bind the embedded smart account.
• apiEndpoint / graphEndpoint: override REST/Graph endpoints; sensible defaults are provided for testnet use.
• isDryRun: force mock behavior when truthy.

For local demos or Storybook, PrexDummyProvider exposes the same context shape but uses MockPrexV3Client, a synthetic wallet, and a dummy API client so hooks resolve without talking to the network.

Using the Prex context and hooks

usePrexContext exposes the lower-level primitives used by the generated hooks:

import { usePrexContext } from '@prex0/v3-react';

const {
  wallet,
  prexClient,
  sendUserOperation,
  signMessage,
  stampWhoAmI,
  logout,
} = usePrexContext();

Common patterns:

• Use wallet to check authentication state and obtain the connected address and ID token.
• Call prexClient methods (token, ticket, batch, lottery, etc.) directly when you need imperative access.
• sendUserOperation submits a single or batched user operation through the configured bundler/client.
• signMessage and stampWhoAmI help produce authenticated signatures for backend requests.

High-level React Query hooks build on top of this context. Examples:

import { useBalance, useUser } from '@prex0/v3-react';

const { data: user } = useUser();
const { data: balance } = useBalance({
  tokenAddress: '0x...',
  userAddress: user?.walletAddress,
});

Available hooks cover user profiles, token and ticket balances/activities, JPY withdrawals, drop/link transfer flows, marketplace listings, lottery management, and more (see src/index.ts exports). All hooks automatically share the QueryClient instance created by the provider.

Server utilities

@prex0/v3-react/server also re-exports cookieToInitialState, AlchemyAccountsConfig, and AlchemyClientState from @account-kit/core so you can type and hydrate account state in frameworks with server components.

Publishing

The package bundles compiled outputs under dist and ships TypeScript sources for reference. With this README in place and the existing build script (tsup) succeeding, the package is ready for npm publish.