IC Reactor 4

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 a prerelease. Its betas are published under npm’s beta dist-tag, and latest is still 3.x until 4.0 GA. Install it as @ic-reactor/core@beta, never bare. The code is developed on the v4 branch.

These pages describe what is built on v4 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

ExamplesFour small apps: a ledger explorer, a Next.js app, a wallet and a Node tool

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 v4 branch as it stands.