# IC Reactor

> IC Reactor is a type-safe TypeScript library for calling Internet Computer (ICP) canisters from web apps. It wraps `@icp-sdk/core` agents with TanStack Query caching, React hooks and reusable query/mutation objects, Internet Identity sign-in, runtime Candid parsing, and code generation from `.did` files.

Install `@ic-reactor/react` in a React app and `@ic-reactor/core` anywhere else; `@ic-reactor/react` re-exports all of core. Start with `defineReactor(...)`, or `defineDisplayReactor(...)` when the UI should get strings instead of `bigint` and `Principal`. In a server-rendered app, build it per request with `createReactorProvider(...)`. Call query methods through query hooks or query objects, and state-changing update methods only through mutations. Hooks run only in React components; loaders, actions and scripts use `.fetch()`, `.execute()`, `.invalidate()` and `reactor.callMethod()`.

This file is published from the main branch, so it can describe changes that no release carries yet. Each installed package carries a short guide for its own API at `node_modules/@ic-reactor/<package>/llms.txt`, which matches the installed version. The complete guide, with setup choices, snippets and the mistakes to avoid, is [llms-full.txt](https://ic-reactor.b3pay.net/llms-full.txt). What changed between releases is in the [changelog](https://github.com/B3Pay/ic-reactor/blob/main/CHANGELOG.md).

Package versions this guide describes:

- `@ic-reactor/core`: `3.13.0`
- `@ic-reactor/react`: `3.13.0`
- `@ic-reactor/candid`: `3.13.0`
- `@ic-reactor/codegen`: `0.15.1`
- `@ic-reactor/cli`: `0.15.1`
- `@ic-reactor/vite-plugin`: `0.15.1`
- `@ic-reactor/parser`: `0.6.0`

## Getting started

- [Installation](https://ic-reactor.b3pay.net/v3/getting-started/installation.md): packages for React and non-React apps, optional tooling, `@icp-sdk/auth`, TypeScript and bundler settings
- [Quick Start](https://ic-reactor.b3pay.net/v3/getting-started/quick-start.md): a Vite app with generated hooks, from install to the first query and mutation
- [React Setup](https://ic-reactor.b3pay.net/v3/framework/react-setup.md): `ClientManager` + `Reactor` + hooks, auth hooks, protected routes, several canisters, and server rendering
- [Local Development](https://ic-reactor.b3pay.net/v3/getting-started/local-development.md): local replica, `ic_env` cookie, root key, Codespaces and Gitpod

## Guides

- [Queries](https://ic-reactor.b3pay.net/v3/framework/queries.md): query hooks, `skipToken` for args not known yet, suspense and infinite queries, update methods in queries
- [Mutations](https://ic-reactor.b3pay.net/v3/framework/mutations.md): mutation hooks and objects, `invalidateQueries`, optimistic updates, retries
- [Query Caching](https://ic-reactor.b3pay.net/v3/framework/query-caching.md): query keys, invalidation, cache reads and writes, `QueryClient` defaults
- [Authentication](https://ic-reactor.b3pay.net/v3/guides/authentication.md): Internet Identity sign-in with `AuthenticationManager`, `useAuth`, identity attributes, `@icp-sdk/auth` v8 and v10
- [Error Handling](https://ic-reactor.b3pay.net/v3/guides/error-handling.md): `CanisterError`, `CallError`, `ValidationError`, and which failures are retried
- [Type Safety](https://ic-reactor.b3pay.net/v3/guides/type-safety.md): service types, display types, and `ReactorArgsOf` / `ReactorDataOf` / `ReactorErrorOf`
- [Testing](https://ic-reactor.b3pay.net/v3/guides/testing.md): the fake replica from `@ic-reactor/react/testing` for component and imperative tests

## API reference

- [ClientManager](https://ic-reactor.b3pay.net/v3/reference/ClientManager.md): agent, identity, `QueryClient`, network detection, `fetchAcrossIdentitySwitch`
- [Reactor](https://ic-reactor.b3pay.net/v3/reference/Reactor.md): `callMethod`, `fetchQuery`, `invalidateQueries`, query keys, `forCanister`
- [DisplayReactor](https://ic-reactor.b3pay.net/v3/reference/DisplayReactor.md): display types, validators, Candid-to-display type table
- [createActorHooks](https://ic-reactor.b3pay.net/v3/reference/createActorHooks/overview.md): the six hooks bound to one reactor
- [useActorQuery](https://ic-reactor.b3pay.net/v3/reference/createActorHooks/useActorQuery.md): options, `select`, `callConfig`, `skipToken`
- [useActorMutation](https://ic-reactor.b3pay.net/v3/reference/createActorHooks/useActorMutation.md): `onCanisterError`, `invalidateQueries`, retries
- [useActorMethod](https://ic-reactor.b3pay.net/v3/reference/createActorHooks/useactormethod.md): one hook for query and update methods with an imperative `call()`
- [Query and mutation factories](https://ic-reactor.b3pay.net/v3/reference/factories/overview.md): reusable objects that work inside and outside React
- [createQuery](https://ic-reactor.b3pay.net/v3/reference/factories/createQuery.md): `createQuery`, `createQueryFactory`, `fetch()`, `invalidate()`, `optimisticUpdate()`
- [createMutation](https://ic-reactor.b3pay.net/v3/reference/factories/createMutation.md): `useMutation()`, `execute()`, invalidation targets
- [createInfiniteQuery](https://ic-reactor.b3pay.net/v3/reference/factories/createInfiniteQuery.md): paginated reads
- [createReactorProvider](https://ic-reactor.b3pay.net/v3/reference/createReactorProvider.md): per-request reactors for server-rendered React apps
- [createAuthHooks](https://ic-reactor.b3pay.net/v3/reference/createAuthHooks/overview.md): `useAuth`, `useUserPrincipal`, `useAgentState`
- [Utilities](https://ic-reactor.b3pay.net/v3/reference/Utilities.md): `formatTokenAmount`, `parseTokenAmount`, `isPrincipalText`, `jsonToString`
- [Validation](https://ic-reactor.b3pay.net/v3/reference/ReactValidation.md): helpers that map a `ValidationError` onto form fields
- [Testing kit](https://ic-reactor.b3pay.net/v3/reference/testing.md): `installFakeReplica` and `createTestCanister`

## Packages

- [@ic-reactor/core](https://ic-reactor.b3pay.net/v3/packages/core.md): framework-agnostic runtime; no React
- [@ic-reactor/react](https://ic-reactor.b3pay.net/v3/packages/react.md): hooks, factories, `defineReactor`, auth; re-exports core
- [@ic-reactor/candid](https://ic-reactor.b3pay.net/v3/packages/candid.md): reactors for canisters whose Candid is only known at run time
- [@ic-reactor/parser](https://ic-reactor.b3pay.net/v3/packages/parser.md): WASM Candid parser (`didToJs`, `didToTs`, `parseDid`)
- [@ic-reactor/vite-plugin](https://ic-reactor.b3pay.net/v3/packages/vite-plugin.md): generate declarations and hooks from `.did` files in Vite, with local canister ids
- [@ic-reactor/cli](https://ic-reactor.b3pay.net/v3/packages/cli.md): the `ic-reactor` command for non-Vite projects and CI
- [@ic-reactor/codegen](https://ic-reactor.b3pay.net/v3/packages/codegen.md): the generation pipeline behind the CLI and the Vite plugin

## Examples

- [Next.js App Router](https://ic-reactor.b3pay.net/v3/examples/nextjs-app-router.md): `createReactorProvider`, a server component, several tokens with `forCanister`
- [TanStack Router](https://ic-reactor.b3pay.net/v3/examples/tanstack-router.md): query objects fetched in route loaders and read with `.useQuery()`
- [Codegen in Action](https://ic-reactor.b3pay.net/v3/examples/codegen-in-action.md): CLI and Vite plugin output, including `factories: true`
- [Multiple Canisters](https://ic-reactor.b3pay.net/v3/examples/multiple-canister.md): several reactors sharing one `ClientManager` and sign-in
- [ckBTC Wallet](https://ic-reactor.b3pay.net/v3/examples/ckbtc-wallet.md): ICRC-1 balances and transfers, ckBTC minter calls, exact token amounts

## Optional

- [Full guide](https://ic-reactor.b3pay.net/llms-full.txt): every rule and snippet in one file
- [Changelog](https://github.com/B3Pay/ic-reactor/blob/main/CHANGELOG.md): per-package changes, with migration hints
- [Why IC Reactor](https://ic-reactor.b3pay.net/v3/getting-started/why-ic-reactor.md): what it adds over a raw `Actor`
- [useActorSuspenseQuery](https://ic-reactor.b3pay.net/v3/reference/createActorHooks/useActorSuspenseQuery.md): suspense variant of the query hook
- [useActorInfiniteQuery](https://ic-reactor.b3pay.net/v3/reference/createActorHooks/useActorInfiniteQuery.md): paginated query hook
- [CandidReactor](https://ic-reactor.b3pay.net/v3/packages/candid/candidreactor.md): dynamic calls from a Candid source fetched at run time
- [MetadataReactor](https://ic-reactor.b3pay.net/v3/packages/candid/metadatareactor.md): form and result metadata generated from Candid
- [Parser reference](https://ic-reactor.b3pay.net/v3/packages/parser/reference.md): parser functions and the names it renames
- [All examples](https://ic-reactor.b3pay.net/v3/examples.md): every example app, with StackBlitz links
- [AI Friendliness](https://ic-reactor.b3pay.net/v3/guides/ai-friendliness.md): how to point an agent at these files, install the agent skill, and a snippet for your own AGENTS.md
- [Agent skill](https://github.com/B3Pay/ic-reactor/tree/main/skill-packages/ic-reactor): the `ic-reactor` skill; in Claude Code `/plugin marketplace add B3Pay/ic-reactor` then `/plugin install ic-reactor@ic-reactor`, elsewhere `npx skills add B3Pay/ic-reactor --skill ic-reactor`
- [Source](https://github.com/B3Pay/ic-reactor): the monorepo; contributors start at its AGENTS.md