[v3 Beta Announcement] IC Reactor: The "Missing" Data-Fetching Library for Internet Computer

b3hr4d · January 4, 2026, 2:01pm

Hi everyone!

I’m excited to announce the v3 Beta of IC Reactor — a modern, type-safe library designed to solve the “frontend boilerplate” when building on the Internet Computer.

If you’ve ever found yourself manually managing actors queries and mutations, handling forms, writing endless if ('ok' in result) checks to unwrap Candid variants, or trying to figure out how to cache canister responses without reinventing the wheel, IC Reactor is for you.

The Concept: TanStack Query for the IC

Rather than building another meta-framework, IC Reactor is built directly on top of TanStack Query (formerly React Query). This means you get production-grade caching, background refetching, and optimistic updates out of the box, but specifically tailored for IC canisters.

Key Features in v3

Automatic Result Unwrapping (The Pain Killer): Say goodbye to manually checking Ok vs Err variants. IC Reactor automatically unwraps Result<T, E> types. If the canister returns an Err, it’s thrown as a typed CanisterError, allowing you to use standard try/catch or hook-level error states.
End-to-End Type Safety: Your Candid definitions flow directly into your React hooks. Complete autocomplete and type checking from .did to UI.
Auto Transformations (DisplayReactor): Automatically handles display-ready types (BigInt → string, Principal → text, etc.) so your UI logic stays clean.
Power Hooks: Intuitive useActorQuery, useActorMutation, and useActorInfiniteQuery (perfect for paginated lists).
Seamless Auth: Built-in support for Internet Identity via createAuthHooks.
AI-Friendly: Includes a structured llms.txt and Cursor rules to help AI assistants write better code for your project.

Why use Reactor instead of a standard Actor?

Feature	Standard Actor	IC Reactor
Type-safe methods
Result Unwrapping	Manual	Automatic
Error Handling	Generic	CanisterError
Query Caching		Built-in
Background Refetching		Automatic
Identity Sharing	Per-actor	Shared Manager

Quick Look

// Candid: get_user_profile : (text) -> (variant { Ok : UserProfile; Err : text }) query;
// No more 'if (ok in result)' boilerplate!
const { data, error, isError } = useActorQuery({
  functionName: "get_user_profile",
  args: [userId],
});

if (isError) {
  // error is a typed CanisterError if the canister returned an Err variant
  console.error("Canister said no:", error.err); 
}

Try the Demos!

We have several live examples in the repository that showcase these features in action:

ICRC Wallet: A simple example of using IC Reactor with TanStack Router.
ckBTC Wallet: A simple example of using IC Reactor with ckBTC.
Codec Demo: See how new codec works.
Multi-Canister Demo: Managing multiple actors with one identity.

We need your feedback!

We are currently in v3.0.0-beta. The core API is stable, but we want to hear from devs building real-world DApps. If you’re tired of the manual boilerplate, please give it a spin!

We want to know:

Does the DisplayReactor simplify your UI code?
How is the experience of managing multiple canisters?
What are we missing to make this your go-to library for every IC project?

Links:

Documentation (v3)
GitHub Give it a star!

npm add @ic-reactor/react@beta @icp-sdk/core @tanstack/react-query

Special thanks to the @icp-sdk team (@ilbert, @peterparker) for their tireless work on a clean, type-safe SDK that powers IC Reactor.

Ajki · January 4, 2026, 2:30pm

Fantastic work, well done.

sea-snake · January 5, 2026, 11:58am

Will definitely have a look how this has been implemented, we’re doing something similar in II (.then(throwCanisterError) utility fn).

b3hr4d · January 5, 2026, 12:05pm

How it works internally in ic-reactor:

github.com/B3Pay/ic-reactor

packages/core/src/utils/helper.ts

8fe6ae0df


      
          export function extractOkResult<T>(result: T): OkResult<T> {
            if (!result || typeof result !== "object") {
              // Non-object, return as-is
              return result as OkResult<T>
            }
          
            // Handle { Ok: T } (Rust convention)
            if ("Ok" in result) {
              return result.Ok as OkResult<T>
            }
            // Handle { ok: T } (Motoko convention)
            if ("ok" in result) {
              return result.ok as OkResult<T>
            }
          
            // Handle { Err: E } (Rust convention) - throw CanisterError
            if ("Err" in result) {
              throw new CanisterError(result.Err)
            }
            // Handle { err: E } (Motoko convention) - throw CanisterError

This file has been truncated. show original

b3hr4d · January 5, 2026, 5:50pm

Here is a quick demo video I put together to show ic-reactor v3 in action!

In this video, I demonstrate one of my favorite features: Optimistic UI with Automatic Rollback.

We all know the Internet Computer is fast (approx. 2s finality), but for a modern web experience, users expect instant feedback.

In the demo, you’ll see:

Instant Updates: Clicking “Like” updates the UI immediately (0 latency).
Chaos Mode: I simulate a canister failure (rejection), and the library automatically rolls back the state to its previous value. No complex error handling code required!

Check it out below:

Source code: ic-reactor/examples/all-in-one-demo at main · B3Pay/ic-reactor · GitHub
Related X post: https://x.com/b3hr4d_dev/status/2008232482177528092

Let me know what you think!

marceljuenemann · January 5, 2026, 7:12pm

This is cool, I’m definitely annoyed by ‘ok’ in result already I see TanStack has Angular integration as well, so might give that a try at some point

Ajki · January 5, 2026, 7:22pm

This is critical for competing with Web2. Users do not care (yet) whether something is onchain (unfortunately) , they just expect instant Web2 UX speed. Truly great work.

b3hr4d · January 5, 2026, 7:34pm

Interesting, Let me know if you have any issues with Angular integration.

b3hr4d · January 5, 2026, 7:38pm

Thank you so much – really appreciate your help getting me more visibility on X!

Ajki · January 5, 2026, 7:42pm

You deserve the praise. I only wish more of the ICP community on X focused on promoting solutions instead of obsessing over token price.

b3hr4d · January 6, 2026, 11:32am

Here is Part 2 of the demo series!

In this video, I dive into Advanced Data Fetching.

One common challenge on the IC is handling mixed latency. If your app calls multiple canisters—and one is slower or under load—it can often freeze the user experience.

What you’ll see in the video:

Suspense Queries: I simulating a slow network response using DevTools. You’ll see how createSuspenseQuery allows the rest of the app to remain strictly interactive while the specific data loads (showing a skeleton state).
Infinite Scrolling: A walkthrough of createInfiniteQuery to handle large datasets with pagination, making it feel just like a standard web2 app.

Watch it here:

Source code: ic-reactor/examples/all-in-one-demo at main · B3Pay/ic-reactor · GitHub
Related X post: https://x.com/b3hr4d_dev/status/2008500787010502821

Feedback is welcome!

b3hr4d · January 7, 2026, 4:46pm

I’m excited to share a major addition to the library: Dynamic Candid Support.

We realized that while type-safety is amazing for your own canisters, sometimes you need to interact with 3rd-party canisters, build explorers, or create generic tools like B3Forge Playground where you don’t have the IDL files at compile time.

We’ve added a new package @ic-reactor/candid that lets you do exactly that.

1. Dynamic Actor Creation

You can now initialize a reactor by simply providing the Candid string (or letting it fetch from the network automatically).

import { CandidReactor } from "@ic-reactor/candid"

// Option A: Fetch IDL from the network automatically
const reactor = new CandidReactor({
  canisterId: "ryjl3-tyaaa-aaaaa-aaaba-cai", // ICP Ledger
  clientManager,
})
await reactor.initialize()

// Option B: Provide Candid string directly
const reactor = new CandidReactor({
  canisterId: "ryjl3-tyaaa-aaaaa-aaaba-cai",
  clientManager,
  candid: `service : {
    icrc1_balance_of : (record { owner : principal }) -> (nat) query;
  }`,
})
await reactor.initialize()

Once initialized, all standard Reactor features work automatically—including TanStack Query caching (fetchQuery), hooks, and type safety (generic types).

2. One-Shot Dynamic Calls

If you just need to make a single call without setting up a full reactor, we added “One-Shot” methods. These register the method signature on-the-fly and execute the call in one step.

Query with caching (TanStack Query):

const balance = await reactor.fetchQueryDynamic({
  functionName: "icrc1_balance_of",
  candid: "(record { owner : principal }) -> (nat) query",
  args: [{ owner: Principal.fromText("...") }],
})

Direct Query:

const symbol = await reactor.queryDynamic({
  functionName: "icrc1_symbol",
  candid: "() -> (text) query",
})

Update Call:

const result = await reactor.callDynamic({
  functionName: "transfer",
  candid:
    "(record { to : principal; amount : nat }) -> (variant { Ok : nat; Err : text })",
  args: [{ to: recipient, amount: 100n }],
})

Why this matters

This completely removes the need for didc or code generation steps when building generic tools or quick scripts. You can literally just paste a Candid signature string and start interacting with the blockchain.

The documentation for these new packages is now live:
https://b3pay.github.io/ic-reactor/v3/packages/candid/

We’d love to hear your thoughts on this approach!

Topic		Replies	Views
🚀 IC Reactor v3: The Production-Ready Data Fetching Library for the Internet Computer JavaScript TypeScript , Frontend , ic-reactor	4	117	February 25, 2026
Introduction @ic-reactor/react for React Developers Showcase Discussing	38	1613	July 28, 2025
Introducing @ic-reactor/core: Streamline Your Development on the Internet Computer Showcase Discussing	6	556	July 18, 2024
ICP JS SDK 3 support for ic-use-internet-identity and ic-use-actor Developers	0	100	August 6, 2025
Announcing ic-use-actor – A React Hook to simplify communicating with canisters Showcase	6	945	June 7, 2024