@ic-reactor/react

@ic-reactor/react is the recommended package for React applications. It re-exports the runtime classes from @ic-reactor/core and adds hook factories, auth hooks, direct reactor hooks, and reusable query factories designed around TanStack Query.

Why Use This Package

You want idiomatic React hooks for queries, mutations, suspense, and auth.
You want ClientManager, Reactor, and DisplayReactor from one package.
You want to keep your app code focused on components instead of manual query wiring.

Installation

pnpm add @ic-reactor/react @tanstack/react-query @icp-sdk/core

# Optional: Internet Identity support (@icp-sdk/auth v8)
pnpm add @icp-sdk/auth

react is the only required React peer — react-dom is declared as an optional peer and never imported. @icp-sdk/auth is optional too: it is loaded through a literal import("@icp-sdk/auth/client") inside a try block, which webpack-family bundlers treat as declaring an optional dependency — with the peer absent the build succeeds and prints one Module not found: Can't resolve '@icp-sdk/auth/client' warning. Install the peer to remove the warning, or silence it with ignoreWarnings (in Next.js, assign it inside the webpack(config) callback):

ignoreWarnings: [{ module: /@ic-reactor\/react/, message: /@icp-sdk\/auth/ }]

That optional-try treatment is webpack-specific — other bundlers may fail to resolve the missing specifier at build time. If yours does, install the peer, or construct the AuthClient yourself and pass it as authClient to AuthenticationManager, in which case IC Reactor never imports @icp-sdk/auth at all.

The package requires Node.js 18+ (declared in engines).

What’s Included

React SetupComplete app wiring with QueryClientProvider, ClientManager, and a Reactor instance.

createActorHooksGenerate typed canister hooks from a bound reactor instance.

createAuthHooksReact hooks for login, logout, agent state, and user principal access.

Reactor HooksDirect hooks that accept a reactor instance explicitly.

Factory FunctionsReusable query and mutation factories for shared data access patterns.

Quick Start

import { ClientManager, Reactor, createActorHooks } from "@ic-reactor/react"
import { QueryClient } from "@tanstack/react-query"
import { idlFactory, type _SERVICE } from "./declarations/backend"

const queryClient = new QueryClient()
const clientManager = new ClientManager({ queryClient })

const backend = new Reactor<_SERVICE>({
  clientManager,
  idlFactory,
  name: "backend",
})

export const { useActorQuery, useActorMutation } = createActorHooks(backend)

Identity Attributes

useIdentityAttributes() comes from createIdentityAttributeHooks(), a factory separate from createAuthHooks(). It returns the helpers for requesting signed OpenID email and profile attributes:

import {
  AuthenticationManager,
  IdentityAttributesManager,
  createIdentityAttributeHooks,
} from "@ic-reactor/react"

const authentication = new AuthenticationManager({ clientManager })
const identityAttributes = new IdentityAttributesManager(authentication)

const { useIdentityAttributes } =
  createIdentityAttributeHooks(identityAttributes)

function ContinueWithProvider() {
  const { requestOpenIdAttributes, isRequestingAttributes } =
    useIdentityAttributes()

  async function handleClick() {
    const result = await requestOpenIdAttributes({
      // Pass the nonce as a callback: awaiting it first ends the user gesture
      // and the browser blocks the Internet Identity window.
      nonce: () => backend.callMethod({ functionName: "register_begin" }),
      openIdProvider: "microsoft",
      keys: ["email", "name"],
    })

    await backend.callMethod({
      functionName: "register_finish",
      args: [
        {
          data: result.signedAttributes.data,
          signature: result.signedAttributes.signature,
        },
      ],
    })
  }

  return (
    <button disabled={isRequestingAttributes} onClick={handleClick}>
      Continue with provider
    </button>
  )
}

Provider aliases ("google", "apple", and "microsoft") and full issuer URLs are supported. Always verify the signed payload server-side or in your canister before trusting decoded values.