Installation

IC Reactor is compatible with React 18+, and works with TypeScript 5+.

Prerequisites

• Node.js 18 or later
• A package manager: npm, yarn, pnpm, or bun

Install Packages

Most users will want the React package, which includes everything you need:

pnpm

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

npm

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

yarn

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

bun

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

Tip

@ic-reactor/react re-exports everything from @ic-reactor/core, so you only need one import for everything!

Non-React Projects (Node.js, Svelte, Vue, etc.)

If you’re not using React, install the core package directly:

pnpm

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

npm

npm install @ic-reactor/core @icp-sdk/core @tanstack/query-core

yarn

yarn add @ic-reactor/core @icp-sdk/core @tanstack/query-core

bun

bun add @ic-reactor/core @icp-sdk/core @tanstack/query-core

Note

The @icp-sdk/auth package is optional and only needed for Internet Identity authentication. It’s dynamically imported when needed, so it won’t increase your bundle size if you don’t use it.

Optional Tooling

Make your development easier with our tooling packages:

Vite Plugin

If you use Vite, this plugin automates code generation and provides zero-config proxy setup.

pnpm add -D @ic-reactor/vite-plugin

Read more about Vite Plugin

CLI

For other frameworks or manual control, use the CLI to generate hooks and declarations.

pnpm add -D @ic-reactor/cli

Read more about CLI

Package Overview

Package	Purpose	For React	For Non-React
@ic-reactor/react	React hooks + re-exports core	✅	❌
@ic-reactor/core	Core: Reactor, ClientManager, utilities	included	✅
@icp-sdk/core	IC SDK for agents and Candid	✅	✅
@tanstack/react-query	TanStack Query for React	✅	❌
@tanstack/query-core	TanStack Query core (caching engine)	included	✅
@icp-sdk/auth	Internet Identity authentication	Optional	Optional

✅ Required • included means it comes with the parent package • Optional for specific features

TypeScript Configuration

IC Reactor is written in TypeScript and provides first-class type support. Ensure your tsconfig.json includes:

{
  "compilerOptions": {
    "strict": true,
    "moduleResolution": "bundler",
    "esModuleInterop": true,
    "skipLibCheck": true,
    "target": "ES2020",
    "lib": ["ES2020", "DOM", "DOM.Iterable"]
  }
}

Note

Setting strict: true is highly recommended to get the full benefit of IC Reactor’s type safety.

Generate Declarations

IC Reactor needs generated canister declarations for end-to-end type safety. You can supply them in three ways:

1. Recommended for Vite: use @ic-reactor/vite-plugin
2. Recommended for non-Vite or CI: use @ic-reactor/cli
3. Manual or existing workflow: keep using your existing generator such as dfx generate or @icp-sdk/bindgen

The generated files typically include:

• index.js or <canister>.js with the idlFactory
• <canister>.did.d.ts service types
• an optional generated index.ts reactor entrypoint when you use IC Reactor tooling

Note

If you use @ic-reactor/vite-plugin or @ic-reactor/cli, you do not need a separate dfx generate step for the IC Reactor output.

Verify Installation

Create a simple test to verify everything is working:

import { ClientManager, Reactor } from "@ic-reactor/react"
import { QueryClient } from "@tanstack/react-query"

const queryClient = new QueryClient()
const clientManager = new ClientManager({ queryClient })

console.log("IC Reactor installed successfully!")
console.log("Network:", clientManager.network)

Bundler Configuration

Vite

No additional configuration needed for Vite. Just ensure you have the required polyfills:

vite.config.ts

import { defineConfig } from "vite"

export default defineConfig({
  define: {
    global: "globalThis",
  },
  optimizeDeps: {
    esbuildOptions: {
      define: {
        global: "globalThis",
      },
    },
  },
})

Next.js

For Next.js apps, add to next.config.js:

/** @type {import('next').NextConfig} */
const nextConfig = {
  webpack: (config) => {
    config.resolve.fallback = {
      ...config.resolve.fallback,
      fs: false,
      net: false,
      tls: false,
    }
    return config
  },
}

module.exports = nextConfig

Next Steps

Now that you have IC Reactor installed, continue to the Quick Start guide to build your first integration!