npm package: @prex0/v3-react
Description: `@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, an
Latest version: 0.2.4

# @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

```bash
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:

```ts
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:

```tsx
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:

```ts
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:

```ts
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`.