@ic-reactor/vite-plugin 0.14.0 → 0.15.1

package/dist/index.cjs

@@ -33,24 +33,44 @@ __export(index_exports, {
   icReactor: () => icReactor
 });
 module.exports = __toCommonJS(index_exports);
+var import_node_fs = __toESM(require("fs"), 1);
 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, projectRoot = process.cwd()) {
+var ICP_TIMEOUT_MS = 1e4;
+function runIcp(args, cwd) {
+  return new Promise((resolve, reject) => {
+    const child = (0, import_child_process.execFile)(
+      "icp",
+      args,
+      {
+        cwd,
+        encoding: "utf-8",
+        timeout: ICP_TIMEOUT_MS,
+        windowsHide: true
+      },
+      (error, stdout, stderr) => {
+        if (error) {
+          reject(Object.assign(error, { stderr }));
+        } else {
+          resolve(stdout);
+        }
+      }
+    );
+    child.stdin?.end();
+  });
+}
+async function getIcEnvironmentInfo(canisterNames, projectRoot = process.cwd()) {
   const networkName = process.env.ICP_ENVIRONMENT || "local";
   const diagnostics = [];
   try {
     const networkStatus = JSON.parse(
-      (0, import_child_process.execFileSync)("icp", ["network", "status", "-e", networkName, "--json"], {
-        cwd: projectRoot,
-        encoding: "utf-8",
-        // 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"]
-      })
+      await runIcp(
+        ["network", "status", "-e", networkName, "--json"],
+        projectRoot
+      )
     );
     const rootKey = networkStatus.root_key;
     const proxyTarget = networkStatus.api_url || networkStatus.gateway_url || (networkStatus.port ? `http://127.0.0.1:${networkStatus.port}` : void 0);
@@ -63,15 +83,10 @@ function getIcEnvironmentInfo(canisterNames, projectRoot = process.cwd()) {
     const canisterIds = {};
     for (const name of canisterNames) {
       try {
-        const canisterId = (0, import_child_process.execFileSync)(
-          "icp",
+        const canisterId = (await runIcp(
           ["canister", "status", name, "-e", networkName, "-i"],
-          {
-            cwd: projectRoot,
-            encoding: "utf-8",
-            stdio: ["ignore", "pipe", "pipe"]
-          }
-        ).trim();
+          projectRoot
+        )).trim();
         if (canisterId) {
           canisterIds[name] = canisterId;
         }
@@ -132,9 +147,129 @@ function localInternetIdentityProvider(proxyTarget) {
   return `${protocol}//id.ai.localhost${portSuffix}/authorize`;
 }
 
+// src/dev-environment.ts
+var DEFAULT_LOCAL_REPLICA = "http://127.0.0.1:4943";
+var DEFAULT_INTERNET_IDENTITY_PROVIDER = "http://id.ai.localhost:8000/authorize";
+function createLocalEnvironment(options) {
+  const {
+    canisterNames,
+    configuredCanisterIds,
+    projectRoot,
+    onDiagnostic,
+    onUpdate
+  } = options;
+  const requiredNames = [...new Set(canisterNames)];
+  const lookupNames = requiredNames.includes("internet_identity") ? requiredNames : [...requiredNames, "internet_identity"];
+  let state;
+  let running;
+  const toState = (environment) => {
+    const canisterIds = {
+      ...environment?.canisterIds,
+      ...configuredCanisterIds
+    };
+    const missingCanisterIds = requiredNames.filter(
+      (name) => !canisterIds[name]
+    );
+    let cookie;
+    if (environment) {
+      cookie = buildIcEnvCookie(
+        canisterIds,
+        environment.rootKey,
+        environment.internetIdentityProvider
+      );
+    } else if (requiredNames.length === 0) {
+      cookie = buildIcEnvCookie(
+        {},
+        void 0,
+        DEFAULT_INTERNET_IDENTITY_PROVIDER
+      );
+    }
+    return {
+      environment,
+      cookie,
+      proxyTarget: environment?.proxyTarget ?? DEFAULT_LOCAL_REPLICA,
+      missingCanisterIds,
+      complete: environment !== null && missingCanisterIds.length === 0
+    };
+  };
+  const run = async () => {
+    const previous = state;
+    try {
+      const { environment, diagnostics } = await getIcEnvironmentInfo(
+        lookupNames,
+        projectRoot
+      );
+      diagnostics.forEach(onDiagnostic);
+      state = toState(
+        mergeDetections(previous?.environment ?? null, environment)
+      );
+    } catch (error) {
+      onDiagnostic(
+        `Detecting the local IC environment failed: ${error instanceof Error ? error.message : String(error)}`
+      );
+      state = previous ?? toState(null);
+    }
+    try {
+      onUpdate?.(previous, state);
+    } catch (error) {
+      onDiagnostic(
+        `Applying the detected IC environment failed: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+    return state;
+  };
+  return {
+    get state() {
+      return state;
+    },
+    detect() {
+      running ?? (running = run().finally(() => {
+        running = void 0;
+      }));
+      return running;
+    }
+  };
+}
+function mergeDetections(previous, next) {
+  if (!next) return previous;
+  if (!previous || previous.rootKey !== next.rootKey) return next;
+  const canisterIds = { ...previous.canisterIds, ...next.canisterIds };
+  return {
+    ...next,
+    canisterIds,
+    // The built-in provider stands in only for a project that has no
+    // internet_identity canister, as getIcEnvironmentInfo decides it.
+    internetIdentityProvider: canisterIds.internet_identity ? void 0 : next.internetIdentityProvider
+  };
+}
+function isDocumentRequest(req) {
+  if (req.method !== "GET" && req.method !== "HEAD") return false;
+  const { accept } = req.headers;
+  return typeof accept === "string" && accept.includes("text/html");
+}
+function setIcEnvCookie(res, value) {
+  const existing = res.getHeader("Set-Cookie");
+  const others = (existing === void 0 ? [] : Array.isArray(existing) ? existing : [String(existing)]).filter((cookie2) => !cookie2.startsWith("ic_env="));
+  const cookie = `ic_env=${value}; Path=/; SameSite=Lax;`;
+  res.setHeader("Set-Cookie", others.length > 0 ? [...others, cookie] : cookie);
+}
+function icEnvMiddleware(environment) {
+  return (req, res, next) => {
+    const respond = (state2) => {
+      if (state2?.cookie !== void 0) setIcEnvCookie(res, state2.cookie);
+      next();
+    };
+    const { state } = environment;
+    if (state?.complete || !isDocumentRequest(req)) {
+      respond(state);
+      return;
+    }
+    void environment.detect().then(respond);
+  };
+}
+
 // src/index.ts
 var PLUGIN_NAME = "ic-reactor-plugin";
-var DEFAULT_LOCAL_REPLICA = "http://127.0.0.1:4943";
 function icReactor(options) {
   const {
     canisters,
@@ -151,10 +286,29 @@ function icReactor(options) {
   };
   let projectRoot = process.cwd();
   let command = "build";
+  let localEnvironment;
+  const apiProxyOptions = /* @__PURE__ */ new Set();
   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 generatedFrom = /* @__PURE__ */ new Map();
+  const readDidSource = (canister) => {
+    try {
+      return import_node_fs.default.readFileSync(resolveDidPath(canister.didFile), "utf-8");
+    } catch {
+      return void 0;
+    }
+  };
+  const describeEntry = (canister) => `canisters[${canisters.indexOf(canister)}] (${JSON.stringify(canister.name)})`;
+  const sharedOutDirError = (canister) => {
+    const first = (0, import_codegen.findSharedOutDirs)(
+      canisters.map((entry) => [entry, entry]),
+      outDir,
+      projectRoot
+    ).get(canister);
+    return first === void 0 ? void 0 : (0, import_codegen.sharedOutDirMessage)(describeEntry(canister), describeEntry(first));
+  };
   const configuredCanisterIds = Object.fromEntries(
     canisters.filter((canister) => !!canister.canisterId).map((canister) => [canister.name, canister.canisterId])
   );
@@ -173,22 +327,31 @@ function icReactor(options) {
   const rerunQueued = /* @__PURE__ */ new Set();
   const regenerate = (canisterConfig, server) => {
     const { name } = canisterConfig;
-    const running = inFlight.get(name);
+    const running = inFlight.get(canisterConfig);
     if (running) {
-      rerunQueued.add(name);
+      rerunQueued.add(canisterConfig);
       return running;
     }
+    const sharedError = sharedOutDirError(canisterConfig);
+    if (sharedError !== void 0) {
+      pendingFailures.set(
+        canisterConfig,
+        reportFailure(server, `Regeneration failed for ${sharedError}`)
+      );
+      return Promise.resolve();
+    }
     const run = (0, import_codegen.runCanisterPipeline)({
       canisterConfig,
       projectRoot,
       globalConfig
     }).then((result) => {
+      reportWarnings(name, result.warnings);
       if (result.success) {
-        pendingFailures.delete(name);
+        pendingFailures.delete(canisterConfig);
         server.ws.send({ type: "full-reload" });
       } else {
         pendingFailures.set(
-          name,
+          canisterConfig,
           reportFailure(
             server,
             `Regeneration failed for ${name}: ${result.error ?? "unknown error"}`
@@ -197,7 +360,7 @@ function icReactor(options) {
       }
     }).catch((error) => {
       pendingFailures.set(
-        name,
+        canisterConfig,
         reportFailure(
           server,
           `Regeneration failed for ${name}: ${describeError(error)}`,
@@ -205,81 +368,77 @@ function icReactor(options) {
         )
       );
     }).finally(() => {
-      inFlight.delete(name);
-      if (rerunQueued.delete(name)) {
+      inFlight.delete(canisterConfig);
+      if (rerunQueued.delete(canisterConfig)) {
         void regenerate(canisterConfig, server);
       }
     });
-    inFlight.set(name, run);
+    inFlight.set(canisterConfig, run);
     return run;
   };
+  const regenerateForDid = (file, server) => {
+    if (!file.endsWith(".did")) {
+      return;
+    }
+    const changedPath = import_node_path.default.normalize(file);
+    const affectedCanisters = canisters.filter(
+      (canister) => resolveDidPath(canister.didFile) === changedPath
+    );
+    if (affectedCanisters.length === 0) {
+      return;
+    }
+    console.log(
+      `[ic-reactor] .did file changed: ${affectedCanisters.map((canister) => canister.name).join(", ")}. Regenerating...`
+    );
+    for (const canister of affectedCanisters) {
+      void regenerate(canister, server);
+    }
+  };
   const plugin = {
     name: PLUGIN_NAME,
     enforce: "pre",
     // Run before other plugins
-    config(userConfig, { command: viteCommand }) {
+    async config(userConfig, { 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 { environment: icEnv, diagnostics } = getIcEnvironmentInfo(
-        canisterNames,
-        import_node_path.default.resolve(userConfig.root ?? process.cwd())
-      );
-      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,
-          "http://id.ai.localhost:8000/authorize"
-        ) : void 0;
-        return {
-          server: {
-            headers: envOnlyCookie ? {
-              "Set-Cookie": `ic_env=${envOnlyCookie}; Path=/; SameSite=Lax;`
-            } : void 0,
-            proxy: apiProxy(userConfig, DEFAULT_LOCAL_REPLICA)
+      const ownsApiProxy = !userConfig.server?.proxy?.["/api"];
+      const environment = createLocalEnvironment({
+        canisterNames: canisters.map((canister) => canister.name).filter((name) => !!name),
+        configuredCanisterIds,
+        // `configResolved` has not run yet, so resolve the root the way Vite
+        // will. icp finds the project from the directory it starts in, and
+        // with `vite apps/web` or a `root` option that is not the process cwd.
+        projectRoot: import_node_path.default.resolve(userConfig.root ?? process.cwd()),
+        onDiagnostic: debugLog,
+        onUpdate: (previous, next) => {
+          for (const proxyOptions of apiProxyOptions) {
+            proxyOptions.target = next.proxyTarget;
           }
-        };
-      }
-      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,
-          ...configuredCanisterIds
-        },
-        icEnv.rootKey,
-        icEnv.internetIdentityProvider
-      );
+          if (previous) {
+            reportDetectionProgress(previous, next, apiProxyOptions.size > 0);
+          }
+        }
+      });
+      localEnvironment = environment;
+      const state = await environment.detect();
+      warnAboutIncompleteDetection(state, canisters.length > 0, ownsApiProxy);
       return {
         server: {
-          headers: {
-            "Set-Cookie": `ic_env=${cookieValue}; Path=/; SameSite=Lax;`
-          },
-          proxy: apiProxy(userConfig, icEnv.proxyTarget)
+          // The cookie is not a static `server.headers` entry: the middleware
+          // that configureServer adds sets it per response, from the latest
+          // detection. See dev-environment.ts.
+          proxy: apiProxy(userConfig, state.proxyTarget, (proxyOptions) => {
+            if (proxyOptions.target !== state.proxyTarget) {
+              debugLog(
+                "Another plugin changed the target of the /api proxy, so the plugin leaves that proxy alone."
+              );
+              return;
+            }
+            apiProxyOptions.add(proxyOptions);
+            proxyOptions.target = environment.state?.proxyTarget ?? state.proxyTarget;
+          })
         }
       };
     },
@@ -289,6 +448,9 @@ function icReactor(options) {
     },
     configureServer(server) {
       devServer = server;
+      if (localEnvironment) {
+        server.middlewares.use(icEnvMiddleware(localEnvironment));
+      }
       server.ws.on?.("connection", () => {
         if (pendingFailures.size === 0) return;
         const failures = [...pendingFailures.values()];
@@ -303,29 +465,69 @@ function icReactor(options) {
       });
       const didFiles = canisters.map((c) => resolveDidPath(c.didFile));
       server.watcher.add(didFiles);
+      const onDidEvent = (file) => regenerateForDid(file, server);
+      server.watcher.on("change", onDidEvent);
+      server.watcher.on("add", onDidEvent);
+    },
+    // `vite preview` resolves the config with the `serve` command too, and
+    // used to inherit the cookie from `server.headers`.
+    configurePreviewServer(server) {
+      if (localEnvironment) {
+        server.middlewares.use(icEnvMiddleware(localEnvironment));
+      }
     },
     async buildStart() {
+      for (const canister of canisters) {
+        if (typeof canister.didFile === "string") {
+          this.addWatchFile(resolveDidPath(canister.didFile));
+        }
+      }
+      const sources = canisters.map(readDidSource);
+      const pending = canisters.filter(
+        (canister, index) => !this.meta.watchMode || sources[index] === void 0 || generatedFrom.get(canister) !== sources[index]
+      );
+      if (pending.length === 0) {
+        return;
+      }
       console.log(
-        `[ic-reactor] Generating canister bindings for ${canisters.length} canisters...`
+        `[ic-reactor] Generating canister bindings for ${pending.length} canisters...`
       );
       const outcomes = await Promise.allSettled(
-        canisters.map(
-          (canisterConfig) => (0, import_codegen.runCanisterPipeline)({
+        pending.map((canisterConfig) => {
+          const sharedError = sharedOutDirError(canisterConfig);
+          if (sharedError !== void 0) {
+            return Promise.reject(new SharedOutDirError(sharedError));
+          }
+          return (0, import_codegen.runCanisterPipeline)({
             canisterConfig,
             projectRoot,
             globalConfig
-          })
-        )
+          });
+        })
       );
+      outcomes.forEach((outcome, index) => {
+        const canister = pending[index];
+        const source = sources[canisters.indexOf(canister)];
+        if (outcome.status === "fulfilled") {
+          reportWarnings(canister.name, outcome.value.warnings);
+        }
+        if (outcome.status === "fulfilled" && outcome.value.success && source !== void 0) {
+          generatedFrom.set(canister, source);
+        } else {
+          generatedFrom.delete(canister);
+        }
+      });
       const failures = outcomes.flatMap((outcome, index) => {
-        const name = canisters[index]?.name ?? `canister #${index}`;
+        const canister = pending[index];
+        const name = canister?.name ?? `canister #${index}`;
         if (outcome.status === "rejected") {
-          return [{ name, detail: `${name}: ${describeError(outcome.reason)}` }];
+          const detail = outcome.reason instanceof SharedOutDirError ? outcome.reason.message : `${name}: ${describeError(outcome.reason)}`;
+          return [{ canister, detail }];
         }
         if (!outcome.value.success) {
           return [
             {
-              name,
+              canister,
               detail: `${name}: ${outcome.value.error ?? "unknown error"}`
             }
           ];
@@ -335,51 +537,86 @@ function icReactor(options) {
       if (failures.length === 0) {
         return;
       }
-      const message = `Failed to generate ${failures.length} of ${canisters.length} canisters:
+      const message = `Failed to generate ${failures.length} of ${pending.length} canisters:
 ` + failures.map(({ detail }) => `  - ${detail}`).join("\n");
       if (failOnError ?? command === "build") {
         this.error(`[ic-reactor] ${message}`);
       }
       reportFailure(devServer, message);
-      for (const { name, detail } of failures) {
-        pendingFailures.set(name, {
+      for (const { canister, detail } of failures) {
+        pendingFailures.set(canister, {
           message: `[ic-reactor] Failed to generate ${detail}`,
           stack: ""
         });
       }
-    },
-    handleHotUpdate({ file, server }) {
-      if (!file.endsWith(".did")) {
-        return;
-      }
-      const changedPath = import_node_path.default.normalize(file);
-      const affectedCanisters = canisters.filter(
-        (canister) => resolveDidPath(canister.didFile) === changedPath
-      );
-      if (affectedCanisters.length === 0) {
-        return;
-      }
-      console.log(
-        `[ic-reactor] .did file changed: ${affectedCanisters.map((canister) => canister.name).join(", ")}. Regenerating...`
-      );
-      return Promise.all(
-        affectedCanisters.map((canister) => regenerate(canister, server))
-      ).then(() => void 0);
     }
   };
   return plugin;
 }
+var SharedOutDirError = class extends Error {
+};
+function reportWarnings(name, warnings) {
+  for (const warning of warnings ?? []) {
+    console.warn(`[ic-reactor] ${name}: ${warning}`);
+  }
+}
 function describeError(error) {
   return error instanceof Error ? error.message : String(error);
 }
-function apiProxy(userConfig, target) {
+function apiProxy(userConfig, target, configure) {
   if (userConfig.server?.proxy?.["/api"]) {
     debugLog(
       `The Vite config already proxies /api, so the plugin keeps that proxy instead of sending /api to ${target}.`
     );
     return void 0;
   }
-  return { "/api": { target, changeOrigin: true } };
+  return {
+    "/api": {
+      target,
+      changeOrigin: true,
+      configure: (_proxy, options) => configure(options)
+    }
+  };
+}
+function quoteNames(names) {
+  return names.map((name) => `"${name}"`).join(", ");
+}
+function warnAboutIncompleteDetection(state, hasCanisters, ownsApiProxy) {
+  if (!state.environment) {
+    if (!hasCanisters) return;
+    const proxyNote = ownsApiProxy ? ` and /api goes to ${state.proxyTarget} for now` : "";
+    console.warn(
+      `[ic-reactor] Could not detect the local IC environment, so no ic_env cookie is set${proxyNote}. Is the local network running? The plugin asks \`icp\` again on each page load until it answers${ownsApiProxy ? ", then sends /api to the network it reports" : ""}: start the network (\`icp network start\`) and reload the page. Re-run with DEBUG=ic-reactor to see the \`icp\` output.`
+    );
+    return;
+  }
+  const missing = state.missingCanisterIds;
+  if (missing.length > 0) {
+    const it = missing.length === 1 ? "it" : "them";
+    console.warn(
+      `[ic-reactor] The local replica is running, but no canister ID could be resolved for ${quoteNames(missing)}. Until one is, the ic_env cookie carries no PUBLIC_CANISTER_ID for ${it} and the app will see an undefined canister id. Deploy ${it} (\`icp deploy\`) and reload the page: the plugin asks \`icp\` again on each page load until every configured canister has an ID. Re-run with DEBUG=ic-reactor to see the \`icp\` output.`
+    );
+  }
+}
+function reportDetectionProgress(previous, next, followsApiProxy) {
+  if (!previous.environment && next.environment) {
+    console.log(
+      `[ic-reactor] Detected the local IC network: the ic_env cookie now carries its root key` + (followsApiProxy ? ` and /api goes to ${next.proxyTarget}.` : ".")
+    );
+  }
+  const resolved = previous.missingCanisterIds.filter(
+    (name) => !next.missingCanisterIds.includes(name)
+  );
+  if (next.environment && resolved.length > 0) {
+    console.log(
+      `[ic-reactor] The ic_env cookie now carries the canister ID${resolved.length === 1 ? "" : "s"} for ${quoteNames(resolved)}.`
+    );
+  }
+  if (next.complete && !previous.complete) {
+    console.log(
+      "[ic-reactor] Every configured canister has an ID, so page loads no longer run `icp`. Restart the dev server after redeploying into a fresh network."
+    );
+  }
 }
 function debugLog(message) {
   const enabled = (process.env.DEBUG ?? "").split(",").some((entry) => {

package/dist/index.d.cts

@@ -13,7 +13,9 @@ import { CanisterConfig, CodegenTarget } from '@ic-reactor/codegen';
 interface IcReactorPluginOptions {
     /**
      * Canister configurations.
-     * `name` is required for each canister.
+     * `name` is required for each canister. Set `factories: true` on an entry to
+     * also generate `index.factories.generated.ts`, a query or mutation object
+     * per method bound to the generated reactor; see `CanisterConfig.factories`.
      */
     canisters: CanisterConfig[];
     /**
@@ -32,7 +34,17 @@ interface IcReactorPluginOptions {
      */
     target?: CodegenTarget;
     /**
-     * Automatically inject `ic_env` cookie for local development?
+     * Inject the local IC environment under `vite dev` and `vite preview`: set
+     * the `ic_env` cookie on each response and proxy `/api` to the network the
+     * `icp` CLI reports.
+     *
+     * Until `icp` reports a network and every configured canister has an ID
+     * (a configured `canisterId` counts), each page load asks `icp` again, so a
+     * deploy after the server started needs only a reload. Once detection is
+     * complete, page loads run no `icp` command, and a redeploy into a fresh
+     * network needs a restart. An `/api` proxy that the Vite config or another
+     * plugin sets is left alone.
+     *
      * Default: true
      */
     injectEnvironment?: boolean;

package/dist/index.d.ts

@@ -13,7 +13,9 @@ import { CanisterConfig, CodegenTarget } from '@ic-reactor/codegen';
 interface IcReactorPluginOptions {
     /**
      * Canister configurations.
-     * `name` is required for each canister.
+     * `name` is required for each canister. Set `factories: true` on an entry to
+     * also generate `index.factories.generated.ts`, a query or mutation object
+     * per method bound to the generated reactor; see `CanisterConfig.factories`.
      */
     canisters: CanisterConfig[];
     /**
@@ -32,7 +34,17 @@ interface IcReactorPluginOptions {
      */
     target?: CodegenTarget;
     /**
-     * Automatically inject `ic_env` cookie for local development?
+     * Inject the local IC environment under `vite dev` and `vite preview`: set
+     * the `ic_env` cookie on each response and proxy `/api` to the network the
+     * `icp` CLI reports.
+     *
+     * Until `icp` reports a network and every configured canister has an ID
+     * (a configured `canisterId` counts), each page load asks `icp` again, so a
+     * deploy after the server started needs only a reload. Once detection is
+     * complete, page loads run no `icp` command, and a redeploy into a fresh
+     * network needs a restart. An `/api` proxy that the Vite config or another
+     * plugin sets is left alone.
+     *
      * Default: true
      */
     injectEnvironment?: boolean;