@ic-reactor/vite-plugin 0.7.2 → 0.9.0

package/README.md

@@ -1,40 +1,19 @@
 # @ic-reactor/vite-plugin
 
-<div align="center">
-  <strong>Zero-config Vite plugin for auto-generating IC reactor hooks from Candid files.</strong>
-  <br><br>
-  
-  [![npm version](https://img.shields.io/npm/v/@ic-reactor/vite-plugin.svg)](https://www.npmjs.com/package/@ic-reactor/vite-plugin)
-  [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
-  [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
-</div>
+Vite plugin for IC Reactor code generation. It runs the shared
+`@ic-reactor/codegen` pipeline, watches `.did` files, and can inject the
+`ic_env` cookie used by `ClientManager` during local development.
 
----
-
-Automatically generate type-safe React hooks for your Internet Computer canisters. This plugin watches your `.did` files and generates ready-to-use hooks with full TypeScript support using the shared `@ic-reactor/codegen` pipeline.
-
-## Features
-
-- ⚡ **Zero Config** — Point to your `.did` file and get hooks instantly
-- 🔄 **Hot Reload** — Automatically regenerates hooks and types when `.did` files change
-- 📦 **TypeScript Declarations** — Full built-in type safety
-- 🌍 **Auto Environment** — Automatically detects local replica and injects `ic_env` cookie
-
-## Installation
+## Install
 
 ```bash
-# With pnpm
 pnpm add -D @ic-reactor/vite-plugin
-
-# Required peer dependencies
 pnpm add @ic-reactor/react @tanstack/react-query @icp-sdk/core
 ```
 
 ## Quick Start
 
-### 1. Configure the Plugin
-
-```typescript
+```ts
 // vite.config.ts
 import { defineConfig } from "vite"
 import react from "@vitejs/plugin-react"
@@ -44,22 +23,13 @@ export default defineConfig({
   plugins: [
     react(),
     icReactor({
-      canisters: [
-        {
-          name: "backend",
-          didFile: "./backend/backend.did",
-        },
-      ],
+      canisters: [{ name: "backend", didFile: "./backend/backend.did" }],
     }),
   ],
 })
 ```
 
-### 2. Create Your ClientManager
-
-The plugin looks for a client manager to import. By default, it expects it at `../../clients` relative to the generated files.
-
-```typescript
+```ts
 // src/clients.ts
 import { ClientManager } from "@ic-reactor/react"
 import { QueryClient } from "@tanstack/react-query"
@@ -67,75 +37,85 @@ import { QueryClient } from "@tanstack/react-query"
 export const queryClient = new QueryClient()
 export const clientManager = new ClientManager({
   queryClient,
-  withCanisterEnv: true, // Important for cookie injection support
+  withCanisterEnv: true,
 })
 ```
 
-### 3. Use Generated Hooks
+The plugin generates files under `src/declarations/<canister>/` by default.
 
-The plugin generates headers in `src/declarations/<name>/index.ts` by default.
+If you want non-React output, set `target: "core"` and install the matching
+runtime package instead of `@ic-reactor/react`.
 
-```tsx
-import { useBackendQuery } from "./declarations/backend"
-
-function MyComponent() {
-  const { data, isPending } = useBackendQuery({
-    functionName: "get_message",
-  })
-
-  return <p>{isPending ? "Loading..." : data}</p>
-}
-```
-
-### Reactor Mode (per canister)
-
-By default, generated hooks use `DisplayReactor` (backward compatible). Set `mode` on a canister to choose the generated reactor class (`Reactor`, `DisplayReactor`, `CandidReactor`, `CandidDisplayReactor`, or `MetadataDisplayReactor`).
+## Options
 
 ```ts
 icReactor({
   canisters: [
-    { name: "backend", didFile: "./backend/backend.did" },
     {
-      name: "workflow_engine",
-      mode: "Reactor",
-      didFile: "./workflow/workflow_engine.did",
+      name: "backend",
+      didFile: "./backend/backend.did",
+      mode: "DisplayReactor",
     },
   ],
+  outDir: "src/declarations",
+  clientManagerPath: "../../clients",
+  target: "react",
+  injectEnvironment: true,
 })
 ```
 
-## Configuration
+### Per-canister options
+
+- `name`
+- `didFile`
+- `outDir`
+- `clientManagerPath`
+- `target`
+- `mode`
+- `canisterId`
+
+Supported `mode` values:
+
+- `Reactor`
+- `DisplayReactor`
+- `CandidReactor`
+- `CandidDisplayReactor`
+- `MetadataDisplayReactor`
+
+Supported `target` values:
+
+- `react` (default): generates the reactor plus bound React hooks
+- `core`: generates only the typed reactor exports with no React dependency
 
-### Plugin Options
+## Local Development Behavior
 
-| Option              | Type               | Description                                         | Default              |
-| :------------------ | :----------------- | :-------------------------------------------------- | :------------------- |
-| `canisters`         | `CanisterConfig[]` | List of canisters to generate hooks for (required). | -                    |
-| `outDir`            | `string`           | Base output directory for generated files.          | `"src/declarations"` |
-| `clientManagerPath` | `string`           | Path to client manager import.                      | `"../../clients"`    |
-| `injectEnvironment` | `boolean`          | Inject `ic_env` cookie for local development.       | `true`               |
+When `injectEnvironment` is enabled during `vite dev`, the plugin:
 
-### Canister Config
+1. asks `icp-cli` for the local network status
+2. resolves configured canister IDs
+3. sets the `ic_env` cookie
+4. proxies `/api` to the local replica
 
-| Option              | Type                                                                                                     | Description                                     | Required |
-| :------------------ | :------------------------------------------------------------------------------------------------------- | :---------------------------------------------- | :------- |
-| `name`              | `string`                                                                                                 | Name of the canister (used for variable names). | Yes      |
-| `didFile`           | `string`                                                                                                 | Path to the `.did` file.                        | Yes      |
-| `outDir`            | `string`                                                                                                 | Override output directory for this canister.    | No       |
-| `clientManagerPath` | `string`                                                                                                 | Override client manager path.                   | No       |
-| `mode`              | `"Reactor" \| "DisplayReactor" \| "CandidReactor" \| "CandidDisplayReactor" \| "MetadataDisplayReactor"` | Reactor class for generated hooks.              | No       |
-| `canisterId`        | `string`                                                                                                 | Optional fixed canister ID.                     | No       |
+If environment detection fails, the plugin still falls back to proxying `/api`
+to `http://127.0.0.1:4943`, but it will not inject canister metadata.
 
-## Local Development (Environment Injection)
+## File Regeneration
 
-When running `vite dev`, the plugin automatically handles local canister environment connection:
+On startup and on `.did` file changes, the plugin regenerates declarations and
+the managed `index.generated.ts` implementation. The user-facing `index.ts`
+entry is created once, then preserved unless it still matches the default
+wrapper or a legacy generated scaffold that can be migrated automatically.
+When a watched `.did` file changes, the plugin sends a full browser reload so
+the new declarations are picked up.
 
-1. Detects your local environment (using `icp` or `dfx` CLI).
-2. Sets an `ic_env` cookie containing the root key and canister IDs.
-3. Sets up a proxy for `/api` to your local replica.
+## When To Use It
 
-This means you **don't** need complex `vite.config.ts` proxy rules or manual `.env` file management for local addresses — it just works.
+- Vite apps with active `.did` iteration
+- teams that want zero extra codegen commands during development
+- projects that want the same output format as the CLI without manual steps
 
-## License
+## See Also
 
-MIT © [Behrad Deylami](https://github.com/b3hr4d)
+- Docs: https://ic-reactor.b3pay.net/v3/packages/vite-plugin
+- `@ic-reactor/codegen`: ../codegen/README.md
+- `@ic-reactor/cli`: ../cli/README.md

package/dist/index.cjs

@@ -83,16 +83,21 @@ function icReactor(options) {
     canisters,
     outDir = "src/declarations",
     clientManagerPath = "../../clients",
+    target = "react",
     injectEnvironment = true
   } = options;
   const globalConfig = {
     outDir,
-    clientManagerPath
+    clientManagerPath,
+    target
   };
   const projectRoot = process.cwd();
   const resolveDidPath = (didFile) => import_node_path.default.normalize(
     import_node_path.default.isAbsolute(didFile) ? didFile : import_node_path.default.resolve(projectRoot, didFile)
   );
+  const configuredCanisterIds = Object.fromEntries(
+    canisters.filter((canister) => !!canister.canisterId).map((canister) => [canister.name, canister.canisterId])
+  );
   const plugin = {
     name: "ic-reactor-plugin",
     enforce: "pre",
@@ -118,7 +123,13 @@ function icReactor(options) {
           }
         };
       }
-      const cookieValue = buildIcEnvCookie(icEnv.canisterIds, icEnv.rootKey);
+      const cookieValue = buildIcEnvCookie(
+        {
+          ...icEnv.canisterIds,
+          ...configuredCanisterIds
+        },
+        icEnv.rootKey
+      );
       return {
         server: {
           headers: {
@@ -139,7 +150,7 @@ function icReactor(options) {
     },
     async buildStart() {
       console.log(
-        `[ic-reactor] Generating hooks for ${canisters.length} canisters...`
+        `[ic-reactor] Generating canister bindings for ${canisters.length} canisters...`
       );
       for (const canisterConfig of canisters) {
         try {

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { CanisterConfig } from '@ic-reactor/codegen';
+import { CanisterConfig, CodegenTarget } from '@ic-reactor/codegen';
 
 /**
  * @ic-reactor/vite-plugin
@@ -25,6 +25,11 @@ interface IcReactorPluginOptions {
      * Default: "../../clients"
      */
     clientManagerPath?: string;
+    /**
+     * Default generated runtime target.
+     * Default: "react"
+     */
+    target?: CodegenTarget;
     /**
      * Automatically inject `ic_env` cookie for local development?
      * Default: true

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { CanisterConfig } from '@ic-reactor/codegen';
+import { CanisterConfig, CodegenTarget } from '@ic-reactor/codegen';
 
 /**
  * @ic-reactor/vite-plugin
@@ -25,6 +25,11 @@ interface IcReactorPluginOptions {
      * Default: "../../clients"
      */
     clientManagerPath?: string;
+    /**
+     * Default generated runtime target.
+     * Default: "react"
+     */
+    target?: CodegenTarget;
     /**
      * Automatically inject `ic_env` cookie for local development?
      * Default: true

package/dist/index.js

@@ -51,16 +51,21 @@ function icReactor(options) {
     canisters,
     outDir = "src/declarations",
     clientManagerPath = "../../clients",
+    target = "react",
     injectEnvironment = true
   } = options;
   const globalConfig = {
     outDir,
-    clientManagerPath
+    clientManagerPath,
+    target
   };
   const projectRoot = process.cwd();
   const resolveDidPath = (didFile) => path.normalize(
     path.isAbsolute(didFile) ? didFile : path.resolve(projectRoot, didFile)
   );
+  const configuredCanisterIds = Object.fromEntries(
+    canisters.filter((canister) => !!canister.canisterId).map((canister) => [canister.name, canister.canisterId])
+  );
   const plugin = {
     name: "ic-reactor-plugin",
     enforce: "pre",
@@ -86,7 +91,13 @@ function icReactor(options) {
           }
         };
       }
-      const cookieValue = buildIcEnvCookie(icEnv.canisterIds, icEnv.rootKey);
+      const cookieValue = buildIcEnvCookie(
+        {
+          ...icEnv.canisterIds,
+          ...configuredCanisterIds
+        },
+        icEnv.rootKey
+      );
       return {
         server: {
           headers: {
@@ -107,7 +118,7 @@ function icReactor(options) {
     },
     async buildStart() {
       console.log(
-        `[ic-reactor] Generating hooks for ${canisters.length} canisters...`
+        `[ic-reactor] Generating canister bindings for ${canisters.length} canisters...`
       );
       for (const canisterConfig of canisters) {
         try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ic-reactor/vite-plugin",
-  "version": "0.7.2",
+  "version": "0.9.0",
   "description": "Vite plugin for zero-config IC reactor generation from Candid files",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -37,14 +37,14 @@
     "url": "https://github.com/B3Pay/ic-reactor/issues"
   },
   "dependencies": {
-    "@ic-reactor/codegen": "0.7.2"
+    "@ic-reactor/codegen": "0.9.0"
   },
   "peerDependencies": {
     "vite": "^4.2.0 || ^5.0.0 || ^6.0.0 || ^7.0.0"
   },
   "devDependencies": {
     "@icp-sdk/bindgen": "^0.2.2",
-    "@types/node": "^25.3.0",
+    "@types/node": "^25.3.5",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"

package/src/index.test.ts

@@ -110,6 +110,46 @@ describe("icReactor", () => {
       expect(config.server.proxy["/api"].target).toBe("http://127.0.0.1:4943")
     })
 
+    it("should prefer configured canisterId over CLI-discovered env values", () => {
+      ;(execFileSync as any).mockImplementation(
+        (command: string, args: string[], options: any) => {
+          if (
+            command === "icp" &&
+            args.includes("network") &&
+            args.includes("status")
+          ) {
+            return JSON.stringify({ root_key: "mock-root-key", port: 4943 })
+          }
+          if (
+            command === "icp" &&
+            args.includes("canister") &&
+            args.includes("status")
+          ) {
+            return "local-cli-canister-id"
+          }
+          return ""
+        }
+      )
+
+      const plugin = createVitePlugin({
+        ...mockOptions,
+        canisters: [
+          {
+            ...mockOptions.canisters[0],
+            canisterId: "yq4ns-hyaaa-aaaap-akbna-cai",
+          },
+        ],
+      })
+      const config = (plugin as any).config({}, { command: "serve" })
+
+      expect(config.server.headers["Set-Cookie"]).toContain(
+        "PUBLIC_CANISTER_ID%3Atest_canister%3Dyq4ns-hyaaa-aaaap-akbna-cai"
+      )
+      expect(config.server.headers["Set-Cookie"]).not.toContain(
+        "PUBLIC_CANISTER_ID%3Atest_canister%3Dlocal-cli-canister-id"
+      )
+    })
+
     it("should fallback to default proxy when icp-cli fails", () => {
       ;(execFileSync as any).mockImplementation(() => {
         throw new Error("Command not found")
@@ -141,6 +181,7 @@ describe("icReactor", () => {
         globalConfig: {
           outDir: "src/declarations",
           clientManagerPath: "../../clients",
+          target: "react",
         },
       })
     })
@@ -187,6 +228,26 @@ describe("icReactor", () => {
         globalConfig: {
           outDir: "src/declarations",
           clientManagerPath: "../../clients",
+          target: "react",
+        },
+      })
+    })
+
+    it("should pass the configured runtime target to codegen", async () => {
+      const plugin = createVitePlugin({
+        ...mockOptions,
+        target: "core",
+      })
+
+      await (plugin.buildStart as any)()
+
+      expect(runCanisterPipeline).toHaveBeenCalledWith({
+        canisterConfig: mockOptions.canisters[0],
+        projectRoot: expect.any(String),
+        globalConfig: {
+          outDir: "src/declarations",
+          clientManagerPath: "../../clients",
+          target: "core",
         },
       })
     })

package/src/index.ts

@@ -13,6 +13,7 @@ import {
   runCanisterPipeline,
   type CanisterConfig,
   type CodegenConfig,
+  type CodegenTarget,
 } from "@ic-reactor/codegen"
 import { getIcEnvironmentInfo, buildIcEnvCookie } from "./env.js"
 
@@ -32,6 +33,11 @@ export interface IcReactorPluginOptions {
    * Default: "../../clients"
    */
   clientManagerPath?: string
+  /**
+   * Default generated runtime target.
+   * Default: "react"
+   */
+  target?: CodegenTarget
   /**
    * Automatically inject `ic_env` cookie for local development?
    * Default: true
@@ -44,19 +50,29 @@ export function icReactor(options: IcReactorPluginOptions): any {
     canisters,
     outDir = "src/declarations",
     clientManagerPath = "../../clients",
+    target = "react",
     injectEnvironment = true,
   } = options
 
   // Construct a partial CodegenConfig to pass to the pipeline
-  const globalConfig: Pick<CodegenConfig, "outDir" | "clientManagerPath"> = {
+  const globalConfig: Pick<
+    CodegenConfig,
+    "outDir" | "clientManagerPath" | "target"
+  > = {
     outDir,
     clientManagerPath,
+    target,
   }
   const projectRoot = process.cwd()
   const resolveDidPath = (didFile: string) =>
     path.normalize(
       path.isAbsolute(didFile) ? didFile : path.resolve(projectRoot, didFile)
     )
+  const configuredCanisterIds = Object.fromEntries(
+    canisters
+      .filter((canister) => !!canister.canisterId)
+      .map((canister) => [canister.name, canister.canisterId as string])
+  )
 
   const plugin: Plugin = {
     name: "ic-reactor-plugin",
@@ -93,7 +109,13 @@ export function icReactor(options: IcReactorPluginOptions): any {
         }
       }
 
-      const cookieValue = buildIcEnvCookie(icEnv.canisterIds, icEnv.rootKey)
+      const cookieValue = buildIcEnvCookie(
+        {
+          ...icEnv.canisterIds,
+          ...configuredCanisterIds,
+        },
+        icEnv.rootKey
+      )
 
       return {
         server: {
@@ -120,7 +142,7 @@ export function icReactor(options: IcReactorPluginOptions): any {
       // ── Code Generation ──────────────────────────────────────────────────
 
       console.log(
-        `[ic-reactor] Generating hooks for ${canisters.length} canisters...`
+        `[ic-reactor] Generating canister bindings for ${canisters.length} canisters...`
       )
 
       for (const canisterConfig of canisters) {