@ic-reactor/vite-plugin 0.12.0 → 0.13.0

package/README.md

@@ -69,9 +69,26 @@ icReactor({
   clientManagerPath: "../../clients",
   target: "react",
   injectEnvironment: true,
+  failOnError: true,
 })
 ```
 
+Relative paths — `didFile`, `outDir` — resolve against Vite's resolved
+`config.root`, not the directory vite was started from. If you set
+`root: "frontend"`, write the paths as the project itself sees them.
+
+Note `--config` alone does **not** change the root: `vite build --config
+apps/web/vite.config.ts` still leaves `root` at the directory vite was started
+from, so app-relative paths resolve against the monorepo root. Set `root` in the
+config file, or pass it positionally (`vite build apps/web --config …`), for
+those paths to mean what the app expects.
+
+`failOnError` decides what a failed canister does to the run. It defaults to
+`true` under `vite build` and `false` under `vite dev`: a build that quietly
+ships the bindings left over from the last successful run is worse than no
+build at all, while a dev server has to survive the broken intermediate states
+of a `.did` file being edited.
+
 ### Per-canister options
 
 - `name`
@@ -112,7 +129,10 @@ Set the `ICP_ENVIRONMENT` environment variable to target a non-default network
 (defaults to `"local"`).
 
 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.
+to `http://127.0.0.1:4943`, but it will not inject canister metadata. It warns
+when that happens with canisters configured, because the failure is otherwise
+indistinguishable from success until the app breaks on an undefined canister
+id. Run with `DEBUG=ic-reactor` to see the `icp` output behind the warning.
 
 ## File Regeneration
 
@@ -121,7 +141,11 @@ 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.
+the new declarations are picked up. Regeneration is serialized per canister —
+saves that land while a run is in flight collapse into a single rerun — so two
+rapid saves cannot interleave inside the pipeline's delete-then-write sequence.
+A regeneration that fails is reported to the terminal and to the browser error
+overlay rather than leaving the page on stale bindings.
 
 ## When To Use It
 

package/dist/index.cjs

@@ -39,44 +39,59 @@ 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";
+  const networkName = process.env.ICP_ENVIRONMENT || "local";
+  const diagnostics = [];
   try {
     const networkStatus = JSON.parse(
-      (0, import_child_process.execFileSync)("icp", ["network", "status", "-e", environment, "--json"], {
+      (0, import_child_process.execFileSync)("icp", ["network", "status", "-e", networkName, "--json"], {
         encoding: "utf-8",
-        stdio: ["ignore", "pipe", "ignore"]
-        // suppress stderr
+        // stderr is piped rather than ignored so a failure can explain itself.
+        // Piping still keeps it off the terminal — it only reaches the user if
+        // the caller decides to print the diagnostics we collect below.
+        stdio: ["ignore", "pipe", "pipe"]
       })
     );
     const rootKey = networkStatus.root_key;
     const proxyTarget = networkStatus.api_url || networkStatus.gateway_url || (networkStatus.port ? `http://127.0.0.1:${networkStatus.port}` : void 0);
     if (!proxyTarget) {
-      return null;
+      diagnostics.push(
+        `\`icp network status -e ${networkName}\` reported no api_url, gateway_url or port`
+      );
+      return { environment: null, diagnostics };
     }
     const canisterIds = {};
     for (const name of canisterNames) {
       try {
         const canisterId = (0, import_child_process.execFileSync)(
           "icp",
-          ["canister", "status", name, "-e", environment, "-i"],
-          { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }
+          ["canister", "status", name, "-e", networkName, "-i"],
+          { encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] }
         ).trim();
         if (canisterId) {
           canisterIds[name] = canisterId;
         }
-      } catch {
+      } catch (error) {
+        diagnostics.push(
+          `\`icp canister status ${name} -e ${networkName}\` failed: ${describeExecError(error)}`
+        );
       }
     }
-    const internetIdentityProvider = !canisterIds.internet_identity && isLocalhostGateway(proxyTarget) && environment !== "ic" ? localInternetIdentityProvider(proxyTarget) : void 0;
+    const internetIdentityProvider = !canisterIds.internet_identity && isLocalhostGateway(proxyTarget) && networkName !== "ic" ? localInternetIdentityProvider(proxyTarget) : void 0;
     return {
-      environment,
-      rootKey,
-      proxyTarget,
-      canisterIds,
-      internetIdentityProvider
+      environment: {
+        environment: networkName,
+        rootKey,
+        proxyTarget,
+        canisterIds,
+        internetIdentityProvider
+      },
+      diagnostics
     };
   } catch (error) {
-    return null;
+    diagnostics.push(
+      `\`icp network status -e ${networkName}\` failed: ${describeExecError(error)}`
+    );
+    return { environment: null, diagnostics };
   }
 }
 function buildIcEnvCookie(canisterIds, rootKey, internetIdentityProvider) {
@@ -89,6 +104,15 @@ function buildIcEnvCookie(canisterIds, rootKey, internetIdentityProvider) {
   }
   return encodeURIComponent(parts.join("&"));
 }
+function describeExecError(error) {
+  const stderr = error?.stderr;
+  const text = typeof stderr === "string" ? stderr : stderr?.toString("utf-8");
+  const trimmed = text?.trim();
+  if (trimmed) {
+    return trimmed;
+  }
+  return error instanceof Error ? error.message : String(error);
+}
 function isLocalhostGateway(proxyTarget) {
   try {
     const { hostname } = new URL(proxyTarget);
@@ -104,40 +128,103 @@ function localInternetIdentityProvider(proxyTarget) {
 }
 
 // src/index.ts
+var PLUGIN_NAME = "ic-reactor-plugin";
+var DEFAULT_LOCAL_REPLICA = "http://127.0.0.1:4943";
 function icReactor(options) {
   const {
     canisters,
     outDir = "src/declarations",
     clientManagerPath = "../../clients",
     target = "react",
-    injectEnvironment = true
+    injectEnvironment = true,
+    failOnError
   } = options;
   const globalConfig = {
     outDir,
     clientManagerPath,
     target
   };
-  const projectRoot = process.cwd();
+  let projectRoot = process.cwd();
+  let command = "build";
+  let devServer = null;
   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])
   );
+  let pendingFailure = null;
+  const reportFailure = (server, message, cause) => {
+    console.error(`[ic-reactor] ${message}`);
+    const err = {
+      message: `[ic-reactor] ${message}`,
+      stack: cause instanceof Error && cause.stack ? cause.stack : "",
+      plugin: PLUGIN_NAME
+    };
+    pendingFailure = { message: err.message, stack: err.stack };
+    server?.ws.send({ type: "error", err });
+  };
+  const inFlight = /* @__PURE__ */ new Map();
+  const rerunQueued = /* @__PURE__ */ new Set();
+  const regenerate = (canisterConfig, server) => {
+    const { name } = canisterConfig;
+    const running = inFlight.get(name);
+    if (running) {
+      rerunQueued.add(name);
+      return running;
+    }
+    const run = (0, import_codegen.runCanisterPipeline)({
+      canisterConfig,
+      projectRoot,
+      globalConfig
+    }).then((result) => {
+      if (result.success) {
+        pendingFailure = null;
+        server.ws.send({ type: "full-reload" });
+      } else {
+        reportFailure(
+          server,
+          `Regeneration failed for ${name}: ${result.error ?? "unknown error"}`
+        );
+      }
+    }).catch((error) => {
+      reportFailure(
+        server,
+        `Regeneration failed for ${name}: ${describeError(error)}`,
+        error
+      );
+    }).finally(() => {
+      inFlight.delete(name);
+      if (rerunQueued.delete(name)) {
+        void regenerate(canisterConfig, server);
+      }
+    });
+    inFlight.set(name, run);
+    return run;
+  };
   const plugin = {
-    name: "ic-reactor-plugin",
+    name: PLUGIN_NAME,
     enforce: "pre",
     // Run before other plugins
-    config(_config, { command }) {
-      if (command !== "serve" || !injectEnvironment) {
+    config(_config, { command: viteCommand }) {
+      command = viteCommand;
+      if (viteCommand !== "serve" || !injectEnvironment) {
         return {};
       }
       const canisterNames = canisters.map((c) => c.name).filter((n) => !!n);
       if (!canisterNames.includes("internet_identity")) {
         canisterNames.push("internet_identity");
       }
-      const icEnv = getIcEnvironmentInfo(canisterNames);
+      const { environment: icEnv, diagnostics } = getIcEnvironmentInfo(canisterNames);
       if (!icEnv) {
+        if (canisters.length > 0) {
+          console.warn(
+            `[ic-reactor] Could not detect the local IC environment, falling back to ${DEFAULT_LOCAL_REPLICA}. Canister IDs and the root key will not be injected \u2014 is the local replica running? Re-run with DEBUG=ic-reactor to see the \`icp\` output.`
+          );
+        }
+        for (const diagnostic of diagnostics) {
+          debugLog(diagnostic);
+        }
         const envOnlyCookie = canisters.length === 0 ? buildIcEnvCookie(
           {},
           void 0,
@@ -150,13 +237,26 @@ function icReactor(options) {
             } : void 0,
             proxy: {
               "/api": {
-                target: "http://127.0.0.1:4943",
+                target: DEFAULT_LOCAL_REPLICA,
                 changeOrigin: true
               }
             }
           }
         };
       }
+      const missingCanisterIds = canisters.map((canister) => canister.name).filter((name) => !!name).filter(
+        (name) => !icEnv.canisterIds[name] && !configuredCanisterIds[name]
+      );
+      if (missingCanisterIds.length > 0) {
+        const names = missingCanisterIds.map((name) => `"${name}"`).join(", ");
+        const it = missingCanisterIds.length === 1 ? "it" : "them";
+        console.warn(
+          `[ic-reactor] The local replica is running, but no canister ID could be resolved for ${names}. Deploy ${it} (\`icp deploy\`) \u2014 until then the injected ic_env carries no PUBLIC_CANISTER_ID for ${it} and the app will see an undefined canister id. Re-run with DEBUG=ic-reactor to see the \`icp\` output.`
+        );
+      }
+      for (const diagnostic of diagnostics) {
+        debugLog(diagnostic);
+      }
       const cookieValue = buildIcEnvCookie(
         {
           ...icEnv.canisterIds,
@@ -179,7 +279,19 @@ function icReactor(options) {
         }
       };
     },
+    configResolved(config) {
+      projectRoot = config.root;
+      command = config.command;
+    },
     configureServer(server) {
+      devServer = server;
+      server.ws.on?.("connection", () => {
+        if (!pendingFailure) return;
+        server.ws.send({
+          type: "error",
+          err: { ...pendingFailure, plugin: PLUGIN_NAME }
+        });
+      });
       const didFiles = canisters.map((c) => resolveDidPath(c.didFile));
       server.watcher.add(didFiles);
     },
@@ -187,55 +299,67 @@ function icReactor(options) {
       console.log(
         `[ic-reactor] Generating canister bindings for ${canisters.length} canisters...`
       );
-      await Promise.allSettled(
-        canisters.map(async (canisterConfig) => {
-          try {
-            const result = await (0, import_codegen.runCanisterPipeline)({
-              canisterConfig,
-              projectRoot,
-              globalConfig
-            });
-            if (!result.success) {
-              console.error(
-                `[ic-reactor] Failed to generate ${canisterConfig.name}: ${result.error}`
-              );
-            }
-          } catch (err) {
-            console.error(
-              `[ic-reactor] Error generating ${canisterConfig.name}:`,
-              err
-            );
-          }
-        })
-      );
-    },
-    handleHotUpdate({ file, server }) {
-      if (file.endsWith(".did")) {
-        const affectedCanister = canisters.find((c) => {
-          const configPath = resolveDidPath(c.didFile);
-          return configPath === import_node_path.default.normalize(file);
-        });
-        if (affectedCanister) {
-          console.log(
-            `[ic-reactor] .did file changed: ${affectedCanister.name}. Regenerating...`
-          );
-          (0, import_codegen.runCanisterPipeline)({
-            canisterConfig: affectedCanister,
+      const outcomes = await Promise.allSettled(
+        canisters.map(
+          (canisterConfig) => (0, import_codegen.runCanisterPipeline)({
+            canisterConfig,
             projectRoot,
             globalConfig
-          }).then((result) => {
-            if (result.success) {
-              server.ws.send({ type: "full-reload" });
-            } else {
-              console.error(`[ic-reactor] Regeneration failed: ${result.error}`);
-            }
-          });
+          })
+        )
+      );
+      const failures = outcomes.flatMap((outcome, index) => {
+        const name = canisters[index]?.name ?? `canister #${index}`;
+        if (outcome.status === "rejected") {
+          return [`${name}: ${describeError(outcome.reason)}`];
         }
+        if (!outcome.value.success) {
+          return [`${name}: ${outcome.value.error ?? "unknown error"}`];
+        }
+        return [];
+      });
+      if (failures.length === 0) {
+        return;
+      }
+      const message = `Failed to generate ${failures.length} of ${canisters.length} canisters:
+` + failures.map((failure) => `  - ${failure}`).join("\n");
+      if (failOnError ?? command === "build") {
+        this.error(`[ic-reactor] ${message}`);
       }
+      reportFailure(devServer, message);
+    },
+    handleHotUpdate({ file, server }) {
+      if (!file.endsWith(".did")) {
+        return;
+      }
+      const changedPath = import_node_path.default.normalize(file);
+      const affectedCanister = canisters.find(
+        // Check if changed file matches configured didFile
+        (canister) => resolveDidPath(canister.didFile) === changedPath
+      );
+      if (!affectedCanister) {
+        return;
+      }
+      console.log(
+        `[ic-reactor] .did file changed: ${affectedCanister.name}. Regenerating...`
+      );
+      return regenerate(affectedCanister, server);
     }
   };
   return plugin;
 }
+function describeError(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function debugLog(message) {
+  const enabled = (process.env.DEBUG ?? "").split(",").some((entry) => {
+    const scope = entry.trim();
+    return scope === "*" || scope === "ic-reactor" || scope.startsWith("ic-reactor:");
+  });
+  if (enabled) {
+    console.debug(`[ic-reactor:debug] ${message}`);
+  }
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   icReactor

package/dist/index.d.cts

@@ -1,3 +1,4 @@
+import { Plugin } from 'vite';
 import { CanisterConfig, CodegenTarget } from '@ic-reactor/codegen';
 
 /**
@@ -16,7 +17,7 @@ interface IcReactorPluginOptions {
      */
     canisters: CanisterConfig[];
     /**
-     * Default output directory (relative to project root).
+     * Default output directory (relative to the Vite project root).
      * Default: "src/declarations"
      */
     outDir?: string;
@@ -35,7 +36,17 @@ interface IcReactorPluginOptions {
      * Default: true
      */
     injectEnvironment?: boolean;
+    /**
+     * Abort the Vite run when a canister fails to generate.
+     *
+     * Default: `true` under `vite build`, `false` under `vite dev`. A build that
+     * silently ships the bindings left over from the last successful run is worse
+     * than no build at all, while a dev server has to survive the broken
+     * intermediate states of a `.did` file being edited — there the failure is
+     * reported to the terminal and the browser error overlay instead.
+     */
+    failOnError?: boolean;
 }
-declare function icReactor(options: IcReactorPluginOptions): any;
+declare function icReactor(options: IcReactorPluginOptions): Plugin;
 
 export { type IcReactorPluginOptions, icReactor };

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { Plugin } from 'vite';
 import { CanisterConfig, CodegenTarget } from '@ic-reactor/codegen';
 
 /**
@@ -16,7 +17,7 @@ interface IcReactorPluginOptions {
      */
     canisters: CanisterConfig[];
     /**
-     * Default output directory (relative to project root).
+     * Default output directory (relative to the Vite project root).
      * Default: "src/declarations"
      */
     outDir?: string;
@@ -35,7 +36,17 @@ interface IcReactorPluginOptions {
      * Default: true
      */
     injectEnvironment?: boolean;
+    /**
+     * Abort the Vite run when a canister fails to generate.
+     *
+     * Default: `true` under `vite build`, `false` under `vite dev`. A build that
+     * silently ships the bindings left over from the last successful run is worse
+     * than no build at all, while a dev server has to survive the broken
+     * intermediate states of a `.did` file being edited — there the failure is
+     * reported to the terminal and the browser error overlay instead.
+     */
+    failOnError?: boolean;
 }
-declare function icReactor(options: IcReactorPluginOptions): any;
+declare function icReactor(options: IcReactorPluginOptions): Plugin;
 
 export { type IcReactorPluginOptions, icReactor };