@ic-reactor/vite-plugin 0.12.0 → 0.13.0

package/dist/index.js

@@ -7,44 +7,59 @@ import {
 // src/env.ts
 import { execFileSync } from "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(
-      execFileSync("icp", ["network", "status", "-e", environment, "--json"], {
+      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 = 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) {
@@ -57,6 +72,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);
@@ -72,40 +96,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) => 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])
   );
+  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 = 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,
@@ -118,13 +205,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,
@@ -147,7 +247,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);
     },
@@ -155,55 +267,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 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 === path.normalize(file);
-        });
-        if (affectedCanister) {
-          console.log(
-            `[ic-reactor] .did file changed: ${affectedCanister.name}. Regenerating...`
-          );
-          runCanisterPipeline({
-            canisterConfig: affectedCanister,
+      const outcomes = await Promise.allSettled(
+        canisters.map(
+          (canisterConfig) => 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 = path.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}`);
+  }
+}
 export {
   icReactor
 };

package/llms.txt

@@ -24,11 +24,18 @@ icReactor({
 - Runs codegen on startup and `.did` changes
 - Regenerates declarations + `index.generated.ts`
 - Preserves user-facing `index.ts` wrapper after initial creation
+- Relative paths (`didFile`, `outDir`) resolve against Vite's `config.root`
+- A failed canister fails `vite build`; in `vite dev` it goes to the terminal
+  and the browser error overlay instead
 
 ## Key Options
 
-- `canisters`, `outDir`, `clientManagerPath`, `target`, `mode`, `canisterId`
+- Plugin level: `canisters`, `outDir`, `clientManagerPath`, `target`,
+  `injectEnvironment`, `failOnError`
+- Per canister (inside `canisters[]`): `name`, `didFile`, `outDir`,
+  `clientManagerPath`, `target`, `mode`, `canisterId`
 - `injectEnvironment` for local `ic_env` cookie + `/api` proxy behavior
+- `failOnError` overrides the default (`true` for build, `false` for dev)
 
 ## Best Practices
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ic-reactor/vite-plugin",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Vite plugin for zero-config IC reactor generation from Candid files",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -22,6 +22,8 @@
   "files": [
     "dist",
     "src",
+    "!src/**/*.test.ts",
+    "!src/**/__snapshots__",
     "README.md",
     "llms.txt"
   ],
@@ -48,20 +50,19 @@
   },
   "homepage": "https://ic-reactor.b3pay.net/v3/packages/vite-plugin",
   "dependencies": {
-    "@ic-reactor/codegen": "0.12.0"
+    "@ic-reactor/codegen": "0.13.0"
   },
   "peerDependencies": {
     "vite": "^4.2.0 || ^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0"
   },
   "devDependencies": {
-    "@icp-sdk/bindgen": "^0.4.0",
-    "@types/node": "^26.1.1",
+    "@types/node": "^26.2.0",
     "tsup": "^8.5.1",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"
   },
   "scripts": {
-    "build": "tsup src/index.ts --format esm,cjs --dts --tsconfig tsconfig.json",
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean --tsconfig tsconfig.json",
     "dev": "tsup src/index.ts --format esm,cjs --dts --watch --tsconfig tsconfig.json",
     "test": "vitest run",
     "typecheck": "tsc --noEmit -p tsconfig.typecheck.json"

package/src/env.ts

@@ -15,19 +15,35 @@ export interface IcEnvironment {
   internetIdentityProvider?: string
 }
 
+export interface IcEnvironmentDetection {
+  /** The detected environment, or `null` when `icp` could not answer. */
+  environment: IcEnvironment | null
+  /**
+   * Why detection came back empty or partial — the `icp` stderr where we have
+   * it. Detection failing is routine on a machine with no local replica, so
+   * these are handed back for the caller to log at its own level rather than
+   * printed here.
+   */
+  diagnostics: string[]
+}
+
 /**
  * Detect the IC environment using the `icp` CLI.
  */
 export function getIcEnvironmentInfo(
   canisterNames: string[]
-): IcEnvironment | null {
-  const environment = process.env.ICP_ENVIRONMENT || "local"
+): IcEnvironmentDetection {
+  const networkName = process.env.ICP_ENVIRONMENT || "local"
+  const diagnostics: string[] = []
 
   try {
     const networkStatus = JSON.parse(
-      execFileSync("icp", ["network", "status", "-e", environment, "--json"], {
+      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"],
       })
     )
 
@@ -40,7 +56,10 @@ export function getIcEnvironmentInfo(
         : undefined)
 
     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: Record<string, string> = {}
@@ -49,35 +68,45 @@ export function getIcEnvironmentInfo(
       try {
         const canisterId = 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 {
-        // Canister might not exist or be deployed yet
+      } catch (error) {
+        // Canister might not exist or be deployed yet — expected for
+        // internet_identity, which is added to the lookup list unconditionally.
+        diagnostics.push(
+          `\`icp canister status ${name} -e ${networkName}\` failed: ${describeExecError(error)}`
+        )
       }
     }
 
     const internetIdentityProvider =
       !canisterIds.internet_identity &&
       isLocalhostGateway(proxyTarget) &&
-      environment !== "ic"
+      networkName !== "ic"
         ? localInternetIdentityProvider(proxyTarget)
         : undefined
 
     return {
-      environment,
-      rootKey,
-      proxyTarget,
-      canisterIds,
-      internetIdentityProvider,
+      environment: {
+        environment: networkName,
+        rootKey,
+        proxyTarget,
+        canisterIds,
+        internetIdentityProvider,
+      },
+      diagnostics,
     }
   } catch (error) {
     // CLI not found or failed
-    return null
+    diagnostics.push(
+      `\`icp network status -e ${networkName}\` failed: ${describeExecError(error)}`
+    )
+    return { environment: null, diagnostics }
   }
 }
 
@@ -103,6 +132,25 @@ export function buildIcEnvCookie(
   return encodeURIComponent(parts.join("&"))
 }
 
+/**
+ * Turn whatever `execFileSync` threw into one readable line.
+ *
+ * The interesting part is almost always the captured stderr — the thrown
+ * Error's own message is just "Command failed: icp ..." — but stderr is absent
+ * when the binary itself is missing (ENOENT), so fall back to the message.
+ */
+function describeExecError(error: unknown): string {
+  const stderr = (error as { stderr?: Buffer | string } | undefined)?.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: string): boolean {
   try {
     const { hostname } = new URL(proxyTarget)