IC Reactor
ic-reactor 4 is the current release. It is a thin layer over a
candid-core generated module, with a guide shipped in @ic-reactor/core
(packages/core/llms.txt), and it replaced the 3.x runtime of
@ic-reactor/core and @ic-reactor/react with the 4 API. The 3.x line lives
on the v3 branch, takes
security fixes only, until 90 days after the 4.0 release, and is documented
at ic-reactor.b3pay.net/v3.
IC Reactor is a monorepo of libraries for building Internet Computer (ICP) apps
in TypeScript. ic-reactor 4 adds, over the module candid-core-cli gen writes
for a canister:
- a client with caller-scoped query keys, for TanStack Query
- one error union that says whether a failed call may have executed
- network resolution: mainnet, a local replica, or the
ic_env cookie
- strict token-unit helpers (
parseUnits, formatUnits)
- a test client over a fake replica
'use client' React bindings: a provider, useClient and useAuth
Package Overview
@ic-reactor/parser, @ic-reactor/codegen and @ic-reactor/cli are not part
of ic-reactor 4: candid-core-cli gen generates the canister module instead.
@ic-reactor/candid stays at 3.x, published from the v3 branch. None of the
four is in this branch's tree.
What changed, per package, is in CHANGELOG.md. What a 4.x
release may change, and the oldest Node, TypeScript, React, TanStack Query,
Vite and @icp-sdk/core supported, is in
Versioning and support.
Install
Install the packages, and the candid-core packages at the exact versions their
peers name:
npm install @ic-reactor/core @ic-reactor/react \
@icp-sdk/core @tanstack/react-query
npm install --save-exact @candid-core/[email protected]
npm install --save-dev --save-exact @candid-core/[email protected]
npm install --save-dev @ic-reactor/vite-plugin # optional, for Vite
Then read node_modules/@ic-reactor/core/llms.txt. The released 3.x packages
are documented at ic-reactor.b3pay.net/v3.
Examples
Five apps in examples/, each with its own tests, and a page in
the examples docs:
icrc-ledger: mainnet ICP ledger reads, archive
callbacks, and a sandbox that injects faults into transfers.vite-wallet: a React and Vite wallet on a local
icp-cli network, with Internet Identity, a dev-account sign-in, a backend
canister and optimistic writes.next-ssr: a Next.js App Router app over mainnet
ledgers, with one client per request, lossless hydration and streaming.node-agent-tool: a command-line tool for
people and AI agents, with identities, certified reads, safe re-sends and
JSON output.canister-studio: a TanStack Start app that
gives every method of any mainnet canister an automatic form, with
interfaces read live from certified metadata, server-rendered reads and
shared query links, confirmed writes, and a safety lab.
The 3.x examples are on the v3 branch.
Documentation
Run docs locally:
cd docs
pnpm install
pnpm dev
Development
# Install dependencies
pnpm install
# Build packages
pnpm build
# Run package tests
pnpm test
# Lint packages/*/src and packages/*/tests (CI gate; run after pnpm build)
pnpm lint
# Type-check every package and e2e/, including their tests (CI gate)
pnpm typecheck
# Check formatting (CI gate; covers the whole repo)
pnpm format:check
# Check versions, package stamps and docs links in the AI guides (CI gate)
pnpm check:ai-context
# Pack, install outside the workspace, and verify the published artifacts
# (real Node import + publint + attw)
pnpm verify:packages
# Run e2e tests
pnpm test-e2e
# Build docs
pnpm docs:build
AI and Agent Integration
ic-reactor 4 ships one consumer guide, llms.txt in @ic-reactor/core's
package (node_modules/@ic-reactor/core/llms.txt), and one consumer skill,
skill-packages/ic-reactor, which
points at it. The 3.x guides and skills are on the v3 branch.
For agents working in this repository: AGENTS.md and
CLAUDE.md.
Contributing
main is the development line of ic-reactor 4; v3 takes 3.x security fixes
only, until 90 days after the 4.0 release. See CONTRIBUTING.md for development workflow, formatting, release notes, and AI-assisted contribution guidance.
Please also review the Code of Conduct.
License
MIT © Behrad Deylami. See LICENSE.
