Installation

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

Prerequisites

• Node.js 18 or later for @ic-reactor/core and @ic-reactor/react; @ic-reactor/candid requires Node 20.19.0 or later (the floor of its @noble/hashes dependency), and @ic-reactor/cli requires Node 22.12.0 or later. Each package declares this in its engines field.
• 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!

Note

react is the only required React peer. react-dom is declared as an optional peer — the package never imports it — so renderers without a DOM (React Native, custom hosts) work without installing it.

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, which lives in @ic-reactor/react. It is loaded through a dynamic import(), so your bundler splits it into its own chunk instead of adding it to your main bundle. See Internet Identity below.

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

Internet Identity (@icp-sdk/auth)

Needed only if you sign users in with Internet Identity. It is an optional peer dependency of @ic-reactor/react — AuthenticationManager loads it with a dynamic import(), so nothing breaks when it is absent, but login() will not work until you install it.

@ic-reactor/react requires @icp-sdk/auth v8 (peerDependencies: "^8.0.0"). v7 is no longer supported — the compatibility shim that made it work was removed in 3.12.0.

pnpm add @icp-sdk/auth@^8

npm cannot resolve this set on its own

Every published @icp-sdk/auth, v7 and v8 alike (through 8.0.3, checked 2026-08-22), declares peerDependencies: { "@icp-sdk/core": "^5" }, while @ic-reactor/react needs @icp-sdk/core@^6. A strict npm install of the advertised set therefore fails:

npm error ERESOLVE unable to resolve dependency tree
npm error Found: @icp-sdk/[email protected]
npm error   peer @icp-sdk/core@"^5" from @icp-sdk/[email protected]
npm error Could not resolve dependency:
npm error   peer @icp-sdk/core@"^6.0.0" from @ic-reactor/react

This is stale metadata upstream, not an actual incompatibility: auth v8 works against core v6, and IC Reactor’s own suite runs that combination. pnpm and yarn install it without complaint. For npm, tell it to use your core for auth as well:

package.json

{
  "overrides": {
    "@icp-sdk/auth": {
      "@icp-sdk/core": "$@icp-sdk/core"
    }
  }
}

That resolves to a single @icp-sdk/core with no duplication. legacy-peer-deps=true in .npmrc also works but disables peer checking everywhere, so prefer the scoped override. This note goes away once @icp-sdk/auth publishes a core@^6 peer.

Bundlers still resolve that specifier while building the module graph, which happens before any tree-shaking — so a missing peer cannot simply be optimized away. The import sits inside a try block, which webpack-family bundlers treat as declaring an optional dependency: with the peer absent the build succeeds and prints one warning, Module not found: Can't resolve '@icp-sdk/auth/client'. Only the login paths are affected, and they throw an actionable error if they are ever called.

Install the peer to remove the warning, or silence it with ignoreWarnings:

webpack.config.js

module.exports = {
  ignoreWarnings: [{ module: /@ic-reactor\/react/, message: /@icp-sdk\/auth/ }],
}

// next.config.js — ignoreWarnings only takes effect inside webpack()
module.exports = {
  webpack: (config) => {
    config.ignoreWarnings = [
      { module: /@ic-reactor\/react/, message: /@icp-sdk\/auth/ },
    ]
    return config
  },
}

The optional-try treatment is webpack-specific — other bundlers may refuse to resolve the missing specifier at build time. If yours does, install the peer, or construct the AuthClient yourself and pass it as authClient to AuthenticationManager, in which case IC Reactor never imports @icp-sdk/auth at all.

With the peer installed, the auth module is code-split into its own async chunk. That chunk is never fetched unless something touches authentication, and its bytes are dropped from the output entirely in apps that never reference AuthenticationManager.

Read more about Authentication

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

With @ic-reactor/vite-plugin or @ic-reactor/cli, every canister gets its own folder under the output directory (default src/declarations):

• declarations/<did-basename>.js with the idlFactory
• declarations/<did-basename>.d.ts service types
• declarations/<did-basename>.did a copy of the source .did
• index.generated.ts — the managed reactor (plus React hooks when target: "react"); regenerated on every run
• index.ts — a stable wrapper that re-exports the generated file and is safe to customize

dfx generate and @icp-sdk/bindgen use their own layout, typically an index.js factory plus a <canister>.did.d.ts service type.

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!