Overview

IC Reactor is often described as the missing data-fetching library for Internet Computer applications, but in more technical terms, it makes fetching, caching, synchronizing and updating canister state in your web applications a breeze.

Motivation

Most blockchain SDKs do not come with an opinionated way of fetching or updating data in a holistic way. Because of this, developers end up building either meta-frameworks which encapsulate strict opinions about data-fetching, or they invent their own ways of fetching data. This usually means cobbling together component-based state and side-effects, or using more general purpose state management libraries to store and provide asynchronous data throughout their apps.

While most traditional state management libraries are great for working with client state, they are not so great at working with async or server state. This is because canister state is totally different. For starters, canister state:

• Is persisted remotely in a decentralized network you may not control
• Requires asynchronous APIs for fetching and updating
• Implies shared ownership and can be changed by other users without your knowledge
• Can potentially become “out of date” in your applications if you’re not careful

Once you grasp the nature of canister state in your application, even more challenges will arise as you go, for example:

• Caching (possibly the hardest thing to do in programming)
• Deduping multiple requests for the same data into a single request
• Updating “out of date” data in the background
• Knowing when data is “out of date”
• Reflecting updates to data as quickly as possible
• Performance optimizations like pagination and lazy loading data
• Managing memory and garbage collection of canister state
• Memoizing query results with structural sharing

If you’re not overwhelmed by that list, then that must mean that you’ve probably solved all of your canister state problems already and deserve an award. However, if you are like the vast majority of people, you either have yet to tackle all or most of these challenges — and we’re only scratching the surface!

Built on TanStack Query

Rather than reinventing the wheel, IC Reactor is built on top of TanStack Query (formerly React Query) — the industry-standard library for server state management with 47K+ GitHub stars and used by companies like Google, PayPal, Walmart, and Microsoft.

Tip

If you’re already familiar with TanStack Query, you’ll feel right at home with IC Reactor. All the patterns you know — useQuery, useMutation, queryClient.invalidateQueries() — work exactly the same way.

Why TanStack Query?

TanStack Query has already solved all the hard problems of server state management:

Challenge	TanStack Query Solution
Caching	Automatic with configurable staleTime and gcTime
Request deduplication	Built-in — multiple components requesting same data = 1 network request
Background refetching	Automatic on window focus, reconnect, or interval
Optimistic updates	First-class support with rollback on failure
Pagination / Infinite scroll	useInfiniteQuery with cursor management
Retry logic	Configurable retries with exponential backoff
Devtools	Chrome extension for debugging cache state

IC Reactor takes all of this and adds the Internet Computer layer:

• Candid type safety — Full TypeScript from your .did file to your components
• Agent integration — Automatic agent.query() and agent.call() handling
• Result unwrapping — variant { Ok: T; Err: E } becomes try/catch with typed errors
• Display transformations — BigInt → string, Principal → text, opt → nullable

The Best of Both Worlds

// IC Reactor gives you TanStack Query powers for IC canisters
const { data, isPending, refetch } = useActorQuery({
  functionName: "getBalance",
  args: [principal],
  staleTime: 30_000, // TanStack Query option
  refetchInterval: 60_000, // TanStack Query option
})

// Invalidate after mutations — just like TanStack Query
const { mutate } = useActorMutation({
  functionName: "transfer",
  invalidateQueries: [backend.generateQueryKey({ functionName: "getBalance" })],
})

Note

IC Reactor doesn’t lock you in. You can use any TanStack Query feature directly — custom queryFn, select transformations, placeholderData, suspense mode, and more.

IC Reactor Will Likely:

• Help you remove many lines of complicated and misunderstood code from your application and replace them with just a handful of lines of IC Reactor logic
• Make your application more maintainable and easier to build new features without worrying about wiring up new canister state data sources
• Have a direct impact on your end-users by making your application feel faster and more responsive than ever before
• Potentially help you save on bandwidth and increase memory performance

Enough talk, show me some code already!

In the example below, you can see IC Reactor in its most basic and simple form being used to fetch data from a canister:

import { ClientManager, Reactor } from "@ic-reactor/react"
import { createActorHooks } from "@ic-reactor/react"
import { QueryClient, QueryClientProvider } from "@tanstack/react-query"
import { idlFactory, type _SERVICE } from "./declarations/backend"

// 1. Create the client
const queryClient = new QueryClient()
const clientManager = new ClientManager({ queryClient })

const backend = new Reactor<_SERVICE>({
  clientManager,
  idlFactory,
  canisterId: "rrkah-fqaaa-aaaaa-aaaaq-cai",
})

// 2. Create hooks
const { useActorQuery, useActorMutation } = createActorHooks(backend)

// 3. Wrap your app in QueryClientProvider (Optional)
// Required only if you want to use DevTools or other TanStack Query features
export default function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <Example />
    </QueryClientProvider>
  )
}

// 4. Use in your components
function Example() {
  const { isPending, error, data } = useActorQuery({
    functionName: "greet",
    args: ["World"],
  })

  if (isPending) return "Loading..."

  if (error) return "An error has occurred: " + error.message

  return (
    <div>
      <h1>{data}</h1>
    </div>
  )
}

Core Concepts

This code snippet illustrates the 3 core concepts of IC Reactor:

Queries Fetch data from canisters with automatic caching and background updates

Mutations Update canister state and automatically sync with your UI

Query Invalidation Control when and how cached data is refreshed

You talked me into it, so what now?

Installation Get IC Reactor set up in your project

Quick Start Build your first IC Reactor integration

React Setup Complete React configuration with authentication

Type Safety Understand the end-to-end type system

Packages

Package	Description	NPM
@ic-reactor/core	Core library with ClientManager, Reactor, and caching
@ic-reactor/react	React hooks for seamless integration
@ic-reactor/candid	Dynamic Candid fetching and parsing
@ic-reactor/parser	WASM Candid parser for local compilation

Note

Looking for v2 documentation? The legacy docs are available at b3pay.github.io/ic-reactor.

Why IC Reactor?

🔒 Type-Safe

End-to-end TypeScript from Candid to components

⚡ TanStack Query

Industry-standard caching engine with 47K+ GitHub stars

🔄 Auto Transforms

BigInt to string, Principal to text, Result unwrapping

🔐 Auth Built-in

Seamless Internet Identity integration

Learn More About TanStack Query

If you’re new to TanStack Query, these resources will help:

• TanStack Query Documentation — Official docs
• TanStack Query DevTools — Debug your cache
• Practical React Query — Excellent blog series by TkDodo

Tip

The concepts you learn from TanStack Query apply directly to IC Reactor. Time invested learning TanStack Query is time well spent!