Skip to content
IC Reactor

@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

Section titled “Installation”

Requires Node.js 22.12.0 or later.

bash pnpm add -D @ic-reactor/cli

Commands

Section titled “Commands”

init

Section titled “init”

Initialize the configuration file (ic-reactor.json) in the current directory.

Terminal window
npx ic-reactor init

Options:

  • -y, --yes: Skip prompts and use defaults.
  • -o, --out-dir <path>: Output directory for generated files (default: src/declarations). Only applied together with -y; the interactive flow prompts for it instead.

init writes to the current directory and nowhere else. A config in a parent directory belongs to a different project and is never modified, so running init inside a monorepo package creates that package’s own config.

-y is fully non-interactive and safe to run with stdin closed in CI. When ic-reactor.json already exists in the current directory it is left exactly as it is; delete it, or run init without -y and confirm the overwrite, to reconfigure. Cancelling a prompt aborts before anything is written.

generate

Section titled “generate”

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

Terminal window
npx ic-reactor generate

Options:

  • -c, --canister <name>: Generate only for a specific canister.
  • --clean: Remove generated output for canisters that are no longer configured.
  • --bindgen-only: Generate only the files under declarations/.

For each canister, the CLI writes into <outDir>/<canister>/:

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

Declaration filenames follow the .did file’s basename, not the canister name, and declarations/ is recreated from scratch on every run.

Because every run rewrites the output of the canisters it generates, the only output that can go stale is the directory of a canister that was renamed or removed from the config. --clean removes those, and only those: it leaves configured canisters (including the index.ts you own) alone, never deletes a directory holding no generated file, and is skipped for --canister <name> runs.

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

Section titled “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

Section titled “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

Section titled “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

Section titled “Examples”

See Also

Section titled “See Also”