@ic-reactor/cli

The IC Reactor CLI (@ic-reactor/cli) helps you generate typed reactor files, optional React hooks, and TypeScript declarations from your Candid files. It’s useful if you’re not using Vite or want more control over the generation process.

It uses the shared @ic-reactor/codegen pipeline, so its output stays aligned with the Vite plugin.

Installation

bash pnpm add -D @ic-reactor/cli

bash npm install -D @ic-reactor/cli

bash yarn add -D @ic-reactor/cli

bash bun add -D @ic-reactor/cli

Commands

`init`

Initialize the configuration file (ic-reactor.json) in your project root.

npx ic-reactor init

Options:

-y, --yes: Skip prompts and use defaults.
-o, --out-dir <path>: Output directory for generated hooks (default: src/declarations).

`generate`

Regenerates hooks and declarations for all configured canisters. Run this whenever your .did files change.

npx ic-reactor generate

Options:

-c, --canister <name>: Generate only for a specific canister.
--clean: Clean output directory before generating.
--bindgen-only: Generate only .did, .did.d.ts, and .js declarations.

For each canister, the CLI writes:

<canister>.did copy
<canister>.did.d.ts TypeScript service types
<canister>.js IDL factory module
index.generated.ts managed reactor implementation, with optional typed hook exports
index.ts user-facing entrypoint

The CLI regenerates index.generated.ts on every run. It creates index.ts once, then preserves it unless the file is still the default wrapper or an older generated scaffold that can be migrated automatically.

Set target to choose the generated runtime:

react (default): generates the reactor plus bound React hooks
core: generates only the typed reactor exports with no React dependency

Use --bindgen-only when you only want the generated declaration files. In that mode, the CLI skips index.generated.ts and index.ts entirely and leaves any existing reactor files untouched.

Configuration

The ic-reactor.json file controls the CLI behavior.

{
  "$schema": "https://raw.githubusercontent.com/B3Pay/ic-reactor/main/packages/cli/schema.json",
  "outDir": "src/declarations",
  "clientManagerPath": "../../clients",
  "target": "react",
  "canisters": {
    "backend": {
      "name": "backend",
      "didFile": "src/backend/backend.did"
    }
  }
}

Options

Key	Type	Description
`outDir`	`string`	Base output directory for generated files (required).
`canisters`	`Record<string, CanisterConfig>`	Map of canister names to configurations (required).
`clientManagerPath`	`string`	Path to a custom `ClientManager` instance (optional).
`target`	`"react" \| "core"`	Default generated runtime target (optional).

Canister Config

Key	Type	Description
`name`	`string`	Canister name (required). Must match the key in `canisters`.
`didFile`	`string`	Path to the `.did` file (required).
`mode`	`string`	Reactor class to generate: `Reactor`, `DisplayReactor` (default), `CandidReactor`, `CandidDisplayReactor`, `MetadataDisplayReactor`.
`outDir`	`string`	Override output directory for this canister.
`clientManagerPath`	`string`	Override client manager path.
`target`	`string`	Override generated runtime target.
`canisterId`	`string`	Optional fixed canister ID.

Examples

Codegen in Action: Comparison between CLI and Vite plugin generated code.
TypeScript Demo: Using the CLI to generate pure TypeScript reactors without React.