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

📦 Packages

Package	Description
@ic-reactor/core	Core library with ClientManager, Reactor, and query caching
@ic-reactor/react	React hooks for seamless integration (re-exports core)

🚀 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

# Optional: Internet Identity authentication
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>;
}

🎯 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

Run Documentation Locally

cd docs
pnpm install
pnpm dev

🏃 Examples

Example	Description
TanStack Router	Full app with routing and authentication
Codec Demo	Type transformation demonstrations
TypeScript Demo	Pure TypeScript usage

🛠️ 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 🌐