# @ic-reactor/react

`@ic-reactor/react` is the React binding of ic-reactor 4: three
`"use client"` exports over a client made by
[`@ic-reactor/core`](https://ic-reactor.b3pay.net/v4/packages/core/). There is no hook that wraps
`useQuery` or `useMutation`. You read and write canisters with TanStack Query's
own hooks and the options the client builds, `client.queryOptions(...)` and
`client.mutationOptions(...)`.

The package never re-exports `@ic-reactor/core`, so every name has one export function Providers({ children }: { children: ReactNode }) {
  return (
    <ReactorProvider
      client={() =>
        createClient({ network: "ic", auth: () => new AuthClient() })
      }
    >
      {children}
    </ReactorProvider>
  )
}
```

Who owns a client follows from when it was created, not from where the factory
is written. A getter such as `client ??= createClient(...)` makes the first
provider that calls it the owner. Create a shared client eagerly instead. A
Server Component cannot pass the factory across the client boundary, so in
Next.js the provider sits in a client module that the layout renders: see
[SSR and hydration](https://ic-reactor.b3pay.net/v4/guides/ssr/).

### useClient

`useClient()` returns the client of the nearest provider. It throws outside a
provider. Call it in the body of each component that builds keys or read
options, on every render:

```tsx
export function Fee({ id }: { id: string }) {
  const client = useClient()
  const ledger = client.canister<Actor>(actor, { id })
  const fee = useQuery(client.queryOptions(ledger, "icrc1_fee"))
  return <span>{fee.data?.toString() ?? "…"}</span>
}
```

It follows the client's caller, so a component that calls it renders again on
a sign-in, a switch of account and a sign-out, and builds the new caller's
keys. A change of status that leaves the caller as it is renders nothing.
While a page hydrates in a browser that holds a session, it returns a view for
the anonymous caller, so do not keep its result past its render. See
[SSR and hydration](https://ic-reactor.b3pay.net/v4/guides/ssr/).

### useAuth

`useAuth()` returns `{ status, principal, signIn, signOut }`: the client's
`AuthState` with sign-in and sign-out forwarded to the client. It renders a
component once for each change of status or principal. It is `"anonymous"` on
a server and during a hydrating render. See [Auth](https://ic-reactor.b3pay.net/v4/guides/auth/).

## Life of the client

- **StrictMode.** The development double-mount does not dispose a client in
  use: disposal is scheduled for the next macrotask, and the second mount
  cancels it.
- **A render React throws away.** React runs no cleanup for a render it drops
  before committing it, such as a provider's first render below a Suspense
  boundary that suspends. A client the factory built for it is disposed once
  that render's state is garbage collected (through a `FinalizationRegistry`,
  in a browser).
- **Replacing the client.** Only the factory of the first render is used.
  Passing another function later does not rebuild the client. To replace the
  client, give the provider another `key`.
- **Activity.** If React shows a hidden `Activity` again after the client the
  provider owns was disposed, the provider builds another one with the same
  factory, and it starts with an empty cache. To keep the cache across hiding,
  render the provider above the `Activity`, or give it a client the app owns.

## Where to go next

- [Auth](https://ic-reactor.b3pay.net/v4/guides/auth/): `useAuth`, sign-in and caller changes.
- [Reads](https://ic-reactor.b3pay.net/v4/guides/reads/) and [Writes](https://ic-reactor.b3pay.net/v4/guides/writes/): the options the
  client builds for TanStack Query.
- [SSR and hydration](https://ic-reactor.b3pay.net/v4/guides/ssr/): one client per request, and the limits
  of a signed-in reload.
- [Testing](https://ic-reactor.b3pay.net/v4/guides/testing/): a provider with a borrowed test client.
- [Examples](https://ic-reactor.b3pay.net/v4/examples/): the Vite wallet and the Next.js app.

The guide for both packages is `llms.txt`, shipped in
`node_modules/@ic-reactor/core/llms.txt`; the React package's own `llms.txt`
points to it. The released 3.x package is documented on
[Migrating from 3.x](https://ic-reactor.b3pay.net/v4/migrating-from-3/).