IC Reactor

ic-reactor 4 is a thin layer over a module that candid-core-cli gen generates from a .did file. The layer is a client with caller-scoped query keys, one error type that says whether a call may have executed, helpers for token units, a test client over an in-memory replica, and a React provider with useAuth. Reading and writing use TanStack Query’s own hooks.

import { createClient } from "@ic-reactor/core"
import { actor, type Actor } from "./generated/icrc1"

const client = createClient({ network: "ic", identity: "anonymous" })
const ledger = client.canister<Actor>(actor, {
  id: "ryjl3-tyaaa-aaaaa-aaaba-cai",
})

console.log(await ledger.icrc1_symbol()) // "ICP"

Status

ic-reactor 4 is the current release, published under npm’s latest dist-tag: npm install @ic-reactor/core installs it. The code is developed on the main branch.

These pages describe what is built on main and nothing else. The one guide that ships in the package, node_modules/@ic-reactor/core/llms.txt, is for people and coding agents alike, and these pages agree with it.

Coming from 3.x? Start with Migrating from 3.x: the 3.x names are gone, and that page maps each one to its 4 replacement.

Start here

Getting startedInstall, generate the module, make a first read and write

ExamplesFive apps: a ledger explorer, a Next.js app, a wallet, a Node tool and a studio for any canister

Migrating from 3.xThe 34 removed names and what replaces them

Guides

In reading order.

The clientNetworks, identity or auth, canisters, dispose, one client per request

Values and unitsCandid values in TypeScript, principals, parseUnits and formatUnits

ReadsqueryOptions, keys, certified reads, retries, suspense, infinite queries

WritesmutationOptions, invalidation, and when an update is sent again

Errors and mayHaveExecutedReactorError, its kinds and codes, and what to do for each

AuthSign in and out, AuthLike, useAuth, identity attributes

SSR and hydrationNext.js App Router, a client per request, dehydrate and hydrate

TestingcreateTestClient: a fake replica, refused requests, test sign-in

The Vite pluginGeneration, the ic_env cookie and the /api proxy

Packages

@ic-reactor/coreThe client, ReactorError, the units helpers, and the test client

@ic-reactor/reactReactorProvider, useClient and useAuth

@ic-reactor/vite-pluginGenerates the module and sets up the local environment

The API reference in the sidebar is generated from the main branch as it stands, which can be ahead of the latest release.