@ic-reactor/vite-plugin 0.15.1 → 4.0.0-beta.1

package/README.md

@@ -1,19 +1,33 @@
 # @ic-reactor/vite-plugin
 
-> **AI coding agents:** read [`llms.txt`](./llms.txt) in this package
-> (`node_modules/@ic-reactor/vite-plugin/llms.txt`) before writing code with it. It
-> is written for the installed version and lists the patterns to use and the
-> mistakes to avoid.
-
-Vite plugin for IC Reactor code generation. It runs the shared
-`@ic-reactor/codegen` pipeline, watches `.did` files, and can inject the
-`ic_env` cookie used by `ClientManager` during local development.
+> **ic-reactor 4 is a prerelease.** `4.0.0-beta.1` is published under npm's
+> `beta` dist-tag, and `latest` stays the 0.15 plugin of the 3.x line until 4.0
+> GA. That plugin, which generates reactor bindings with `@ic-reactor/codegen`,
+> is documented at https://ic-reactor.b3pay.net/v3/packages/vite-plugin.
+
+A Vite plugin for an app built on a module that `candid-core-cli gen` generates
+from a `.did` file. It does two things, and exports only `icReactor` and the
+type `IcReactorPluginOptions`:
+
+- **Generation.** It runs `candid-core-cli gen` on each configured `.did` file
+  when a build or the dev server starts, and again when that file changes. The
+  generated module is candid-core's, as the generator wrote it: the plugin
+  adds no wrapper files, hooks or reactors.
+- **Environment.** Under `vite dev` and `vite preview` it sets the `ic_env`
+  cookie and proxies `/api` to the local IC network, so the app finds its
+  canister IDs and the replica's root key without configuration.
 
 ## Install
 
-```bash
-pnpm add -D @ic-reactor/vite-plugin
-pnpm add @ic-reactor/react @tanstack/react-query @icp-sdk/core
+The plugin runs the `@candid-core/cli` your app installs, and that CLI has to
+pair with the `@candid-core/schema` runtime the generated modules import. Both
+are pinned to one exact release while they are betas, and so is the plugin's
+peer on the CLI:
+
+```sh
+npm install --save-exact @candid-core/schema@0.3.0-beta.1
+npm install --save-dev --save-exact @candid-core/cli@0.2.0-beta.1
+npm install --save-dev @ic-reactor/vite-plugin@beta
 ```
 
 ## Quick Start
@@ -21,156 +35,140 @@ pnpm add @ic-reactor/react @tanstack/react-query @icp-sdk/core
 ```ts
 // vite.config.ts
 import { defineConfig } from "vite"
-import react from "@vitejs/plugin-react"
 import { icReactor } from "@ic-reactor/vite-plugin"
 
 export default defineConfig({
   plugins: [
-    react(),
     icReactor({
-      canisters: [{ name: "backend", didFile: "./backend/backend.did" }],
+      canisters: {
+        ledger: { didFile: "../backend/ledger.did" },
+      },
     }),
   ],
 })
 ```
 
-```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,
-})
-```
-
-No opt-in flag is needed to pick up the plugin's environment in development:
-the plugin sets the `ic_env` cookie and `ClientManager` reads it automatically
-in the browser. That trust stops at the local replica — cookies are not
-origin-isolated, so on a custom domain, on mainnet, and on Codespaces or Gitpod
-(whose workspaces share a parent domain with every other user's) the cookie is
-ignored and a reactor with no `canisterId` throws. Set the per-canister `canisterId` in the
-plugin config to bake it into the generated output for those builds, or pass
-`allowEnvConfig: true` to `ClientManager` if you trust every subdomain of the
-domain you serve from.
-
-The plugin generates files under `src/declarations/<canister>/` by default —
-`declarations/<did-basename>.{js,d.ts,did}` plus a managed `index.generated.ts`
-and a stable `index.ts` wrapper. With `target: "react"`, `index.generated.ts`
-exports the reactor and six hooks named after the canister
-(`use<Canister>Query`, `use<Canister>SuspenseQuery`,
-`use<Canister>InfiniteQuery`, `use<Canister>SuspenseInfiniteQuery`,
-`use<Canister>Mutation`, `use<Canister>Method`).
-
-Set `factories: true` on a canister to also generate
-`index.factories.generated.ts`, a query or mutation object per method bound to
-the generated reactor: `createQuery` for a query method without arguments,
-`createQueryFactory` for one with arguments, and `createMutation` for an
-update or oneway method, named `<method>Query` or `<method>Mutation` with the
-method name in camelCase. The default `index.ts` wrapper re-exports it; an
-`index.ts` you have edited is left alone, and the plugin warns in the terminal
-until it re-exports the factories. It needs `target: "react"`. See
-https://ic-reactor.b3pay.net/v3/packages/codegen#query-and-mutation-factories
-for the naming rule for any method name.
-
-```ts
-import { icReactor } from "@ic-reactor/vite-plugin"
+On `vite dev` and `vite build` this writes `src/canisters/ledger.ts`, the
+generated module (it exports `actor` and the type `Actor`), and
+`src/canisters/ledger.envelope.json` next to it. The generator names its output
+after the `.did` file, not after the key in `canisters`.
 
-icReactor({
-  canisters: [
-    { name: "backend", didFile: "./backend/backend.did", factories: true },
-  ],
-})
-```
+The first line the plugin logs says where an agent reads how to use the
+library: `ic-reactor: agent guide at node_modules/@ic-reactor/core/llms.txt`.
 
-```tsx
-import { getMessageQuery, setMessageMutation } from "./declarations/backend"
+## Options
 
-// In a component
-const { data } = getMessageQuery.useQuery()
+| Option              | Default                   | Meaning                                                                           |
+| ------------------- | ------------------------- | --------------------------------------------------------------------------------- |
+| `canisters`         | `{}`                      | The app's canisters, by their name in the `icp` project; see below                |
+| `injectEnvironment` | `true`                    | Set the cookie and the `/api` proxy under `vite dev` and `vite preview`           |
+| `failOnError`       | build `true`, dev `false` | Abort the Vite run when a canister fails to generate; see "When generation fails" |
 
-// Anywhere, outside React included
-await setMessageMutation.execute(["hello"])
-```
+Each entry of `canisters` takes:
 
-If Prettier resolves from Vite's `config.root`, the plugin formats the
-generated `.js`, `.d.ts`, `index.generated.ts`, `index.factories.generated.ts`
-and the `index.ts` wrapper it writes with it and your Prettier config, so a rebuild leaves formatted,
-committed output unchanged. Without Prettier the declarations hold the Candid
-parser's output followed by a newline, and a formatting error never fails the
-build.
+| Field        | Default           | Meaning                                                                                |
+| ------------ | ----------------- | -------------------------------------------------------------------------------------- |
+| `didFile`    | none              | The canister's Candid file, relative to the Vite root. Without it nothing is generated |
+| `outDir`     | `"src/canisters"` | Where the generator writes, relative to the Vite root                                  |
+| `canisterId` | none              | A fixed ID for the cookie, which wins over the one `icp` reports                       |
 
-If you want non-React output, set `target: "core"` and install the matching
-runtime package instead of `@ic-reactor/react`.
-
-## Options
+Canisters that share one interface share one module. An ICP ledger and a ckBTC
+ledger both on `icrc1.did` are two entries, so that the `ic_env` cookie carries
+each ID, and one generated module:
 
 ```ts
+// vite.config.ts
+import { defineConfig } from "vite"
 import { icReactor } from "@ic-reactor/vite-plugin"
 
-icReactor({
-  canisters: [
-    {
-      name: "backend",
-      didFile: "./backend/backend.did",
-      mode: "DisplayReactor",
-    },
+export default defineConfig({
+  plugins: [
+    icReactor({
+      canisters: {
+        icp_ledger: { didFile: "did/icrc1.did" },
+        ckbtc_ledger: { didFile: "did/icrc1.did" },
+      },
+    }),
   ],
-  outDir: "src/declarations",
-  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`
-- `didFile`
-- `outDir`
-- `clientManagerPath`
-- `target`
-- `mode`
-- `canisterId`
-- `factories`: also generate `index.factories.generated.ts` (default `false`)
-
-Each entry needs an output directory of its own. Two entries with the same
-`name` and no `outDir`, or with `outDir` values that reach one directory, would
-overwrite each other's output, so the plugin generates the first of them and
-fails the later one with the error the CLI reports. To generate one canister
-twice, say as a `DisplayReactor` and as a `Reactor`, give each entry its own
-`outDir`.
-
-Supported `mode` values:
-
-- `Reactor`
-- `DisplayReactor`
-- `CandidReactor`
-- `CandidDisplayReactor`
-- `MetadataDisplayReactor`
-
-Supported `target` values:
-
-- `react` (default): generates the reactor plus bound React hooks
-- `core`: generates only the typed reactor exports with no React dependency
+The generator is given `icrc1.did` once, writes `src/canisters/icrc1.ts` once,
+and a save of the file regenerates it once. (Naming a canister without a
+`didFile` is the same thing when only the cookie is wanted.) Different `.did`
+files that name the same module cannot share an `outDir`: `a/ledger.did` and
+`b/ledger.did` both mean `ledger.ts`, and the second is refused with a message
+naming both. Give one an `outDir` of its own. Names that differ only in case
+(`Ledger.did` and `ledger.did`) collide only where the filesystem of the
+`outDir` ignores case, as macOS and Windows do by default: the plugin checks
+the filesystem and does not refuse them where it tells them apart.
+
+## Generation
+
+The generator is WebAssembly, so the plugin does not load it: it runs the bin
+script of the `@candid-core/cli` installed for your app (resolved from the Vite
+root, so a monorepo's hoisted copy is found) with the running Node binary, in a
+child process and not through a shell. A trap, a crash or a runaway loop on a
+bad `.did` ends that process and the plugin reports it. The dev server is not
+affected.
+
+- Canisters that write into one `outDir` share one process, and each `outDir`
+  has its own. A process that dies without a report is run again, one
+  canister at a time and side by side, so the failure lands on the canister
+  that caused it.
+- A process that runs longer than 60 seconds is killed, and counts as one that
+  died: when it was generating several canisters, each is run again alone and
+  only the one that hangs fails. A hang therefore costs up to two timeouts
+  (120 seconds) before the others are generated.
+- What the generator writes to stderr is logged as a warning, a line at a time
+  and as it arrives, naming the `.did` files its process is generating. With
+  `--json` the generator reports in its JSON document, so what shows up here
+  is a crash's output or a warning from the runtime. When a process fails, its
+  stderr is also in the error message, so that text appears twice. Past 200
+  lines from one process the rest is not logged, so a runaway generator does
+  not flood the terminal.
+- Closing the dev server (or restarting it, as a `vite.config` edit does) kills
+  a generator that is still running and drops the runs still waiting, so none
+  outlives the server it belonged to or runs beside the next one.
+- A declaration the generator cannot represent is left out of the module, and
+  the plugin logs each one as a warning, for example
+  `ic-reactor: ledger: omitted declaration Bad (reserved_field_name)`.
+- Editing a `.did` regenerates only the canisters that name it. Saves that
+  arrive while it runs collapse into one more run. `vite build --watch`
+  regenerates a canister only when its `.did` text changed.
+- Deleting a `.did` under `vite dev` fails the canisters that name it at once,
+  in the log and the overlay: the module it generated is still on disk, and
+  would otherwise look current. Putting the file back regenerates them.
+
+### When generation fails
+
+A failed canister costs that canister, and nothing else:
+
+- Under `vite build` the build fails, with the generator's diagnostics (or its
+  stderr, if it crashed) in the error message. A build that exits 0 would ship
+  the bindings left over from the last good run.
+- Under `vite dev` the failure is logged and shown in the browser's error
+  overlay, and the server keeps serving. The overlay lists the canisters that
+  are still broken: fixing one of several updates it, and fixing the last
+  clears it. Vite's client clears an error overlay whenever it applies a hot
+  update, as it does for Vite's own errors, so a canister that is still broken
+  can drop out of the browser's overlay after you save some other file. Its
+  error stays in the terminal log, and a full reload shows the overlay again.
+- `failOnError` overrides either default.
+
+### In CI
+
+`candid-core-cli gen --check` compares the generated files with the ones on
+disk, writes nothing, and exits 1 on any difference. Run it with the same
+arguments the plugin uses to fail a pipeline when committed output is stale:
+
+```json
+{
+  "scripts": {
+    "gen:check": "candid-core-cli gen ../backend/ledger.did -o src/canisters --check"
+  }
+}
+```
 
 ## Local Development Behavior
 
@@ -178,8 +176,8 @@ When `injectEnvironment` is enabled during `vite dev` or `vite preview`, the
 plugin:
 
 1. asks `icp` for the local network status
-2. resolves canister IDs — `internet_identity` is added automatically if not
-   already in your canister list
+2. resolves canister IDs: the keys of `canisters`, and `internet_identity`,
+   which is added automatically if not already listed
 3. sets the `ic_env` cookie on each response
 4. proxies `/api` to the local replica
 
@@ -213,38 +211,8 @@ If your Vite config or another plugin sets `server.proxy["/api"]`, the plugin
 leaves that entry alone, whether detection succeeds or not, and that proxy does
 not follow detection.
 
-## File Regeneration
-
-On startup and on `.did` file changes, the plugin regenerates declarations and
-the managed `index.generated.ts` implementation, and `index.factories.generated.ts`
-for a canister that sets `factories: true`. 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 plugin follows the dev server's file watcher itself, so a `.did` file that
-appears after the server started, or that a build tool deletes and writes
-again, is generated too, and saves regenerate even with `server.hmr: false`.
-
-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.
-
-`vite build --watch` watches the configured `.did` files as well. Saving one
-starts a rebuild that regenerates that canister's bindings. A rebuild that any
-other file starts leaves the generated files alone.
-
-## When To Use It
-
-- Vite apps with active `.did` iteration
-- teams that want zero extra codegen commands during development
-- projects that want the same output format as the CLI without manual steps
-
-## See Also
+## Tests
 
-- Docs: https://ic-reactor.b3pay.net/v3/packages/vite-plugin
-- `@ic-reactor/codegen`: ../codegen/README.md
-- `@ic-reactor/cli`: ../cli/README.md
+Vitest runs the plugin in mode `test`. There the plugin injects no environment
+and never runs `icp`, whatever `injectEnvironment` says. Generation is not an
+environment concern and still runs, so the modules a test imports exist.