@ic-reactor/vite-plugin 0.11.1 → 0.12.0

package/README.md

@@ -31,17 +31,25 @@ export default defineConfig({
 
 ```ts
 // src/clients.ts
-import { ClientManager } from "@ic-reactor/core"
+import { ClientManager } from "@ic-reactor/react"
 import { QueryClient } from "@tanstack/react-query"
 
 export const queryClient = new QueryClient()
 export const clientManager = new ClientManager({
   queryClient,
-  withCanisterEnv: true,
 })
 ```
 
-The plugin generates files under `src/declarations/<canister>/` by default.
+No opt-in flag is needed to pick up the plugin's environment: the plugin sets
+the `ic_env` cookie and `ClientManager` reads it automatically in the browser.
+
+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`).
 
 If you want non-React output, set `target: "core"` and install the matching
 runtime package instead of `@ic-reactor/react`.

package/dist/index.cjs

@@ -49,7 +49,10 @@ function getIcEnvironmentInfo(canisterNames) {
       })
     );
     const rootKey = networkStatus.root_key;
-    const proxyTarget = `http://127.0.0.1:${networkStatus.port}`;
+    const proxyTarget = networkStatus.api_url || networkStatus.gateway_url || (networkStatus.port ? `http://127.0.0.1:${networkStatus.port}` : void 0);
+    if (!proxyTarget) {
+      return null;
+    }
     const canisterIds = {};
     for (const name of canisterNames) {
       try {
@@ -64,18 +67,41 @@ function getIcEnvironmentInfo(canisterNames) {
       } catch {
       }
     }
-    return { environment, rootKey, proxyTarget, canisterIds };
+    const internetIdentityProvider = !canisterIds.internet_identity && isLocalhostGateway(proxyTarget) && environment !== "ic" ? localInternetIdentityProvider(proxyTarget) : void 0;
+    return {
+      environment,
+      rootKey,
+      proxyTarget,
+      canisterIds,
+      internetIdentityProvider
+    };
   } catch (error) {
     return null;
   }
 }
-function buildIcEnvCookie(canisterIds, rootKey) {
-  const parts = [`ic_root_key=${rootKey}`];
+function buildIcEnvCookie(canisterIds, rootKey, internetIdentityProvider) {
+  const parts = rootKey ? [`ic_root_key=${rootKey}`] : [];
   for (const [name, id] of Object.entries(canisterIds)) {
     parts.push(`PUBLIC_CANISTER_ID:${name}=${id}`);
   }
+  if (internetIdentityProvider) {
+    parts.push(`INTERNET_IDENTITY_PROVIDER=${internetIdentityProvider}`);
+  }
   return encodeURIComponent(parts.join("&"));
 }
+function isLocalhostGateway(proxyTarget) {
+  try {
+    const { hostname } = new URL(proxyTarget);
+    return hostname === "localhost" || hostname === "127.0.0.1";
+  } catch {
+    return false;
+  }
+}
+function localInternetIdentityProvider(proxyTarget) {
+  const { protocol, port } = new URL(proxyTarget);
+  const portSuffix = port ? `:${port}` : "";
+  return `${protocol}//id.ai.localhost${portSuffix}/authorize`;
+}
 
 // src/index.ts
 function icReactor(options) {
@@ -112,8 +138,16 @@ function icReactor(options) {
       }
       const icEnv = getIcEnvironmentInfo(canisterNames);
       if (!icEnv) {
+        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: {
               "/api": {
                 target: "http://127.0.0.1:4943",
@@ -128,7 +162,8 @@ function icReactor(options) {
           ...icEnv.canisterIds,
           ...configuredCanisterIds
         },
-        icEnv.rootKey
+        icEnv.rootKey,
+        icEnv.internetIdentityProvider
       );
       return {
         server: {

package/dist/index.js

@@ -17,7 +17,10 @@ function getIcEnvironmentInfo(canisterNames) {
       })
     );
     const rootKey = networkStatus.root_key;
-    const proxyTarget = `http://127.0.0.1:${networkStatus.port}`;
+    const proxyTarget = networkStatus.api_url || networkStatus.gateway_url || (networkStatus.port ? `http://127.0.0.1:${networkStatus.port}` : void 0);
+    if (!proxyTarget) {
+      return null;
+    }
     const canisterIds = {};
     for (const name of canisterNames) {
       try {
@@ -32,18 +35,41 @@ function getIcEnvironmentInfo(canisterNames) {
       } catch {
       }
     }
-    return { environment, rootKey, proxyTarget, canisterIds };
+    const internetIdentityProvider = !canisterIds.internet_identity && isLocalhostGateway(proxyTarget) && environment !== "ic" ? localInternetIdentityProvider(proxyTarget) : void 0;
+    return {
+      environment,
+      rootKey,
+      proxyTarget,
+      canisterIds,
+      internetIdentityProvider
+    };
   } catch (error) {
     return null;
   }
 }
-function buildIcEnvCookie(canisterIds, rootKey) {
-  const parts = [`ic_root_key=${rootKey}`];
+function buildIcEnvCookie(canisterIds, rootKey, internetIdentityProvider) {
+  const parts = rootKey ? [`ic_root_key=${rootKey}`] : [];
   for (const [name, id] of Object.entries(canisterIds)) {
     parts.push(`PUBLIC_CANISTER_ID:${name}=${id}`);
   }
+  if (internetIdentityProvider) {
+    parts.push(`INTERNET_IDENTITY_PROVIDER=${internetIdentityProvider}`);
+  }
   return encodeURIComponent(parts.join("&"));
 }
+function isLocalhostGateway(proxyTarget) {
+  try {
+    const { hostname } = new URL(proxyTarget);
+    return hostname === "localhost" || hostname === "127.0.0.1";
+  } catch {
+    return false;
+  }
+}
+function localInternetIdentityProvider(proxyTarget) {
+  const { protocol, port } = new URL(proxyTarget);
+  const portSuffix = port ? `:${port}` : "";
+  return `${protocol}//id.ai.localhost${portSuffix}/authorize`;
+}
 
 // src/index.ts
 function icReactor(options) {
@@ -80,8 +106,16 @@ function icReactor(options) {
       }
       const icEnv = getIcEnvironmentInfo(canisterNames);
       if (!icEnv) {
+        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: {
               "/api": {
                 target: "http://127.0.0.1:4943",
@@ -96,7 +130,8 @@ function icReactor(options) {
           ...icEnv.canisterIds,
           ...configuredCanisterIds
         },
-        icEnv.rootKey
+        icEnv.rootKey,
+        icEnv.internetIdentityProvider
       );
       return {
         server: {

package/llms.txt

@@ -0,0 +1,41 @@
+# @ic-reactor/vite-plugin — AI Quick Guide
+
+Vite integration for automatic IC Reactor generation from `.did` files.
+
+## Install
+
+```bash
+pnpm add -D @ic-reactor/vite-plugin
+pnpm add @ic-reactor/react @tanstack/react-query @icp-sdk/core
+```
+
+## Minimal Setup
+
+```ts
+import { icReactor } from "@ic-reactor/vite-plugin"
+
+icReactor({
+  canisters: [{ name: "backend", didFile: "./backend/backend.did" }],
+})
+```
+
+## Behavior
+
+- Runs codegen on startup and `.did` changes
+- Regenerates declarations + `index.generated.ts`
+- Preserves user-facing `index.ts` wrapper after initial creation
+
+## Key Options
+
+- `canisters`, `outDir`, `clientManagerPath`, `target`, `mode`, `canisterId`
+- `injectEnvironment` for local `ic_env` cookie + `/api` proxy behavior
+
+## Best Practices
+
+- Keep custom code in stable wrapper/factory modules
+- Do not hand-edit generated `index.generated.ts`
+
+## Full References
+
+- Full AI guide: https://ic-reactor.b3pay.net/llms-full.txt
+- Vite plugin docs: https://ic-reactor.b3pay.net/v3/packages/vite-plugin

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ic-reactor/vite-plugin",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "description": "Vite plugin for zero-config IC reactor generation from Candid files",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -8,14 +8,22 @@
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
-    }
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
   },
   "files": [
     "dist",
-    "src"
+    "src",
+    "README.md",
+    "llms.txt"
   ],
   "keywords": [
     "vite",
@@ -24,7 +32,9 @@
     "candid",
     "ic-reactor",
     "dfinity",
-    "icp"
+    "icp",
+    "llms",
+    "ai-friendly"
   ],
   "author": "Behrad Deylami",
   "license": "MIT",
@@ -36,22 +46,24 @@
   "bugs": {
     "url": "https://github.com/B3Pay/ic-reactor/issues"
   },
+  "homepage": "https://ic-reactor.b3pay.net/v3/packages/vite-plugin",
   "dependencies": {
-    "@ic-reactor/codegen": "0.11.1"
+    "@ic-reactor/codegen": "0.12.0"
   },
   "peerDependencies": {
     "vite": "^4.2.0 || ^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0"
   },
   "devDependencies": {
-    "@icp-sdk/bindgen": "^0.3.0",
-    "@types/node": "^25.5.2",
+    "@icp-sdk/bindgen": "^0.4.0",
+    "@types/node": "^26.1.1",
     "tsup": "^8.5.1",
-    "typescript": "^5.9.3",
-    "vitest": "^4.1.2"
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
   },
   "scripts": {
     "build": "tsup src/index.ts --format esm,cjs --dts --tsconfig tsconfig.json",
     "dev": "tsup src/index.ts --format esm,cjs --dts --watch --tsconfig tsconfig.json",
-    "test": "vitest run"
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit -p tsconfig.typecheck.json"
   }
 }

package/src/env.ts

@@ -12,6 +12,7 @@ export interface IcEnvironment {
   rootKey: string
   proxyTarget: string
   canisterIds: Record<string, string>
+  internetIdentityProvider?: string
 }
 
 /**
@@ -31,8 +32,16 @@ export function getIcEnvironmentInfo(
     )
 
     const rootKey = networkStatus.root_key
-    // Default to localhost:4943 if port strictly needed, but `icp` gives us the port
-    const proxyTarget = `http://127.0.0.1:${networkStatus.port}`
+    const proxyTarget =
+      networkStatus.api_url ||
+      networkStatus.gateway_url ||
+      (networkStatus.port
+        ? `http://127.0.0.1:${networkStatus.port}`
+        : undefined)
+
+    if (!proxyTarget) {
+      return null
+    }
 
     const canisterIds: Record<string, string> = {}
 
@@ -52,7 +61,20 @@ export function getIcEnvironmentInfo(
       }
     }
 
-    return { environment, rootKey, proxyTarget, canisterIds }
+    const internetIdentityProvider =
+      !canisterIds.internet_identity &&
+      isLocalhostGateway(proxyTarget) &&
+      environment !== "ic"
+        ? localInternetIdentityProvider(proxyTarget)
+        : undefined
+
+    return {
+      environment,
+      rootKey,
+      proxyTarget,
+      canisterIds,
+      internetIdentityProvider,
+    }
   } catch (error) {
     // CLI not found or failed
     return null
@@ -65,13 +87,33 @@ export function getIcEnvironmentInfo(
  */
 export function buildIcEnvCookie(
   canisterIds: Record<string, string>,
-  rootKey: string
+  rootKey?: string,
+  internetIdentityProvider?: string
 ): string {
-  const parts = [`ic_root_key=${rootKey}`]
+  const parts = rootKey ? [`ic_root_key=${rootKey}`] : []
 
   for (const [name, id] of Object.entries(canisterIds)) {
     parts.push(`PUBLIC_CANISTER_ID:${name}=${id}`)
   }
 
+  if (internetIdentityProvider) {
+    parts.push(`INTERNET_IDENTITY_PROVIDER=${internetIdentityProvider}`)
+  }
+
   return encodeURIComponent(parts.join("&"))
 }
+
+function isLocalhostGateway(proxyTarget: string): boolean {
+  try {
+    const { hostname } = new URL(proxyTarget)
+    return hostname === "localhost" || hostname === "127.0.0.1"
+  } catch {
+    return false
+  }
+}
+
+function localInternetIdentityProvider(proxyTarget: string): string {
+  const { protocol, port } = new URL(proxyTarget)
+  const portSuffix = port ? `:${port}` : ""
+  return `${protocol}//id.ai.localhost${portSuffix}/authorize`
+}

package/src/index.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect, vi, beforeEach } from "vitest"
-import * as vitePluginModule from "./index"
-import type { IcReactorPluginOptions } from "./index"
+import * as vitePluginModule from "./index.js"
+import type { IcReactorPluginOptions } from "./index.js"
 import path from "path"
 import { execFileSync } from "child_process"
 import { runCanisterPipeline } from "@ic-reactor/codegen"
@@ -150,6 +150,42 @@ describe("icReactor", () => {
       )
     })
 
+    it("should inject built-in local Internet Identity provider when no project II canister is found", () => {
+      ;(execFileSync as any).mockImplementation(
+        (command: string, args: string[], _options: any) => {
+          if (
+            command === "icp" &&
+            args.includes("network") &&
+            args.includes("status")
+          ) {
+            return JSON.stringify({
+              root_key: "mock-root-key",
+              api_url: "http://localhost:8000/",
+            })
+          }
+          if (
+            command === "icp" &&
+            args.includes("canister") &&
+            args.includes("status")
+          ) {
+            if (args.includes("internet_identity")) {
+              throw new Error("system canister is not a project canister")
+            }
+            return "mock-canister-id"
+          }
+          return ""
+        }
+      )
+
+      const plugin = createVitePlugin(mockOptions)
+      const config = (plugin as any).config({}, { command: "serve" })
+
+      expect(config.server.headers["Set-Cookie"]).toContain(
+        "INTERNET_IDENTITY_PROVIDER%3Dhttp%3A%2F%2Fid.ai.localhost%3A8000%2Fauthorize"
+      )
+      expect(config.server.proxy["/api"].target).toBe("http://localhost:8000/")
+    })
+
     it("should fallback to default proxy when icp-cli fails", () => {
       ;(execFileSync as any).mockImplementation(() => {
         throw new Error("Command not found")
@@ -162,6 +198,20 @@ describe("icReactor", () => {
       expect(config.server.proxy["/api"].target).toBe("http://127.0.0.1:4943")
     })
 
+    it("should inject default local II provider in env-only mode when icp-cli project detection fails", () => {
+      ;(execFileSync as any).mockImplementation(() => {
+        throw new Error("project manifest not found")
+      })
+
+      const plugin = createVitePlugin({ canisters: [] })
+      const config = (plugin as any).config({}, { command: "serve" })
+
+      expect(config.server.headers["Set-Cookie"]).toContain(
+        "INTERNET_IDENTITY_PROVIDER%3Dhttp%3A%2F%2Fid.ai.localhost%3A8000%2Fauthorize"
+      )
+      expect(config.server.proxy["/api"].target).toBe("http://127.0.0.1:4943")
+    })
+
     it("should return empty config for build command", () => {
       const plugin = createVitePlugin(mockOptions)
       const config = (plugin as any).config({}, { command: "build" })

package/src/index.ts

@@ -96,9 +96,24 @@ export function icReactor(options: IcReactorPluginOptions): any {
       const icEnv = getIcEnvironmentInfo(canisterNames)
 
       if (!icEnv) {
-        // Fallback: just proxy /api to default local replica
+        const envOnlyCookie =
+          canisters.length === 0
+            ? buildIcEnvCookie(
+                {},
+                undefined,
+                "http://id.ai.localhost:8000/authorize"
+              )
+            : undefined
+
+        // Fallback: proxy /api to default local replica. In env-only mode,
+        // still provide the standard ICP CLI built-in local II URL.
         return {
           server: {
+            headers: envOnlyCookie
+              ? {
+                  "Set-Cookie": `ic_env=${envOnlyCookie}; Path=/; SameSite=Lax;`,
+                }
+              : undefined,
             proxy: {
               "/api": {
                 target: "http://127.0.0.1:4943",
@@ -114,7 +129,8 @@ export function icReactor(options: IcReactorPluginOptions): any {
           ...icEnv.canisterIds,
           ...configuredCanisterIds,
         },
-        icEnv.rootKey
+        icEnv.rootKey,
+        icEnv.internetIdentityProvider
       )
 
       return {