@ic-reactor/vite-plugin 0.7.1 → 0.8.0

package/README.md

@@ -1,65 +1,35 @@
 # @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"
-import { icReactorPlugin } from "@ic-reactor/vite-plugin"
+import { icReactor } from "@ic-reactor/vite-plugin"
 
 export default defineConfig({
   plugins: [
     react(),
-    icReactorPlugin({
-      canisters: [
-        {
-          name: "backend",
-          didFile: "./backend/backend.did",
-        },
-      ],
+    icReactor({
+      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,57 +37,75 @@ 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.
+
+## Options
 
-The plugin generates headers in `src/declarations/<name>/index.ts` by default.
+```ts
+icReactor({
+  canisters: [
+    {
+      name: "backend",
+      didFile: "./backend/backend.did",
+      mode: "DisplayReactor",
+    },
+  ],
+  outDir: "src/declarations",
+  clientManagerPath: "../../clients",
+  injectEnvironment: true,
+})
+```
 
-```tsx
-import { useBackendQuery } from "./declarations/backend"
+### Per-canister options
 
-function MyComponent() {
-  const { data, isPending } = useBackendQuery({
-    functionName: "get_message",
-  })
+- `name`
+- `didFile`
+- `outDir`
+- `clientManagerPath`
+- `mode`
+- `canisterId`
 
-  return <p>{isPending ? "Loading..." : data}</p>
-}
-```
+Supported `mode` values:
 
-## Configuration
+- `Reactor`
+- `DisplayReactor`
+- `CandidReactor`
+- `CandidDisplayReactor`
+- `MetadataDisplayReactor`
 
-### 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       |
-| `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

@@ -30,7 +30,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  icReactorPlugin: () => icReactorPlugin
+  icReactor: () => icReactor
 });
 module.exports = __toCommonJS(index_exports);
 var import_node_path = __toESM(require("path"), 1);
@@ -78,7 +78,7 @@ function buildIcEnvCookie(canisterIds, rootKey) {
 }
 
 // src/index.ts
-function icReactorPlugin(options) {
+function icReactor(options) {
   const {
     canisters,
     outDir = "src/declarations",
@@ -93,6 +93,9 @@ function icReactorPlugin(options) {
   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 +121,13 @@ function icReactorPlugin(options) {
           }
         };
       }
-      const cookieValue = buildIcEnvCookie(icEnv.canisterIds, icEnv.rootKey);
+      const cookieValue = buildIcEnvCookie(
+        {
+          ...icEnv.canisterIds,
+          ...configuredCanisterIds
+        },
+        icEnv.rootKey
+      );
       return {
         server: {
           headers: {
@@ -191,5 +200,5 @@ function icReactorPlugin(options) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  icReactorPlugin
+  icReactor
 });

package/dist/index.d.cts

@@ -31,6 +31,6 @@ interface IcReactorPluginOptions {
      */
     injectEnvironment?: boolean;
 }
-declare function icReactorPlugin(options: IcReactorPluginOptions): any;
+declare function icReactor(options: IcReactorPluginOptions): any;
 
-export { type IcReactorPluginOptions, icReactorPlugin };
+export { type IcReactorPluginOptions, icReactor };

package/dist/index.d.ts

@@ -31,6 +31,6 @@ interface IcReactorPluginOptions {
      */
     injectEnvironment?: boolean;
 }
-declare function icReactorPlugin(options: IcReactorPluginOptions): any;
+declare function icReactor(options: IcReactorPluginOptions): any;
 
-export { type IcReactorPluginOptions, icReactorPlugin };
+export { type IcReactorPluginOptions, icReactor };

package/dist/index.js

@@ -46,7 +46,7 @@ function buildIcEnvCookie(canisterIds, rootKey) {
 }
 
 // src/index.ts
-function icReactorPlugin(options) {
+function icReactor(options) {
   const {
     canisters,
     outDir = "src/declarations",
@@ -61,6 +61,9 @@ function icReactorPlugin(options) {
   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 +89,13 @@ function icReactorPlugin(options) {
           }
         };
       }
-      const cookieValue = buildIcEnvCookie(icEnv.canisterIds, icEnv.rootKey);
+      const cookieValue = buildIcEnvCookie(
+        {
+          ...icEnv.canisterIds,
+          ...configuredCanisterIds
+        },
+        icEnv.rootKey
+      );
       return {
         server: {
           headers: {
@@ -158,5 +167,5 @@ function icReactorPlugin(options) {
   return plugin;
 }
 export {
-  icReactorPlugin
+  icReactor
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ic-reactor/vite-plugin",
-  "version": "0.7.1",
+  "version": "0.8.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.1"
+    "@ic-reactor/codegen": "0.8.0"
   },
   "peerDependencies": {
     "vite": "^4.2.0 || ^5.0.0 || ^6.0.0 || ^7.0.0"
   },
   "devDependencies": {
-    "@icp-sdk/bindgen": "^0.2.1",
-    "@types/node": "^25.2.3",
+    "@icp-sdk/bindgen": "^0.2.2",
+    "@types/node": "^25.3.5",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"

package/src/index.test.ts

@@ -1,9 +1,14 @@
 import { describe, it, expect, vi, beforeEach } from "vitest"
-import { icReactorPlugin, type IcReactorPluginOptions } from "./index"
+import * as vitePluginModule from "./index"
+import type { IcReactorPluginOptions } from "./index"
 import path from "path"
 import { execFileSync } from "child_process"
 import { runCanisterPipeline } from "@ic-reactor/codegen"
 
+const createVitePlugin =
+  (vitePluginModule as any).icReactor ??
+  (vitePluginModule as any).icReactorPlugin
+
 // Mock internal dependencies
 vi.mock("@ic-reactor/codegen", () => ({
   runCanisterPipeline: vi.fn(),
@@ -24,7 +29,7 @@ vi.mock("fs", () => ({
   },
 }))
 
-describe("icReactorPlugin", () => {
+describe("icReactor", () => {
   const mockOptions: IcReactorPluginOptions = {
     canisters: [
       {
@@ -63,7 +68,7 @@ describe("icReactorPlugin", () => {
   })
 
   it("should return correct plugin structure", () => {
-    const plugin = icReactorPlugin(mockOptions)
+    const plugin = createVitePlugin(mockOptions)
     expect(plugin.name).toBe("ic-reactor-plugin")
     expect(plugin.buildStart).toBeDefined()
     expect(plugin.handleHotUpdate).toBeDefined()
@@ -92,7 +97,7 @@ describe("icReactorPlugin", () => {
         }
       )
 
-      const plugin = icReactorPlugin(mockOptions)
+      const plugin = createVitePlugin(mockOptions)
       const config = (plugin as any).config({}, { command: "serve" })
 
       expect(config.server.headers["Set-Cookie"]).toContain("ic_env=")
@@ -105,12 +110,52 @@ describe("icReactorPlugin", () => {
       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")
       })
 
-      const plugin = icReactorPlugin(mockOptions)
+      const plugin = createVitePlugin(mockOptions)
       const config = (plugin as any).config({}, { command: "serve" })
 
       expect(config.server.headers).toBeUndefined()
@@ -118,7 +163,7 @@ describe("icReactorPlugin", () => {
     })
 
     it("should return empty config for build command", () => {
-      const plugin = icReactorPlugin(mockOptions)
+      const plugin = createVitePlugin(mockOptions)
       const config = (plugin as any).config({}, { command: "build" })
 
       expect(config).toEqual({})
@@ -127,7 +172,7 @@ describe("icReactorPlugin", () => {
 
   describe("buildStart", () => {
     it("should generate declarations and reactor file", async () => {
-      const plugin = icReactorPlugin(mockOptions)
+      const plugin = createVitePlugin(mockOptions)
       await (plugin.buildStart as any)()
 
       expect(runCanisterPipeline).toHaveBeenCalledWith({
@@ -150,7 +195,7 @@ describe("icReactorPlugin", () => {
         error: "Failed to generate",
       })
 
-      const plugin = icReactorPlugin(mockOptions)
+      const plugin = createVitePlugin(mockOptions)
       await (plugin.buildStart as any)()
 
       expect(consoleErrorSpy).toHaveBeenCalledWith(
@@ -159,11 +204,37 @@ describe("icReactorPlugin", () => {
 
       consoleErrorSpy.mockRestore()
     })
+
+    it("should pass canister mode through to codegen via canister config", async () => {
+      const plugin = createVitePlugin({
+        canisters: [
+          {
+            ...mockOptions.canisters[0],
+            mode: "Reactor",
+          },
+        ],
+        outDir: mockOptions.outDir,
+      })
+
+      await (plugin.buildStart as any)()
+
+      expect(runCanisterPipeline).toHaveBeenCalledWith({
+        canisterConfig: {
+          ...mockOptions.canisters[0],
+          mode: "Reactor",
+        },
+        projectRoot: expect.any(String),
+        globalConfig: {
+          outDir: "src/declarations",
+          clientManagerPath: "../../clients",
+        },
+      })
+    })
   })
 
   describe("handleHotUpdate", () => {
     it("should register configured .did files with the watcher", () => {
-      const plugin = icReactorPlugin(mockOptions)
+      const plugin = createVitePlugin(mockOptions)
       ;(plugin.configureServer as any)(mockServer)
 
       expect(mockServer.watcher.add).toHaveBeenCalledWith([
@@ -172,7 +243,7 @@ describe("icReactorPlugin", () => {
     })
 
     it("should restart server when .did file changes", async () => {
-      const plugin = icReactorPlugin(mockOptions)
+      const plugin = createVitePlugin(mockOptions)
       const ctx = {
         file: "/absolute/path/to/src/declarations/test.did",
         server: mockServer,
@@ -193,7 +264,7 @@ describe("icReactorPlugin", () => {
     })
 
     it("should ignore other files", () => {
-      const plugin = icReactorPlugin(mockOptions)
+      const plugin = createVitePlugin(mockOptions)
       const ctx = {
         file: "/some/other/file.ts",
         server: mockServer,

package/src/index.ts

@@ -39,7 +39,7 @@ export interface IcReactorPluginOptions {
   injectEnvironment?: boolean
 }
 
-export function icReactorPlugin(options: IcReactorPluginOptions): any {
+export function icReactor(options: IcReactorPluginOptions): any {
   const {
     canisters,
     outDir = "src/declarations",
@@ -57,6 +57,11 @@ export function icReactorPlugin(options: IcReactorPluginOptions): any {
     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 +98,13 @@ export function icReactorPlugin(options: IcReactorPluginOptions): any {
         }
       }
 
-      const cookieValue = buildIcEnvCookie(icEnv.canisterIds, icEnv.rootKey)
+      const cookieValue = buildIcEnvCookie(
+        {
+          ...icEnv.canisterIds,
+          ...configuredCanisterIds,
+        },
+        icEnv.rootKey
+      )
 
       return {
         server: {