IC-Reactor: A suite of JavaScript libraries for seamless frontend development on the Internet Computer platform, offering state management, React integration, and core functionalities for efficient...
Overview
Type-safe Internet Computer integration for TypeScript and React IC Reactor is a monorepo of libraries for building Internet Computer (ICP) apps with: - end-to-end TypeScript types - TanStack Query-powered caching and refetching - React hook factories (useActorQuery, useActorMutation, etc.) - display-friendly transforms (DisplayReactor) - optional code generation (CLI + Vite plugin) IC Reactor gives you a higher-level API than raw Actor usage while keeping type safety and control: - typed canister method calls - built-in cache keys and invalidation primitives - typed Ok/Err result handling - shared agent + cache management via ClientManager, with Internet Identity in AuthenticationManager - reusable query/mutation objects that work both inside and outside React What changed, per package, is in CHANGELOG.md, including the changes on main that no release carries yet.
README
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/coreand@ic-reactor/reactwith the 4 API. The 3.x line lives on thev3branch, 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_envcookie - strict token-unit helpers (
parseUnits,formatUnits) - a test client over a fake replica
'use client'React bindings: a provider,useClientanduseAuth
Package Overview
| Package | Purpose |
|---|---|
@ic-reactor/core |
The client, errors, network and units |
@ic-reactor/react |
'use client' bindings over core |
@ic-reactor/vite-plugin |
Generates the candid-core module with candid-core-cli gen in a child process, and sets the local ic_env cookie and /api proxy for vite dev |
@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
- Docs site: ic-reactor.b3pay.net/v4
(source:
./docs), and ic-reactor.b3pay.net/v3 for 3.x. - Changelog:
CHANGELOG.md - Versioning and support:
docs/src/content/docs/versioning.mdx - Package docs:
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.
Recommended Tools
Try a different keyword or remove a filter.
Install
npx skillfish add b3pay/ic-reactor