🚀 IC Reactor v3: The Production-Ready Data Fetching Library for the Internet Computer

Developers JavaScript
, ,
1

Hi everyone! :waving_hand:

Following our beta announcement, I am thrilled to announce that IC Reactor v3 is now officially stable and released! :rocket:

If you are building frontends on the Internet Computer, you know the struggle: manually managing agent state, writing endless boilerplates to unwrap Result types, handling BigInt/Variant serialization for the UI, and trying to implement caching without reinventing the wheel.

IC Reactor v3 solves this by combining the power of the ICP SDK with TanStack Query (React Query), giving you a production-grade data fetching layer specifically designed for the IC.

:glowing_star: What makes v3 special?

We’ve spent the beta period polishing APIs, improving test coverage, and refining the developer experience. v3 is not just a wrapper; it’s a complete toolkit for building robust dApps.

1. :brain: TanStack Query Integration (The “Brain”)

Stop managing isLoading and isError states manually. Get automatic caching, background refetching, deduplication, and optimistic updates for your canister calls right out of the box.

2. :shield: TypeScript & End-to-End Type Safety

Your .did files flow directly into your React hooks. Arguments and return types are fully inferred.

  • Auto-Unwrapping: Result<T, E> is automatically unwrapped. If a canister returns Err, it throws a typed error you can catch or handle with error boundaries.

  • No more: if ('ok' in result) { ... }

3. :robot: First-Class AI Support (llms.txt)

We ship an llms.txt file in the root of our documentation. Point your AI editor (Cursor, Windsurf, etc.) to our docs, and it will instantly know how to write correct IC Reactor code.

4. :performing_arts: Dynamic Candid & Forms

Building a canister explorer or admin dashboard?

  • CandidReactor: Interact with any canister by just providing its ID. It fetches the Interface Definition (IDL) on the fly.

  • Dynamic Forms: We provide visitors that generate form schemas and validation logic directly from Candid definitions.

5. :test_tube: Experimental: Zero-Config Environment

We are abstracting away the complexity of environment configuration. You can now initialize your Reactor with just the canister name, and we handle the rest!

By enabling withCanisterEnv in your ClientManager, ic-reactor automatically detects:

  • Canister IDs: Resolves canisterId dynamically from the environment (e.g., PUBLIC_CANISTER_ID:my_canister).

  • Network Settings: Auto-configures host, root keys, and query signature verification based on your environment (dev vs. prod).

  • Internet Identity: Automatically finds the Internet Identity canister ID.

// 1. Enable environment detection
const clientManager = new ClientManager({
  withCanisterEnv: true,
})

// 2. Initialize with just the name!
const reactor = new Reactor({
  name: "my_canister", // Auto-resolves canisterId!
  clientManager,
})

This delivers complex environment handling out-of-the-box, so you can focus on building your app.

:package: Installation

We are officially out of beta! You don’t need the @beta tag anymore.

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

# For backend/Node.js/Svelte/Vue logic
pnpm add @ic-reactor/core @icp-sdk/core @tanstack/query-core

:building_construction: Live Demo

Check out B3Forge, our latest tool built entirely with IC Reactor v3! It showcases dynamic canister interactions, shareable playgrounds, and AI-powered app building.

:hammer_and_wrench: Quick Example

Here is how simple it is to query a canister with full caching and type safety:

import { createActorHooks } from "@ic-reactor/react"
import { canisterId, idlFactory } from "./declarations/my_canister"

// 1. Initialize
const { useActorQuery } = createActorHooks({ canisterId, idlFactory })

function UserProfile({ userId }) {
  // 2. Use the hook (caches the result automatically!)
  const { data, isPending, error } = useActorQuery({
    functionName: "get_user_profile",
    args: [userId],
  })

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

  return <div>Welcome, {data.name}!</div>
}

:books: Resources

A huge thank you to everyone who tested the beta and provided feedback. We can’t wait to see what you build with v3!

Happy coding! :rocket:

3 Likes
Icp-cli announcements and feedback discussion
2

Quick follow-up for everyone building with ic-reactor v3: I just shipped a new AI-ready workflow to make onboarding much easier in your next project.

New AI/Agent Skills (Now in a Separate Skills Repo)

I extracted the IC Reactor skills into a dedicated mono-repo so they’re easier to install and reuse across projects:

I also improved the main ic-reactor repo’s AI guidance so tools like Codex / Copilot / Cursor can generate better IC Reactor code with fewer mistakes:

  • improved llms.txt (better context for LLMs)
  • updated AI docs + contributor guidance
  • clearer guidance for hook/factory usage and cache invalidation patterns

What the ic-reactor-hooks skill helps with

It teaches agents to correctly use:

  • createActorHooks(...)
  • createQuery, createMutation, createSuspenseQuery, createInfiniteQuery
  • useActorMethod
  • cache invalidation (getQueryKey(), invalidate())
  • the difference between:
    • React hook usage inside components
    • imperative usage outside React (fetch, execute, etc.)

This is especially useful for avoiding common mistakes like calling hooks outside React.

Install the Skill (new)

If you use the skills CLI (nested skill discovery):

npx skills add B3Pay/ic-reactor-skills --full-depth --skill ic-reactor-hooks

Easiest Way to Use IC Reactor in Your Next Project

1) Install (React)

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

2) Create a shared reactor + hooks

  • Create one QueryClient
  • Create one ClientManager
  • Create your Reactor (or DisplayReactor)
  • Export hooks from createActorHooks(...)

3) For scalable apps, use codegen

  • Vite app: use @ic-reactor/vite-plugin (recommended)
  • Non-Vite / CI: use @ic-reactor/cli

This gives you generated query/mutation files that support both:

  • React usage: .useQuery(), .useMutation()
  • non-React usage: .fetch(), .execute(), .invalidate()

Pro tip (for AI-assisted dev)

If you’re using an AI editor/agent, point it to:

  • llms.txt (from the main ic-reactor repo)
  • the skills repo: B3Pay/ic-reactor-skills

And ask something like:

Use $ic-reactor-hooks to create a reusable query/mutation factory pair for my canister and show usage in both a React component and a route loader.

That produces much cleaner results now.

If people are interested, I can also share a recommended IC Reactor v3 project structure (React + generated hooks + auth + loaders) next.

1 Like
3

First off let me just say Happy B day (if the data in the forum is correct) , and thank you for all your hard work much appreciated. Hooks Skill is awesome and a good idea to have a separate repo, and also love the best practices from the llms.txt . Keep up the great work.

1 Like
4

Hey Zack,

Thank you so much for the kind words and the Happy Birthday wishes — you nailed it, the forum data is 100% correct! :grinning_face_with_smiling_eyes: That really made my day.

I’m super glad you like the Hooks Skill being in its own repo — you’re absolutely right, separating it was the right move and keeps everything cleaner for everyone (and for the AI tools too). Your feedback means a lot!

I also see how hard you’re working and pushing for the ICP ecosystem every single day. It’s seriously inspiring, man — thank you for all the effort and dedication. Keep crushing it! :rocket:

Looking forward to building more awesome stuff together.

Cheers,
Behrad

1 Like
5

image discourse has some nice features. :slight_smile:

1 Like