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

package/dist/index.d.cts

@@ -1,38 +1,67 @@
 import { Plugin } from 'vite';
-import { CanisterConfig, CodegenTarget } from '@ic-reactor/codegen';
 
 /**
  * @ic-reactor/vite-plugin
  *
- * Vite plugin that:
- * 1. Generates hooks at build time (using @ic-reactor/codegen pipeline)
- * 2. Injects `ic_env` cookie for local development (via proxy)
- * 3. Hot-reloads when .did files change
+ * Vite plugin for an app built on a candid-core generated module.
+ *
+ * - Generation: at the start of a build or dev server, and when a `.did` file
+ *   changes, it runs `candid-core-cli gen` in a child process (see
+ *   generate.ts) and leaves candid-core's module as the generator wrote it. No
+ *   wrapper files, hooks or reactors are generated.
+ * - Environment: under `vite dev` and `vite preview` it sets the `ic_env`
+ *   cookie and proxies `/api` to the local IC network (see dev-environment.ts).
  */
 
+/**
+ * The options of {@link icReactor}. Every one is optional: with none, the
+ * plugin generates nothing and, under `vite dev`, only injects the local IC
+ * environment, for no canister of the app's.
+ */
 interface IcReactorPluginOptions {
     /**
-     * Canister configurations.
-     * `name` is required for each canister.
-     */
-    canisters: CanisterConfig[];
-    /**
-     * Default output directory (relative to the Vite project root).
-     * Default: "src/declarations"
-     */
-    outDir?: string;
-    /**
-     * Default client manager import path.
-     * Default: "../../clients"
-     */
-    clientManagerPath?: string;
-    /**
-     * Default generated runtime target.
-     * Default: "react"
+     * The app's canisters, by name: the canister's name in the `icp` project,
+     * which is also the name the `ic_env` cookie carries its ID under.
+     *
+     * - `didFile`: the canister's Candid interface, relative to the Vite root.
+     *   The plugin runs `candid-core-cli gen` on it at the start of a build or
+     *   dev server and again each time the file changes, regenerating only the
+     *   canisters that name the file that changed. The generator names its
+     *   output after the file, so `didFile: "../backend/ledger.did"` writes `ledger.ts` (the
+     *   module: it exports `actor` and the type `Actor`) and
+     *   `ledger.envelope.json` into `outDir`. Canisters that name the same
+     *   `didFile` and `outDir` share that one module, which is generated once.
+     *   Different `.did` files that would write the same module are refused:
+     *   give one an `outDir` of its own. A canister without a `didFile`
+     *   generates nothing and is only named in the cookie.
+     * - `outDir`: where the generator writes, relative to the Vite root.
+     *   Default: `"src/canisters"`.
+     * - `canisterId`: a fixed ID for the cookie, which wins over the ID `icp`
+     *   reports for the canister.
+     *
+     * The generator is the `@candid-core/cli` the app has installed, run as a
+     * child process so that a failure on one `.did` stops that process and not
+     * the dev server.
      */
-    target?: CodegenTarget;
+    canisters?: Record<string, {
+        didFile?: string;
+        outDir?: string;
+        canisterId?: string;
+    }>;
     /**
-     * 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.
+     *
+     * Never injected in mode `"test"` (Vitest's), where `icp` is not run at all.
+     *
      * Default: true
      */
     injectEnvironment?: boolean;
@@ -40,13 +69,54 @@ interface IcReactorPluginOptions {
      * 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.
+     * 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
+     * logged and shown in the browser's error overlay, and the server keeps
+     * serving.
      */
     failOnError?: boolean;
 }
-declare function icReactor(options: IcReactorPluginOptions): Plugin;
+/**
+ * The Vite plugin for an app built on a candid-core generated module.
+ *
+ * It does two things:
+ *
+ * - **Generates the module.** When a build or the dev server starts, and
+ *   when a configured `.did` changes, it runs the app's `candid-core-cli gen`
+ *   on each `didFile` and leaves the module as the generator wrote it: no
+ *   wrapper files, hooks or reactors. The generator is WebAssembly, so it runs
+ *   in a child process (the running Node binary on the CLI's bin script, never
+ *   through a shell, killed after 60 seconds). A trap, a crash or a hang on a
+ *   bad `.did` then ends that process and not the dev server: under
+ *   `vite build` it fails the build with the CLI's own message, and under
+ *   `vite dev` it is logged and shown in the error overlay while the server
+ *   keeps serving. See {@link IcReactorPluginOptions.failOnError}.
+ * - **Injects the local IC environment.** Under `vite dev` and `vite preview`
+ *   it sets the `ic_env` cookie, which carries the replica's root key and the
+ *   canister IDs, and proxies `/api` to the local replica, so the app needs no
+ *   configuration to find them. It asks the `icp` CLI for both, and is off in
+ *   mode `"test"` (Vitest's), where `icp` is never run.
+ *
+ * The first thing it logs names where an agent reads how to use the library:
+ * `ic-reactor: agent guide at node_modules/@ic-reactor/core/llms.txt`.
+ *
+ * The plugin needs `@candid-core/cli`, at the exact release that pairs with
+ * the `@candid-core/schema` the generated modules import, installed in the
+ * app. It imports neither, and no `@ic-reactor` runtime package.
+ *
+ * @example
+ * ```ts
+ * // vite.config.ts
+ * export default defineConfig({
+ *   plugins: [
+ *     icReactor({
+ *       canisters: { ledger: { didFile: "../backend/ledger.did" } },
+ *     }),
+ *   ],
+ * })
+ * ```
+ */
+declare function icReactor(options?: IcReactorPluginOptions): Plugin;
 
 export { type IcReactorPluginOptions, icReactor };

package/dist/index.d.ts

@@ -1,38 +1,67 @@
 import { Plugin } from 'vite';
-import { CanisterConfig, CodegenTarget } from '@ic-reactor/codegen';
 
 /**
  * @ic-reactor/vite-plugin
  *
- * Vite plugin that:
- * 1. Generates hooks at build time (using @ic-reactor/codegen pipeline)
- * 2. Injects `ic_env` cookie for local development (via proxy)
- * 3. Hot-reloads when .did files change
+ * Vite plugin for an app built on a candid-core generated module.
+ *
+ * - Generation: at the start of a build or dev server, and when a `.did` file
+ *   changes, it runs `candid-core-cli gen` in a child process (see
+ *   generate.ts) and leaves candid-core's module as the generator wrote it. No
+ *   wrapper files, hooks or reactors are generated.
+ * - Environment: under `vite dev` and `vite preview` it sets the `ic_env`
+ *   cookie and proxies `/api` to the local IC network (see dev-environment.ts).
  */
 
+/**
+ * The options of {@link icReactor}. Every one is optional: with none, the
+ * plugin generates nothing and, under `vite dev`, only injects the local IC
+ * environment, for no canister of the app's.
+ */
 interface IcReactorPluginOptions {
     /**
-     * Canister configurations.
-     * `name` is required for each canister.
-     */
-    canisters: CanisterConfig[];
-    /**
-     * Default output directory (relative to the Vite project root).
-     * Default: "src/declarations"
-     */
-    outDir?: string;
-    /**
-     * Default client manager import path.
-     * Default: "../../clients"
-     */
-    clientManagerPath?: string;
-    /**
-     * Default generated runtime target.
-     * Default: "react"
+     * The app's canisters, by name: the canister's name in the `icp` project,
+     * which is also the name the `ic_env` cookie carries its ID under.
+     *
+     * - `didFile`: the canister's Candid interface, relative to the Vite root.
+     *   The plugin runs `candid-core-cli gen` on it at the start of a build or
+     *   dev server and again each time the file changes, regenerating only the
+     *   canisters that name the file that changed. The generator names its
+     *   output after the file, so `didFile: "../backend/ledger.did"` writes `ledger.ts` (the
+     *   module: it exports `actor` and the type `Actor`) and
+     *   `ledger.envelope.json` into `outDir`. Canisters that name the same
+     *   `didFile` and `outDir` share that one module, which is generated once.
+     *   Different `.did` files that would write the same module are refused:
+     *   give one an `outDir` of its own. A canister without a `didFile`
+     *   generates nothing and is only named in the cookie.
+     * - `outDir`: where the generator writes, relative to the Vite root.
+     *   Default: `"src/canisters"`.
+     * - `canisterId`: a fixed ID for the cookie, which wins over the ID `icp`
+     *   reports for the canister.
+     *
+     * The generator is the `@candid-core/cli` the app has installed, run as a
+     * child process so that a failure on one `.did` stops that process and not
+     * the dev server.
      */
-    target?: CodegenTarget;
+    canisters?: Record<string, {
+        didFile?: string;
+        outDir?: string;
+        canisterId?: string;
+    }>;
     /**
-     * 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.
+     *
+     * Never injected in mode `"test"` (Vitest's), where `icp` is not run at all.
+     *
      * Default: true
      */
     injectEnvironment?: boolean;
@@ -40,13 +69,54 @@ interface IcReactorPluginOptions {
      * 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.
+     * 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
+     * logged and shown in the browser's error overlay, and the server keeps
+     * serving.
      */
     failOnError?: boolean;
 }
-declare function icReactor(options: IcReactorPluginOptions): Plugin;
+/**
+ * The Vite plugin for an app built on a candid-core generated module.
+ *
+ * It does two things:
+ *
+ * - **Generates the module.** When a build or the dev server starts, and
+ *   when a configured `.did` changes, it runs the app's `candid-core-cli gen`
+ *   on each `didFile` and leaves the module as the generator wrote it: no
+ *   wrapper files, hooks or reactors. The generator is WebAssembly, so it runs
+ *   in a child process (the running Node binary on the CLI's bin script, never
+ *   through a shell, killed after 60 seconds). A trap, a crash or a hang on a
+ *   bad `.did` then ends that process and not the dev server: under
+ *   `vite build` it fails the build with the CLI's own message, and under
+ *   `vite dev` it is logged and shown in the error overlay while the server
+ *   keeps serving. See {@link IcReactorPluginOptions.failOnError}.
+ * - **Injects the local IC environment.** Under `vite dev` and `vite preview`
+ *   it sets the `ic_env` cookie, which carries the replica's root key and the
+ *   canister IDs, and proxies `/api` to the local replica, so the app needs no
+ *   configuration to find them. It asks the `icp` CLI for both, and is off in
+ *   mode `"test"` (Vitest's), where `icp` is never run.
+ *
+ * The first thing it logs names where an agent reads how to use the library:
+ * `ic-reactor: agent guide at node_modules/@ic-reactor/core/llms.txt`.
+ *
+ * The plugin needs `@candid-core/cli`, at the exact release that pairs with
+ * the `@candid-core/schema` the generated modules import, installed in the
+ * app. It imports neither, and no `@ic-reactor` runtime package.
+ *
+ * @example
+ * ```ts
+ * // vite.config.ts
+ * export default defineConfig({
+ *   plugins: [
+ *     icReactor({
+ *       canisters: { ledger: { didFile: "../backend/ledger.did" } },
+ *     }),
+ *   ],
+ * })
+ * ```
+ */
+declare function icReactor(options?: IcReactorPluginOptions): Plugin;
 
 export { type IcReactorPluginOptions, icReactor };