@ic-reactor/vite-plugin 0.14.0 → 0.15.1

package/llms.txt

@@ -1,55 +1,156 @@
-# @ic-reactor/vite-plugin — AI Quick Guide
+# @ic-reactor/vite-plugin
 
-Vite integration for automatic IC Reactor generation from `.did` files.
+> Vite plugin that generates typed declarations, a reactor with bound React
+> hooks, and optionally one query or mutation object per method from `.did`
+> files, regenerates on change, and gives `vite dev` the local canister ids
+> and an `/api` proxy to the local replica.
+
+Applies to `@ic-reactor/vite-plugin` 0.15.1.
+
+Read this file from `node_modules/@ic-reactor/vite-plugin/llms.txt` when
+writing code against the installed version. The complete guide for every
+package is https://ic-reactor.b3pay.net/llms-full.txt, and behaviour changes
+are in https://github.com/B3Pay/ic-reactor/blob/main/CHANGELOG.md.
 
 ## Install
 
 ```bash
 pnpm add -D @ic-reactor/vite-plugin
-pnpm add @ic-reactor/react @tanstack/react-query @icp-sdk/core
+pnpm add @ic-reactor/react @icp-sdk/core @tanstack/react-query
 ```
 
-## Minimal Setup
+## Setup and Usage
 
 ```ts
+// vite.config.ts
+import { defineConfig, loadEnv } from "vite"
 import { icReactor } from "@ic-reactor/vite-plugin"
 
-icReactor({
-  canisters: [{ name: "backend", didFile: "./backend/backend.did" }],
+export default defineConfig(({ mode }) => {
+  const env = loadEnv(mode, process.cwd(), "")
+  return {
+    plugins: [
+      icReactor({
+        // outDir: "src/declarations" and clientManagerPath: "../../clients"
+        // by default, so src/clients.ts must export `clientManager`
+        canisters: [
+          {
+            name: "backend",
+            didFile: "./backend/backend.did",
+            factories: true, // also a query or mutation object per method
+            // Used under `vite dev` too, in place of the local id
+            canisterId: env.CANISTER_ID_BACKEND,
+          },
+        ],
+      }),
+    ],
+  }
 })
 ```
 
-## Behavior
+```tsx
+// src/App.tsx: the generated entry is src/declarations/backend/index.ts
+import { getPostsQuery, useBackendMutation } from "./declarations/backend"
+
+export function Posts() {
+  const { data: posts } = getPostsQuery.useQuery()
+  const create = useBackendMutation({
+    functionName: "create_post",
+    invalidateQueries: [getPostsQuery],
+  })
+  return (
+    <button onClick={() => create.mutate(["Hello"])}>
+      {posts?.length ?? 0} posts
+    </button>
+  )
+}
+```
+
+`src/clients.ts` is yours:
+`export const clientManager = new ClientManager({ queryClient })`, with
+`ClientManager` from `@ic-reactor/react` and a `QueryClient` from
+`@tanstack/react-query` (set `retry: reactorRetry` in its query defaults).
+For Internet Identity sign-in, build
+`new AuthenticationManager({ clientManager })` in the same module and export
+`useAuth` from `createAuthHooks(authentication)`; every generated reactor on
+that `clientManager` then calls as the signed-in user.
+
+## When to Use What
+
+| Need                                              | Use                                                    |
+| ------------------------------------------------- | ------------------------------------------------------ |
+| Vite app, `.did` files in the repo                | this plugin                                            |
+| No Vite, or generation as a CI step               | `@ic-reactor/cli`                                      |
+| Query and mutation objects per method             | `factories: true` on the canister entry                |
+| Raw Candid values instead of display values       | `mode: "Reactor"` on the canister entry                |
+| No React                                          | `target: "core"`                                       |
+| Local canister ids and `/api` proxy in `vite dev` | `injectEnvironment` (on by default)                    |
+| A project without a local network                 | `injectEnvironment: false`, so page loads run no `icp` |
+
+## Options
+
+- Plugin level: `canisters` (required), `outDir`, `clientManagerPath`,
+  `target`, `injectEnvironment`, `failOnError`.
+- Per canister: `name` and `didFile` (required), `outDir`,
+  `clientManagerPath`, `target`, `mode`, `canisterId`, `factories`. Relative
+  paths resolve against Vite's `root`.
+- `failOnError` defaults to `true` under `vite build` and `false` under
+  `vite dev`, where a failure goes to the terminal and the browser overlay.
+- Each entry needs its own output directory: a later entry with the same
+  `name` and `outDir` as an earlier one fails.
+
+## Generated Files
 
-- 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
+Per canister, under `<outDir>/<name>/`: `declarations/` (`idlFactory` and
+`_SERVICE`), `index.generated.ts` (`<name>Reactor` and six hooks
+`use<Name>Query`, `use<Name>Mutation`, ...), `index.factories.generated.ts`
+with `factories: true` (`<method>Query`, `<method>Mutation`), and `index.ts`,
+which is created once and then yours. Generation runs on startup and on every
+`.did` change. An edited `index.ts` gets a terminal warning until it
+re-exports `./index.factories.generated`; a warning never fails the build.
 
-## Key Options
+## Local Environment (`injectEnvironment`)
 
-- 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. The
-  consumer side is a positive allowlist: `ClientManager` trusts the cookie — its
-  root key, its Internet Identity provider, and the canister IDs a reactor
-  resolves by name — only for loopback, `localhost`, and dev-container hosts.
-  Serving a dev build over a tunnel or custom domain needs
-  `allowEnvConfig: true` (formerly `allowEnvRootKey`); without it a generated
-  reactor that carries no `canisterId` throws instead of reading one from the
-  cookie — see `packages/core/llms.txt`
-- `failOnError` overrides the default (`true` for build, `false` for dev)
+- Under `vite dev` and `vite preview` the plugin sets the `ic_env` cookie
+  (root key, Internet Identity provider, `PUBLIC_CANISTER_ID:<name>`) on each
+  response and proxies `/api` to the network `icp` reports.
+- While `icp` reports no network or a configured canister has no id, each page
+  load asks `icp` again, so deploying after `vite dev` started needs only a
+  reload. Once every canister resolves, page loads run no `icp` command, and a
+  redeploy into a fresh network needs a restart.
+- An `/api` proxy set by the Vite config or another plugin is left alone.
+- `ClientManager` trusts the cookie only on loopback and `localhost` hosts. A
+  dev build served over a tunnel, Codespaces, Gitpod or a custom domain needs
+  `allowEnvConfig: true` on the `ClientManager`; without it a generated
+  reactor with no `canisterId` throws instead of reading one from the cookie.
+- The cookie does not exist in production: set `canisterId` on every entry
+  whose build is served anywhere else. A set `canisterId` is written into the
+  generated reactor and wins over the local id under `vite dev` too, so take
+  it from the environment (`loadEnv`, as above) when the local and production
+  ids differ, rather than hard-coding the production id.
+- Vitest runs `vite.config.ts` unless a `vitest.config.ts` replaces it, so
+  the plugin generates again when tests run, in mode `test`. Set the
+  `canisterId` variable for that mode too (for example in `.env.test`), or
+  the regenerated reactor has no id and importing it in a test throws
+  `canisterId is required`.
 
-## Best Practices
+## Do Not
 
-- Keep custom code in stable wrapper/factory modules
-- Do not hand-edit generated `index.generated.ts`
+- Edit `index.generated.ts`, `index.factories.generated.ts` or
+  `declarations/`; edit the `.did` or the plugin options.
+- Hand-write per-method `createQuery` / `createMutation` modules; set
+  `factories: true` and customize in `index.ts`.
+- Rely on the `ic_env` cookie outside local development.
+- Point two entries at one output directory.
+- Import generated modules into a React Server Component, or use them per
+  request on a server: they are module scope and import hooks.
 
-## Full References
+## Docs
 
-- Full AI guide: https://ic-reactor.b3pay.net/llms-full.txt
-- Vite plugin docs: https://ic-reactor.b3pay.net/v3/packages/vite-plugin
+- Vite plugin: https://ic-reactor.b3pay.net/v3/packages/vite-plugin.md
+- Quick start: https://ic-reactor.b3pay.net/v3/getting-started/quick-start.md
+- Local development: https://ic-reactor.b3pay.net/v3/getting-started/local-development.md
+- Codegen (factory naming rules): https://ic-reactor.b3pay.net/v3/packages/codegen.md
+- Vite plugin example: https://ic-reactor.b3pay.net/v3/examples/vite-plugin.md
+- Index of all docs: https://ic-reactor.b3pay.net/llms.txt
+- Full guide: https://ic-reactor.b3pay.net/llms-full.txt

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ic-reactor/vite-plugin",
-  "version": "0.14.0",
+  "version": "0.15.1",
   "description": "Vite plugin for zero-config IC reactor generation from Candid files",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -50,7 +50,7 @@
   },
   "homepage": "https://ic-reactor.b3pay.net/v3/packages/vite-plugin",
   "dependencies": {
-    "@ic-reactor/codegen": "0.14.0"
+    "@ic-reactor/codegen": "0.15.1"
   },
   "peerDependencies": {
     "vite": "^4.2.0 || ^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0"

package/src/dev-environment.ts

@@ -0,0 +1,268 @@
+/**
+ * The local IC environment that `vite dev` and `vite preview` inject, kept up
+ * to date while detection is incomplete.
+ *
+ * The dev server usually starts before the canisters are deployed, and
+ * sometimes before the local network is up. Detection used to run once, in the
+ * `config` hook, and its answer was fixed into `server.headers` and
+ * `server.proxy` for the server's lifetime. A canister deployed afterwards
+ * never reached the `ic_env` cookie, and a network started afterwards never
+ * received `/api`, until the dev server was restarted.
+ *
+ * Detection now runs again for each page load while it is incomplete, that is
+ * while `icp` reports no network or a configured canister has no ID. Once
+ * every configured canister has an ID on a detected network it stops, and page
+ * loads run no `icp` command. A redeploy into a fresh network, with new IDs and
+ * a new root key, still needs a restart.
+ */
+
+import type { IncomingMessage, ServerResponse } from "node:http"
+import {
+  buildIcEnvCookie,
+  getIcEnvironmentInfo,
+  type IcEnvironment,
+} from "./env.js"
+
+/** Where `/api` goes while `icp` reports no network. */
+export const DEFAULT_LOCAL_REPLICA = "http://127.0.0.1:4943"
+
+/**
+ * The Internet Identity provider the cookie names when no canister is
+ * configured and `icp` reports no network: icp-cli's built-in one, on its
+ * default port.
+ */
+const DEFAULT_INTERNET_IDENTITY_PROVIDER =
+  "http://id.ai.localhost:8000/authorize"
+
+/** What the dev server injects, from the latest detection. */
+export interface LocalEnvironmentState {
+  /** What `icp` reported, or `null` while it has reported no network. */
+  environment: IcEnvironment | null
+  /** The `ic_env` cookie's value, or `undefined` when no cookie is set. */
+  cookie: string | undefined
+  /** Where the plugin's `/api` proxy sends requests. */
+  proxyTarget: string
+  /** Configured canisters with neither a detected nor a configured ID. */
+  missingCanisterIds: string[]
+  /**
+   * `icp` reported a network and every configured canister has an ID, so
+   * detection does not run again.
+   */
+  complete: boolean
+}
+
+export interface LocalEnvironmentOptions {
+  /** The configured canisters' names. */
+  canisterNames: string[]
+  /** IDs set in the plugin config. They win over detected ones. */
+  configuredCanisterIds: Record<string, string>
+  /** The directory `icp` runs in. */
+  projectRoot: string
+  /** Receives each line that explains why an `icp` command failed. */
+  onDiagnostic: (message: string) => void
+  /**
+   * Called after each detection with the state before it, `undefined` for the
+   * first, and the state after it.
+   */
+  onUpdate?: (
+    previous: LocalEnvironmentState | undefined,
+    next: LocalEnvironmentState
+  ) => void
+}
+
+export interface LocalEnvironment {
+  /** The latest detection's result, once one has finished. */
+  readonly state: LocalEnvironmentState | undefined
+  /**
+   * Ask `icp` again and resolve with the new state. A call while a detection
+   * runs shares it. Never rejects.
+   */
+  detect(): Promise<LocalEnvironmentState>
+}
+
+export function createLocalEnvironment(
+  options: LocalEnvironmentOptions
+): LocalEnvironment {
+  const {
+    canisterNames,
+    configuredCanisterIds,
+    projectRoot,
+    onDiagnostic,
+    onUpdate,
+  } = options
+
+  // Two entries can share a name. internet_identity is looked up as well, but
+  // it is routinely not deployed, so it is not needed for detection to be
+  // complete.
+  const requiredNames = [...new Set(canisterNames)]
+  const lookupNames = requiredNames.includes("internet_identity")
+    ? requiredNames
+    : [...requiredNames, "internet_identity"]
+
+  let state: LocalEnvironmentState | undefined
+  let running: Promise<LocalEnvironmentState> | undefined
+
+  const toState = (
+    environment: IcEnvironment | null
+  ): LocalEnvironmentState => {
+    const canisterIds = {
+      ...environment?.canisterIds,
+      ...configuredCanisterIds,
+    }
+    const missingCanisterIds = requiredNames.filter(
+      (name) => !canisterIds[name]
+    )
+
+    let cookie: string | undefined
+    if (environment) {
+      cookie = buildIcEnvCookie(
+        canisterIds,
+        environment.rootKey,
+        environment.internetIdentityProvider
+      )
+    } else if (requiredNames.length === 0) {
+      // Env-only mode: there are no canister IDs to carry, but the app can
+      // still sign in with icp-cli's built-in Internet Identity.
+      cookie = buildIcEnvCookie(
+        {},
+        undefined,
+        DEFAULT_INTERNET_IDENTITY_PROVIDER
+      )
+    }
+
+    return {
+      environment,
+      cookie,
+      proxyTarget: environment?.proxyTarget ?? DEFAULT_LOCAL_REPLICA,
+      missingCanisterIds,
+      complete: environment !== null && missingCanisterIds.length === 0,
+    }
+  }
+
+  const run = async (): Promise<LocalEnvironmentState> => {
+    const previous = state
+    try {
+      const { environment, diagnostics } = await getIcEnvironmentInfo(
+        lookupNames,
+        projectRoot
+      )
+      diagnostics.forEach(onDiagnostic)
+      state = toState(
+        mergeDetections(previous?.environment ?? null, environment)
+      )
+    } catch (error) {
+      // getIcEnvironmentInfo reports failures in its result. This is for
+      // anything else, which must not fail the page request that waits here.
+      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 ??= run().finally(() => {
+        running = undefined
+      })
+      return running
+    },
+  }
+}
+
+/**
+ * Combine a detection with the one before it.
+ *
+ * `icp` can fail for a moment, during a deploy say. A detection that finds no
+ * network keeps the last one that did, and on the same network, which the
+ * root key identifies, a canister keeps the ID it had. A cookie that works is
+ * not taken away by a command that failed once.
+ */
+function mergeDetections(
+  previous: IcEnvironment | null,
+  next: IcEnvironment | null
+): IcEnvironment | null {
+  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
+      ? undefined
+      : next.internetIdentityProvider,
+  }
+}
+
+/**
+ * Whether `req` loads a page, which is when the app reads the `ic_env` cookie.
+ *
+ * Browsers put `text/html` in the Accept header of a navigation, and not in
+ * that of a script, a stylesheet, a `fetch` call or an HMR request.
+ */
+export function isDocumentRequest(req: IncomingMessage): boolean {
+  if (req.method !== "GET" && req.method !== "HEAD") return false
+  const { accept } = req.headers
+  return typeof accept === "string" && accept.includes("text/html")
+}
+
+/** Add the `ic_env` cookie to `res`, keeping any other cookie set on it. */
+function setIcEnvCookie(res: ServerResponse, value: string): void {
+  const existing = res.getHeader("Set-Cookie")
+  const others = (
+    existing === undefined
+      ? []
+      : Array.isArray(existing)
+        ? existing
+        : [String(existing)]
+  ).filter((cookie) => !cookie.startsWith("ic_env="))
+  const cookie = `ic_env=${value}; Path=/; SameSite=Lax;`
+  res.setHeader("Set-Cookie", others.length > 0 ? [...others, cookie] : cookie)
+}
+
+/**
+ * Connect middleware that sets the `ic_env` cookie on each response.
+ *
+ * For a page load while detection is incomplete, it first asks `icp` again and
+ * waits for the answer, so the page that loads after a deploy already carries
+ * the new ID. Other requests, and every request once detection is complete,
+ * get the cookie from the latest detection without running `icp`.
+ */
+export function icEnvMiddleware(environment: LocalEnvironment) {
+  return (
+    req: IncomingMessage,
+    res: ServerResponse,
+    next: (error?: unknown) => void
+  ): void => {
+    const respond = (state: LocalEnvironmentState | undefined) => {
+      if (state?.cookie !== undefined) setIcEnvCookie(res, state.cookie)
+      next()
+    }
+
+    const { state } = environment
+    if (state?.complete || !isDocumentRequest(req)) {
+      respond(state)
+      return
+    }
+
+    void environment.detect().then(respond)
+  }
+}

package/src/env.ts

@@ -5,7 +5,7 @@
  * and building the `ic_env` cookie for the browser.
  */
 
-import { execFileSync } from "child_process"
+import { execFile } from "child_process"
 
 export interface IcEnvironment {
   environment: string
@@ -27,6 +27,45 @@ export interface IcEnvironmentDetection {
   diagnostics: string[]
 }
 
+/**
+ * How long one `icp` command may run. The dev server runs detection while a
+ * page request waits for it, so a command that never exits must not hold the
+ * page forever.
+ */
+const ICP_TIMEOUT_MS = 10_000
+
+/**
+ * Run `icp` with `args` in `cwd` and resolve with its stdout.
+ *
+ * Asynchronous, so a page request that waits for detection does not block the
+ * dev server's other requests. stderr is captured rather than shown, so a
+ * failure can explain itself: it only reaches the terminal if the caller prints
+ * the diagnostics. stdin is closed, so a command that asks a question fails
+ * instead of waiting for an answer.
+ */
+function runIcp(args: string[], cwd: string): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const child = 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()
+  })
+}
+
 /**
  * Detect the IC environment using the `icp` CLI.
  *
@@ -34,23 +73,19 @@ export interface IcEnvironmentDetection {
  * looking for `icp.yaml` there and in each parent directory, so this has to be
  * the app's root and not wherever the process happened to start.
  */
-export function getIcEnvironmentInfo(
+export async function getIcEnvironmentInfo(
   canisterNames: string[],
   projectRoot: string = process.cwd()
-): IcEnvironmentDetection {
+): Promise<IcEnvironmentDetection> {
   const networkName = process.env.ICP_ENVIRONMENT || "local"
   const diagnostics: string[] = []
 
   try {
     const networkStatus = JSON.parse(
-      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
@@ -70,16 +105,15 @@ export function getIcEnvironmentInfo(
 
     const canisterIds: Record<string, string> = {}
 
+    // One at a time, as icp is run from a terminal. Each command reads the
+    // project's state, and these are not known to be safe to run at once.
     for (const name of canisterNames) {
       try {
-        const canisterId = execFileSync(
-          "icp",
-          ["canister", "status", name, "-e", networkName, "-i"],
-          {
-            cwd: projectRoot,
-            encoding: "utf-8",
-            stdio: ["ignore", "pipe", "pipe"],
-          }
+        const canisterId = (
+          await runIcp(
+            ["canister", "status", name, "-e", networkName, "-i"],
+            projectRoot
+          )
         ).trim()
 
         if (canisterId) {
@@ -143,7 +177,7 @@ export function buildIcEnvCookie(
 }
 
 /**
- * Turn whatever `execFileSync` threw into one readable line.
+ * Turn whatever `icp` failed with 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