IC Reactor

The modern, type-safe library for building Internet Computer applications

---

IC Reactor provides seamless integration between your applications and Internet Computer canisters with full TypeScript support, intelligent caching powered by TanStack Query, and first-class React integration.

✨ Features

• 🔒 End-to-End Type Safety - From Candid to your components
• ⚡ TanStack Query Integration - Automatic caching, background refetching, optimistic updates
• 🔄 Auto Transformations - BigInt to string, Principal to text, and more with DisplayReactor
• ⚛️ React Ready - useActorQuery, useActorInfiniteQuery, useActorMutation and more
• 📦 Result Unwrapping - Automatic Ok/Err handling from Candid Result types
• 🏗️ Multi-Actor Support - Manage multiple canisters with shared authentication
• 🔐 Internet Identity - Seamless authentication integration
• 🔍 Dynamic Candid - Runtime Candid parsing for building explorers and dev tools

📦 Packages

Package	Description
@ic-reactor/core	Core library with ClientManager, Reactor, DisplayReactor, and query caching
@ic-reactor/react	React hooks for seamless integration (useActorQuery, useActorMutation, etc.)
@ic-reactor/candid	Dynamic Candid fetching, parsing, and CandidReactor / CandidDisplayReactor
@ic-reactor/parser	Local WASM-based Candid parser (offline, fast compilation)

🚀 Quick Start

Installation

# For React apps
pnpm add @ic-reactor/react@beta @icp-sdk/core @tanstack/react-query

# For non-React apps
pnpm add @ic-reactor/core@beta @icp-sdk/core @tanstack/query-core

# For dynamic Candid (optional)
pnpm add @ic-reactor/candid@beta @ic-reactor/parser

# For Internet Identity authentication (optional)
pnpm add @icp-sdk/auth

Basic Usage

import { ClientManager, Reactor, createActorHooks, createAuthHooks } from '@ic-reactor/react';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { idlFactory, type _SERVICE } from './declarations/my_canister';

// 1. Setup ClientManager (handles Identity and Agent)
const queryClient = new QueryClient();
const clientManager = new ClientManager({ queryClient, withProcessEnv: true });

// 2. Setup Reactor (handles Canister interaction)
const backend = new Reactor<_SERVICE>({
  clientManager,
  idlFactory,
  canisterId: 'rrkah-fqaaa-aaaaa-aaaaq-cai',
});

// 3. Create Hooks
const { useActorQuery, useActorMutation } = createActorHooks(backend);
const { useAuth, useUserPrincipal } = createAuthHooks(clientManager);

// 4. Use in components
function LoginButton() {
  const { login, logout, isAuthenticated, principal } = useAuth();

  return isAuthenticated ? (
    <button onClick={() => logout()}>Logout {principal?.toText()}</button>
  ) : (
    <button onClick={() => login()}>Login with Internet Identity</button>
  );
}

function Greeting() {
  const { data, isPending, error } = useActorQuery({
    functionName: 'greet',
    args: ['World'],
  });

  if (isPending) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return <h1>{data}</h1>;
}

Dynamic Candid (for Explorers & Dev Tools)

import { CandidDisplayReactor } from "@ic-reactor/candid"
import { ClientManager } from "@ic-reactor/core"

const clientManager = new ClientManager()

// Create a reactor for ANY canister - no pre-generated types needed!
const reactor = new CandidDisplayReactor({
  canisterId: "ryjl3-tyaaa-aaaaa-aaaba-cai", // ICP Ledger
  clientManager,
})

// Initialize from network (fetches Candid automatically)
await reactor.initialize()

// Call methods with display-friendly types (bigint → string)
const balance = await reactor.callMethod({
  functionName: "icrc1_balance_of",
  args: [{ owner: "aaaaa-aa" }], // Principal as string!
})

console.log(balance) // "1000000" (string, ready for UI display)

🎯 Why Reactor Instead of Actor?

Feature	Standard Actor	Reactor
Type-safe method calls	✅	✅
Query caching	❌	✅ Built-in
Automatic refetching	❌	✅ Background updates
Result unwrapping	❌ Manual	✅ Automatic
Error typing	❌ Generic	✅ CanisterError<E>
Identity sharing	❌ Per-actor	✅ Via ClientManager
Display transformations	❌	✅ DisplayReactor

🏃 Examples

Example	Description
Candid Parser	Dynamic canister calls with runtime Candid parsing
TanStack Router	Full app with routing and authentication
Codec Demo	Type transformation demonstrations
TypeScript Demo	Pure TypeScript usage (no React)

Run Documentation Locally

cd docs
pnpm install
pnpm dev

🛠️ Development

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Run tests
pnpm test

# Run E2E tests
pnpm test-e2e

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines on how to submit PRs, run the project locally, and formatting rules. Please also review our Code of Conduct.

🤖 AI/LLM Integration

This project is AI-friendly with:

• /llms.txt in documentation for structured API overview
• Clear, scannable documentation structure
• Complete, copy-pasteable code examples
• Semantic HTML and heading hierarchy

📄 License

MIT © Behrad Deylami

---

Built for the Internet Computer 🌐