Vite Plugin

The @ic-reactor/vite-plugin automates the generation of TypeScript declarations and Reactor hooks from your Candid files. It integrates seamlessly with Vite’s development server, providing hot-module replacement (HMR) for your canister interfaces.

Installation

pnpm

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

npm

bash npm install -D @ic-reactor/vite-plugin

yarn

bash yarn add -D @ic-reactor/vite-plugin

bun

bash bun add -D @ic-reactor/vite-plugin

Usage

Add the plugin to your vite.config.ts:

import { defineConfig } from "vite"
import react from "@vitejs/plugin-react"
import { icReactorPlugin } from "@ic-reactor/vite-plugin"

export default defineConfig({
  plugins: [
    react(),
    icReactorPlugin({
      canisters: [
        {
          name: "backend",
          didFile: "src/backend/backend.did", // Path to your .did file
        },
      ],
    }),
  ],
})

Features

Zero-Config Proxy

The plugin automatically configures a proxy for /api requests to your local replica (defaulting to http://127.0.0.1:4943). This ensures your frontend can communicate with backend canisters during development without CORS issues.

Automatic ic_env Injection

The plugin automatically detects your network environment and canister IDs using the icp or dfx CLI. It injects this information into the ic_env cookie. This allows ClientManager to automatically resolve the correct canister IDs and network root key without manual configuration.

Hot Module Replacement

The plugin watches your .did files. When you modify a Candid file, it automatically:

1. Regenerates the TypeScript declarations (.d.ts, .js factory).
2. Regenerates the index.ts file with fully typed hooks.
3. Restarts the Vite server to pick up the changes.

Configuration Options

Option	Type	Description	Default
canisters	CanisterConfig[]	List of canisters to generate hooks for (required).	-
outDir	string	Base output directory for generated files.	"src/declarations"
injectEnvironment	boolean	Whether to inject canister IDs into ic_env cookie.	true
clientManagerPath	string	Path to a custom ClientManager instance.	"../../clients"

Canister Config

Option	Type	Description	Required
name	string	Name of the canister (used in generated code).	Yes
didFile	string	Path to the .did file.	Yes
outDir	string	Override output directory for this canister.	No
clientManagerPath	string	Override client manager path for this canister.	No
canisterId	string	Optional fixed canister ID.	No

Examples

Check out these examples to see the Vite plugin in action:

• Vite Plugin Demo: Basic usage of the Vite plugin for automatic hook generation.
• Vite Environment Variables: Using the plugin to automatically inject canister IDs and root keys.
• Codegen in Action: Comparison between Vite plugin and CLI output.