@ic-reactor/vite-plugin 0.4.0 → 0.5.0

package/README.md

@@ -11,15 +11,14 @@
 
 ---
 
-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.
+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 when `.did` files change
-- 📦 **TypeScript Declarations** — Full type safety with auto-generated types
-- 🎯 **Display Types** — Optional `DisplayReactor` support for React-friendly types
-- 🔌 **Flexible** — Works with any `ClientManager` configuration
+- 🔄 **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
 
@@ -58,26 +57,29 @@ export default defineConfig({
 
 ### 2. Create Your ClientManager
 
-The plugin expects you to have a `ClientManager` exported from a file. By default, it looks for `./src/lib/clients.ts`:
+The plugin looks for a client manager to import. By default, it expects it at `../../clients` relative to the generated files.
 
 ```typescript
-// src/lib/clients.ts
+// src/clients.ts
 import { ClientManager } from "@ic-reactor/react"
 import { QueryClient } from "@tanstack/react-query"
 
 export const queryClient = new QueryClient()
-export const clientManager = new ClientManager({ queryClient })
+export const clientManager = new ClientManager({
+  queryClient,
+  withCanisterEnv: true, // Important for cookie injection support
+})
 ```
 
 ### 3. Use Generated Hooks
 
-The plugin generates an `index.ts` file in your canister folder (default: `./src/lib/canisters/<name>/index.ts`):
+The plugin generates headers in `src/declarations/<name>/index.ts` by default.
 
 ```tsx
-import { useActorQuery, useActorMutation } from "./canisters/backend"
+import { useBackendQuery } from "./declarations/backend"
 
 function MyComponent() {
-  const { data, isPending } = useActorQuery({
+  const { data, isPending } = useBackendQuery({
     functionName: "get_message",
   })
 
@@ -89,116 +91,32 @@ function MyComponent() {
 
 ### Plugin Options
 
-| Option              | Type               | Description                                          | Default                 |
-| :------------------ | :----------------- | :--------------------------------------------------- | :---------------------- |
-| `canisters`         | `CanisterConfig[]` | List of canisters to generate hooks for.             | `[]`                    |
-| `outDir`            | `string`           | Base output directory for generated files.           | `"./src/lib/canisters"` |
-| `injectEnvironment` | `boolean`          | Whether to inject canister IDs into `ic_env` cookie. | `true`                  |
-| `clientManagerPath` | `string`           | Path to a custom `ClientManager` instance.           | `"../../clients"`       |
+| 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`               |
 
 ### 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       |
-| `useDisplayReactor` | `boolean` | Use `DisplayReactor` instead of standard `Reactor`. | `true`   |
-| `clientManagerPath` | `string`  | Override client manager path for this canister.     | No       |
-
-## How It Works
-
-1. **Build Start**: The plugin reads your `.did` files and generates TypeScript declarations (`.js` and `.d.ts`).
-2. **Code Generation**: Creates a reactor instance and typed hooks (using `createActorHooks`) for each canister in `index.ts`.
-3. **Hot Reload**: Watches for `.did` file changes and regenerates everything automatically.
-4. **Local Proxy**: Configures a Vite proxy to redirect `/api` calls to your local replica.
-5. **Environment Detection**: Automatically injects canister IDs from `icp-cli` or `dfx` cache into your session.
-
-## DisplayReactor vs Reactor
-
-By default, the plugin uses `DisplayReactor` which transforms Candid types into React-friendly formats:
-
-| Candid Type | Reactor      | DisplayReactor |
-| ----------- | ------------ | -------------- |
-| `nat`       | `bigint`     | `string`       |
-| `int`       | `bigint`     | `string`       |
-| `principal` | `Principal`  | `string`       |
-| `vec nat8`  | `Uint8Array` | `string` (hex) |
-
-To use raw Candid types:
-
-```typescript
-icReactorPlugin({
-  canisters: [
-    {
-      name: "backend",
-      didFile: "./backend/backend.did",
-      useDisplayReactor: false, // Use Reactor instead
-    },
-  ],
-})
-```
-
-## Integration with ICP CLI
-
-`@ic-reactor/vite-plugin` now supports **zero-config local `icp-cli` canister env injection** during `vite dev`.
-
-When dev server starts, the plugin automatically tries to read:
-
-- `.icp/cache/mappings/local.ids.json`
-
-If present, it sets an `ic_env` cookie with:
-
-- `ic_root_key=<local-root-key>`
-- `PUBLIC_CANISTER_ID:<name>=<canister-id>`
-
-This means `withCanisterEnv: true` works out of the box after `icp deploy`, without custom cookie code in `vite.config.ts`.
-
-```typescript
-// 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: "./backend/backend.did",
-        },
-      ],
-    }),
-  ],
-})
-```
-
-If you need to disable this behavior:
-
-```typescript
-icReactorPlugin({
-  canisters: [...],
-  injectEnvironment: false,
-})
-```
-
-## Requirements
-
-- **Vite 5.x, 6.x, or 7.x**
-- **Node.js 18+**
-- **TypeScript 5.0+**
+| 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       |
 
-## Related Packages
+## Local Development (Environment Injection)
 
-- [@ic-reactor/react](https://www.npmjs.com/package/@ic-reactor/react) — React hooks for IC
-- [@ic-reactor/core](https://www.npmjs.com/package/@ic-reactor/core) — Core reactor functionality
-- [@icp-sdk/bindgen](https://www.npmjs.com/package/@icp-sdk/bindgen) — Candid binding generator
+When running `vite dev`, the plugin automatically handles local canister environment connection:
 
-## Documentation
+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.
 
-For comprehensive guides and API reference, visit the [documentation site](https://b3pay.github.io/ic-reactor/v3).
+This means you **don't** need complex `vite.config.ts` proxy rules or manual `.env` file management for local addresses — it just works.
 
 ## License
 

package/dist/index.cjs

@@ -33,16 +33,19 @@ __export(index_exports, {
   icReactorPlugin: () => icReactorPlugin
 });
 module.exports = __toCommonJS(index_exports);
-var import_fs = __toESM(require("fs"), 1);
-var import_path = __toESM(require("path"), 1);
-var import_child_process = require("child_process");
+var import_node_path = __toESM(require("path"), 1);
 var import_codegen = require("@ic-reactor/codegen");
+
+// src/env.ts
+var import_child_process = require("child_process");
 function getIcEnvironmentInfo(canisterNames) {
   const environment = process.env.ICP_ENVIRONMENT || "local";
   try {
     const networkStatus = JSON.parse(
       (0, import_child_process.execFileSync)("icp", ["network", "status", "-e", environment, "--json"], {
-        encoding: "utf-8"
+        encoding: "utf-8",
+        stdio: ["ignore", "pipe", "ignore"]
+        // suppress stderr
       })
     );
     const rootKey = networkStatus.root_key;
@@ -53,35 +56,51 @@ function getIcEnvironmentInfo(canisterNames) {
         const canisterId = (0, import_child_process.execFileSync)(
           "icp",
           ["canister", "status", name, "-e", environment, "-i"],
-          {
-            encoding: "utf-8"
-          }
+          { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }
         ).trim();
-        canisterIds[name] = canisterId;
+        if (canisterId) {
+          canisterIds[name] = canisterId;
+        }
       } catch {
       }
     }
     return { environment, rootKey, proxyTarget, canisterIds };
-  } catch {
+  } catch (error) {
     return null;
   }
 }
 function buildIcEnvCookie(canisterIds, rootKey) {
-  const envParts = [`ic_root_key=${rootKey}`];
+  const parts = [`ic_root_key=${rootKey}`];
   for (const [name, id] of Object.entries(canisterIds)) {
-    envParts.push(`PUBLIC_CANISTER_ID:${name}=${id}`);
+    parts.push(`PUBLIC_CANISTER_ID:${name}=${id}`);
   }
-  return encodeURIComponent(envParts.join("&"));
+  return encodeURIComponent(parts.join("&"));
 }
+
+// src/index.ts
 function icReactorPlugin(options) {
-  const baseOutDir = options.outDir ?? "./src/lib/canisters";
+  const {
+    canisters,
+    outDir = "src/declarations",
+    clientManagerPath = "../../clients",
+    injectEnvironment = true
+  } = options;
+  const globalConfig = {
+    outDir,
+    clientManagerPath
+  };
   return {
     name: "ic-reactor-plugin",
-    config(_config, { command }) {
-      if (command !== "serve" || !(options.injectEnvironment ?? true)) {
+    enforce: "pre",
+    // Run before other plugins
+    config(config, { command }) {
+      if (command !== "serve" || !injectEnvironment) {
         return {};
       }
-      const canisterNames = options.canisters.map((c) => c.name);
+      const canisterNames = canisters.map((c) => c.name).filter((n) => !!n);
+      if (!canisterNames.includes("internet_identity")) {
+        canisterNames.push("internet_identity");
+      }
       const icEnv = getIcEnvironmentInfo(canisterNames);
       if (!icEnv) {
         return {
@@ -111,91 +130,53 @@ function icReactorPlugin(options) {
       };
     },
     async buildStart() {
-      const defaultClientPath = import_path.default.resolve(
-        process.cwd(),
-        "src/lib/clients.ts"
+      const projectRoot = process.cwd();
+      console.log(
+        `[ic-reactor] Generating hooks for ${canisters.length} canisters...`
       );
-      if (!import_fs.default.existsSync(defaultClientPath)) {
-        console.log(
-          `[ic-reactor] Default client manager not found. Creating at ${defaultClientPath}`
-        );
-        const clientContent = (0, import_codegen.generateClientFile)();
-        import_fs.default.mkdirSync(import_path.default.dirname(defaultClientPath), { recursive: true });
-        import_fs.default.writeFileSync(defaultClientPath, clientContent);
-      }
-      for (const canister of options.canisters) {
-        let didFile = canister.didFile;
-        const outDir = canister.outDir ?? import_path.default.join(baseOutDir, canister.name);
-        if (!didFile) {
-          const environment = process.env.ICP_ENVIRONMENT || "local";
-          console.log(
-            `[ic-reactor] didFile not specified for "${canister.name}". Attempting to download from canister...`
-          );
-          try {
-            const candidContent = (0, import_child_process.execFileSync)(
-              "icp",
-              [
-                "canister",
-                "metadata",
-                canister.name,
-                "candid:service",
-                "-e",
-                environment
-              ],
-              { encoding: "utf-8" }
-            ).trim();
-            const declarationsDir = import_path.default.join(outDir, "declarations");
-            if (!import_fs.default.existsSync(declarationsDir)) {
-              import_fs.default.mkdirSync(declarationsDir, { recursive: true });
-            }
-            didFile = import_path.default.join(declarationsDir, `${canister.name}.did`);
-            import_fs.default.writeFileSync(didFile, candidContent);
-            console.log(
-              `[ic-reactor] Candid downloaded and saved to ${didFile}`
-            );
-          } catch (error) {
+      for (const canisterConfig of canisters) {
+        try {
+          const result = await (0, import_codegen.runCanisterPipeline)({
+            canisterConfig,
+            projectRoot,
+            globalConfig
+          });
+          if (!result.success) {
             console.error(
-              `[ic-reactor] Failed to download candid for ${canister.name}: ${error}`
+              `[ic-reactor] Failed to generate ${canisterConfig.name}: ${result.error}`
             );
-            continue;
+          } else {
           }
-        }
-        console.log(
-          `[ic-reactor] Generating hooks for ${canister.name} from ${didFile}`
-        );
-        const result = await (0, import_codegen.generateDeclarations)({
-          didFile,
-          outDir,
-          canisterName: canister.name
-        });
-        if (!result.success) {
+        } catch (err) {
           console.error(
-            `[ic-reactor] Failed to generate declarations: ${result.error}`
+            `[ic-reactor] Error generating ${canisterConfig.name}:`,
+            err
           );
-          continue;
         }
-        const reactorContent = (0, import_codegen.generateReactorFile)({
-          canisterName: canister.name,
-          didFile,
-          clientManagerPath: canister.clientManagerPath ?? options.clientManagerPath
-        });
-        const reactorPath = import_path.default.join(outDir, "index.ts");
-        import_fs.default.mkdirSync(outDir, { recursive: true });
-        import_fs.default.writeFileSync(reactorPath, reactorContent);
-        console.log(`[ic-reactor] Reactor hooks generated at ${reactorPath}`);
       }
     },
     handleHotUpdate({ file, server }) {
       if (file.endsWith(".did")) {
-        const canister = options.canisters.find((c) => {
-          if (!c.didFile) return false;
-          return import_path.default.resolve(c.didFile) === file;
+        const affectedCanister = canisters.find((c) => {
+          const configPath = import_node_path.default.resolve(process.cwd(), c.didFile);
+          return configPath === file;
         });
-        if (canister) {
+        if (affectedCanister) {
           console.log(
-            `[ic-reactor] Detected change in ${file}, regenerating...`
+            `[ic-reactor] .did file changed: ${affectedCanister.name}. Regenerating...`
           );
-          server.restart();
+          const projectRoot = process.cwd();
+          (0, import_codegen.runCanisterPipeline)({
+            canisterConfig: affectedCanister,
+            projectRoot,
+            globalConfig
+          }).then((result) => {
+            if (result.success) {
+              server.ws.send({ type: "full-reload" });
+            } else {
+              console.error(`[ic-reactor] Regeneration failed: ${result.error}`);
+            }
+          });
         }
       }
     }

package/dist/index.d.cts

@@ -1,55 +1,37 @@
 import { Plugin } from 'vite';
+import { CanisterConfig } from '@ic-reactor/codegen';
 
 /**
- * IC-Reactor Vite Plugin
+ * @ic-reactor/vite-plugin
  *
- * A Vite plugin that generates ic-reactor hooks from Candid .did files.
- * Uses @ic-reactor/codegen for all code generation logic.
- *
- * Usage:
- * ```ts
- * import { icReactorPlugin } from "@ic-reactor/vite-plugin"
- *
- * export default defineConfig({
- *   plugins: [
- *     icReactorPlugin({
- *       canisters: [
- *         {
- *           name: "backend",
- *           didFile: "../backend/backend.did",
- *           clientManagerPath: "../lib/client"
- *         }
- *       ]
- *     })
- *   ]
- * })
- * ```
+ * Vite plugin that:
+ * 1. Generates hooks at build time (using @ic-reactor/codegen pipeline)
+ * 2. Injects `ic_env` cookie for local development (via proxy)
+ * 3. Hot-reloads when .did files change
  */
 
-interface CanisterConfig {
-    name: string;
-    outDir?: string;
-    didFile?: string;
-    clientManagerPath?: string;
-}
 interface IcReactorPluginOptions {
-    /** List of canisters to generate hooks for */
+    /**
+     * Canister configurations.
+     * `name` is required for each canister.
+     */
     canisters: CanisterConfig[];
-    /** Base output directory (default: ./src/lib/canisters) */
+    /**
+     * Default output directory (relative to project root).
+     * Default: "src/declarations"
+     */
     outDir?: string;
     /**
-     * Path to import ClientManager from (relative to generated file).
+     * Default client manager import path.
      * Default: "../../clients"
      */
     clientManagerPath?: string;
     /**
-     * Automatically inject the IC environment (canister IDs and root key)
-     * into the browser using an `ic_env` cookie. (default: true)
-     *
-     * This is useful for local development with `icp`.
+     * Automatically inject `ic_env` cookie for local development?
+     * Default: true
      */
     injectEnvironment?: boolean;
 }
 declare function icReactorPlugin(options: IcReactorPluginOptions): Plugin;
 
-export { type CanisterConfig, type IcReactorPluginOptions, icReactorPlugin };
+export { type IcReactorPluginOptions, icReactorPlugin };

package/dist/index.d.ts

@@ -1,55 +1,37 @@
 import { Plugin } from 'vite';
+import { CanisterConfig } from '@ic-reactor/codegen';
 
 /**
- * IC-Reactor Vite Plugin
+ * @ic-reactor/vite-plugin
  *
- * A Vite plugin that generates ic-reactor hooks from Candid .did files.
- * Uses @ic-reactor/codegen for all code generation logic.
- *
- * Usage:
- * ```ts
- * import { icReactorPlugin } from "@ic-reactor/vite-plugin"
- *
- * export default defineConfig({
- *   plugins: [
- *     icReactorPlugin({
- *       canisters: [
- *         {
- *           name: "backend",
- *           didFile: "../backend/backend.did",
- *           clientManagerPath: "../lib/client"
- *         }
- *       ]
- *     })
- *   ]
- * })
- * ```
+ * Vite plugin that:
+ * 1. Generates hooks at build time (using @ic-reactor/codegen pipeline)
+ * 2. Injects `ic_env` cookie for local development (via proxy)
+ * 3. Hot-reloads when .did files change
  */
 
-interface CanisterConfig {
-    name: string;
-    outDir?: string;
-    didFile?: string;
-    clientManagerPath?: string;
-}
 interface IcReactorPluginOptions {
-    /** List of canisters to generate hooks for */
+    /**
+     * Canister configurations.
+     * `name` is required for each canister.
+     */
     canisters: CanisterConfig[];
-    /** Base output directory (default: ./src/lib/canisters) */
+    /**
+     * Default output directory (relative to project root).
+     * Default: "src/declarations"
+     */
     outDir?: string;
     /**
-     * Path to import ClientManager from (relative to generated file).
+     * Default client manager import path.
      * Default: "../../clients"
      */
     clientManagerPath?: string;
     /**
-     * Automatically inject the IC environment (canister IDs and root key)
-     * into the browser using an `ic_env` cookie. (default: true)
-     *
-     * This is useful for local development with `icp`.
+     * Automatically inject `ic_env` cookie for local development?
+     * Default: true
      */
     injectEnvironment?: boolean;
 }
 declare function icReactorPlugin(options: IcReactorPluginOptions): Plugin;
 
-export { type CanisterConfig, type IcReactorPluginOptions, icReactorPlugin };
+export { type IcReactorPluginOptions, icReactorPlugin };