@ic-reactor/codegen 0.7.1 → 0.8.0

package/README.md

@@ -17,6 +17,7 @@ import { runCanisterPipeline } from "@ic-reactor/codegen"
 await runCanisterPipeline({
   canisterConfig: {
     name: "backend",
+    mode: "DisplayReactor",
     didFile: "./backend.did",
   },
   projectRoot: process.cwd(),
@@ -27,12 +28,25 @@ await runCanisterPipeline({
 })
 ```
 
+## Reactor Class Configuration
+
+Set `canisterConfig.mode` to choose the generated reactor class:
+
+- `DisplayReactor` (default)
+- `Reactor`
+- `CandidReactor`
+- `CandidDisplayReactor`
+- `MetadataDisplayReactor`
+
+Codegen now writes two files per canister: a managed `index.generated.ts` implementation that is regenerated on every run, and an `index.ts` entry wrapper. The wrapper is created once, then preserved unless it still matches the default generated wrapper or an older generated scaffold that can be migrated automatically.
+
 ## Generators
 
 You can also use individual generators if you need more granular control:
 
 - **`generateDeclarations`**: Generates `.js` (factory), `.d.ts` (types), and `.did` copy.
-- **`generateReactorFile`**: Generates the `index.ts` file with `DisplayReactor` and hooks.
+- **`generateReactorFile`**: Generates the managed `index.generated.ts` implementation using either `DisplayReactor` or `Reactor`.
+- **`generateReactorEntryFile`**: Generates the stable `index.ts` wrapper that re-exports from `index.generated.ts`.
 - **`generateClientFile`**: Generates a `ClientManager` boilerplate file.
 
 ## Utilities

package/dist/index.cjs

@@ -34,6 +34,7 @@ __export(index_exports, {
   extractMethods: () => extractMethods,
   generateClientFile: () => generateClientFile,
   generateDeclarations: () => generateDeclarations,
+  generateReactorEntryFile: () => generateReactorEntryFile,
   generateReactorFile: () => generateReactorFile,
   getReactorName: () => getReactorName,
   getServiceTypeName: () => getServiceTypeName,
@@ -123,14 +124,35 @@ function getServiceTypeName(canisterName) {
 }
 
 // src/generators/reactor.ts
+function getReactorClassImportSource(reactorClass) {
+  switch (reactorClass) {
+    case "Reactor":
+    case "DisplayReactor":
+      return "@ic-reactor/react";
+    case "CandidReactor":
+    case "CandidDisplayReactor":
+    case "MetadataDisplayReactor":
+      return "@ic-reactor/candid";
+  }
+}
 function generateReactorFile(options) {
-  const { canisterName, didFile, clientManagerPath = "../../clients" } = options;
+  const {
+    canisterName,
+    didFile,
+    clientManagerPath = "../../clients",
+    canisterId,
+    reactorClass = "DisplayReactor"
+  } = options;
   const pascalName = toPascalCase(canisterName);
   const reactorName = getReactorName(canisterName);
   const serviceName = getServiceTypeName(canisterName);
   const baseName = import_node_path2.default.basename(didFile, ".did");
   const declarationsPath = `./declarations/${baseName}`;
-  return `import { DisplayReactor, createActorHooks } from "@ic-reactor/react"
+  const reactorImportSource = getReactorClassImportSource(reactorClass);
+  const canisterIdLine = canisterId ? `  canisterId: ${JSON.stringify(canisterId)},
+` : "";
+  return `import { createActorHooks } from "@ic-reactor/react"
+import { ${reactorClass} } from "${reactorImportSource}"
 import { clientManager } from "${clientManagerPath}"
 import { idlFactory, type _SERVICE } from "${declarationsPath}"
 
@@ -140,12 +162,12 @@ export type ${serviceName} = _SERVICE
  * ${pascalName} Reactor
  *
  * Auto-generated by @ic-reactor/codegen \u2014 do not edit.
- * Re-run \`ic-reactor generate\` (or the Vite plugin) to regenerate.
+ * This file is overwritten whenever generation runs.
  */
-export const ${reactorName} = new DisplayReactor<${serviceName}>({
+export const ${reactorName} = new ${reactorClass}<${serviceName}>({
   clientManager,
   idlFactory,
-  name: "${canisterName}",
+${canisterIdLine}  name: "${canisterName}",
 })
 
 export const {
@@ -158,8 +180,30 @@ export const {
 } = createActorHooks(${reactorName})
 `;
 }
+function generateReactorEntryFile() {
+  return `/**
+ * Canister entrypoint.
+ *
+ * Created once by @ic-reactor/codegen and safe to customize.
+ * Keep the re-export below if you want generated hooks and types to stay in sync.
+ */
+export * from "./index.generated"
+`;
+}
 
 // src/pipeline.ts
+function resolveReactorClass(canisterConfig) {
+  return canisterConfig.mode ?? "DisplayReactor";
+}
+function normalizeFileContent(content) {
+  return content.replace(/\r\n/g, "\n").trim();
+}
+function isLegacyGeneratedIndexFile(content) {
+  return content.includes("Auto-generated by @ic-reactor/codegen") && content.includes("createActorHooks(");
+}
+function isManagedEntryWrapper(content, expectedEntryContent) {
+  return normalizeFileContent(content) === normalizeFileContent(expectedEntryContent);
+}
 async function runCanisterPipeline(options) {
   const { canisterConfig, projectRoot, globalConfig } = options;
   const { name, didFile, clientManagerPath } = canisterConfig;
@@ -198,16 +242,33 @@ async function runCanisterPipeline(options) {
       error: `Declarations step failed: ${err instanceof Error ? err.message : String(err)}`
     };
   }
-  const reactorPath = import_node_path3.default.join(canisterOutDir, "index.ts");
+  const reactorPath = import_node_path3.default.join(canisterOutDir, "index.generated.ts");
+  const entryPath = import_node_path3.default.join(canisterOutDir, "index.ts");
+  const reactorClass = resolveReactorClass(canisterConfig);
   try {
     const reactorContent = generateReactorFile({
       canisterName: name,
       didFile: resolvedDidFile,
-      clientManagerPath: resolvedClientManagerPath
+      clientManagerPath: resolvedClientManagerPath,
+      canisterId: canisterConfig.canisterId,
+      reactorClass
     });
+    const entryContent = generateReactorEntryFile();
     import_node_fs2.default.mkdirSync(canisterOutDir, { recursive: true });
     import_node_fs2.default.writeFileSync(reactorPath, reactorContent);
     files.push({ success: true, filePath: reactorPath });
+    if (!import_node_fs2.default.existsSync(entryPath)) {
+      import_node_fs2.default.writeFileSync(entryPath, entryContent);
+      files.push({ success: true, filePath: entryPath });
+    } else {
+      const existingEntryContent = import_node_fs2.default.readFileSync(entryPath, "utf-8");
+      if (isLegacyGeneratedIndexFile(existingEntryContent) || isManagedEntryWrapper(existingEntryContent, entryContent)) {
+        import_node_fs2.default.writeFileSync(entryPath, entryContent);
+        files.push({ success: true, filePath: entryPath });
+      } else {
+        files.push({ success: true, filePath: entryPath, skipped: true });
+      }
+    }
   } catch (err) {
     files.push({
       success: false,
@@ -289,6 +350,7 @@ export const clientManager = new ClientManager({
   extractMethods,
   generateClientFile,
   generateDeclarations,
+  generateReactorEntryFile,
   generateReactorFile,
   getReactorName,
   getServiceTypeName,

package/dist/index.d.cts

@@ -19,9 +19,15 @@ interface CanisterConfig {
      * Example: "../../clients" → `import { clientManager } from "../../clients"`
      */
     clientManagerPath?: string;
+    /**
+     * Reactor class used for generated hooks in this canister.
+     * Defaults to DisplayReactor for backward compatibility.
+     */
+    mode?: ReactorClassName;
     /** Optional fixed canister ID */
     canisterId?: string;
 }
+type ReactorClassName = "Reactor" | "DisplayReactor" | "CandidReactor" | "CandidDisplayReactor" | "MetadataDisplayReactor";
 /**
  * Top-level codegen / CLI configuration (stored in `ic-reactor.json`).
  */
@@ -62,7 +68,8 @@ interface GeneratorResult {
  * Pipeline steps (in order):
  *  1. Resolve paths (didFile, outDir)
  *  2. Generate declarations (JS + .d.ts + .did copy)
- *  3. Generate reactor file (index.ts)
+ *  3. Generate reactor implementation (`index.generated.ts`)
+ *  4. Create or migrate the user entry (`index.ts`)
  */
 
 interface PipelineOptions {
@@ -186,7 +193,7 @@ declare function declarationsExist(outDir: string, canisterName: string): boolea
 /**
  * Reactor File Generator
  *
- * Generates the main `index.ts` for a canister — a DisplayReactor instance
+ * Generates the managed `index.generated.ts` implementation for a canister
  * plus the full set of typed hooks via `createActorHooks`.
  *
  * Generated output example (for canister "backend"):
@@ -204,6 +211,7 @@ declare function declarationsExist(outDir: string, canisterName: string): boolea
  *     ...
  *   } = createActorHooks(backendReactor)
  */
+
 interface ReactorGeneratorOptions {
     /** Canister name (e.g. "backend") */
     canisterName: string;
@@ -217,11 +225,22 @@ interface ReactorGeneratorOptions {
      * Default: "../../clients"
      */
     clientManagerPath?: string;
+    /** Optional fixed canister ID for the generated reactor */
+    canisterId?: string;
+    /**
+     * Which reactor class should back the generated hooks.
+     * Default: "DisplayReactor" (backward compatible)
+     */
+    reactorClass?: ReactorClassName;
 }
 /**
- * Generate the content of a canister's `index.ts` reactor file.
+ * Generate the content of a canister's managed implementation file.
  */
 declare function generateReactorFile(options: ReactorGeneratorOptions): string;
+/**
+ * Generate the user-facing `index.ts` wrapper content.
+ */
+declare function generateReactorEntryFile(): string;
 
 /**
  * Client Manager Generator
@@ -246,4 +265,4 @@ interface ClientGeneratorOptions {
  */
 declare function generateClientFile(options?: ClientGeneratorOptions): string;
 
-export { type CanisterConfig, type ClientGeneratorOptions, type CodegenConfig, type DeclarationsGeneratorOptions, type DeclarationsGeneratorResult, type GeneratorResult, type MethodInfo, type MethodType, type PipelineOptions, type PipelineResult, type ReactorGeneratorOptions, declarationsExist, extractMethods, generateClientFile, generateDeclarations, generateReactorFile, getReactorName, getServiceTypeName, parseDIDFile, runCanisterPipeline, toPascalCase };
+export { type CanisterConfig, type ClientGeneratorOptions, type CodegenConfig, type DeclarationsGeneratorOptions, type DeclarationsGeneratorResult, type GeneratorResult, type MethodInfo, type MethodType, type PipelineOptions, type PipelineResult, type ReactorClassName, type ReactorGeneratorOptions, declarationsExist, extractMethods, generateClientFile, generateDeclarations, generateReactorEntryFile, generateReactorFile, getReactorName, getServiceTypeName, parseDIDFile, runCanisterPipeline, toPascalCase };

package/dist/index.d.ts

@@ -19,9 +19,15 @@ interface CanisterConfig {
      * Example: "../../clients" → `import { clientManager } from "../../clients"`
      */
     clientManagerPath?: string;
+    /**
+     * Reactor class used for generated hooks in this canister.
+     * Defaults to DisplayReactor for backward compatibility.
+     */
+    mode?: ReactorClassName;
     /** Optional fixed canister ID */
     canisterId?: string;
 }
+type ReactorClassName = "Reactor" | "DisplayReactor" | "CandidReactor" | "CandidDisplayReactor" | "MetadataDisplayReactor";
 /**
  * Top-level codegen / CLI configuration (stored in `ic-reactor.json`).
  */
@@ -62,7 +68,8 @@ interface GeneratorResult {
  * Pipeline steps (in order):
  *  1. Resolve paths (didFile, outDir)
  *  2. Generate declarations (JS + .d.ts + .did copy)
- *  3. Generate reactor file (index.ts)
+ *  3. Generate reactor implementation (`index.generated.ts`)
+ *  4. Create or migrate the user entry (`index.ts`)
  */
 
 interface PipelineOptions {
@@ -186,7 +193,7 @@ declare function declarationsExist(outDir: string, canisterName: string): boolea
 /**
  * Reactor File Generator
  *
- * Generates the main `index.ts` for a canister — a DisplayReactor instance
+ * Generates the managed `index.generated.ts` implementation for a canister
  * plus the full set of typed hooks via `createActorHooks`.
  *
  * Generated output example (for canister "backend"):
@@ -204,6 +211,7 @@ declare function declarationsExist(outDir: string, canisterName: string): boolea
  *     ...
  *   } = createActorHooks(backendReactor)
  */
+
 interface ReactorGeneratorOptions {
     /** Canister name (e.g. "backend") */
     canisterName: string;
@@ -217,11 +225,22 @@ interface ReactorGeneratorOptions {
      * Default: "../../clients"
      */
     clientManagerPath?: string;
+    /** Optional fixed canister ID for the generated reactor */
+    canisterId?: string;
+    /**
+     * Which reactor class should back the generated hooks.
+     * Default: "DisplayReactor" (backward compatible)
+     */
+    reactorClass?: ReactorClassName;
 }
 /**
- * Generate the content of a canister's `index.ts` reactor file.
+ * Generate the content of a canister's managed implementation file.
  */
 declare function generateReactorFile(options: ReactorGeneratorOptions): string;
+/**
+ * Generate the user-facing `index.ts` wrapper content.
+ */
+declare function generateReactorEntryFile(): string;
 
 /**
  * Client Manager Generator
@@ -246,4 +265,4 @@ interface ClientGeneratorOptions {
  */
 declare function generateClientFile(options?: ClientGeneratorOptions): string;
 
-export { type CanisterConfig, type ClientGeneratorOptions, type CodegenConfig, type DeclarationsGeneratorOptions, type DeclarationsGeneratorResult, type GeneratorResult, type MethodInfo, type MethodType, type PipelineOptions, type PipelineResult, type ReactorGeneratorOptions, declarationsExist, extractMethods, generateClientFile, generateDeclarations, generateReactorFile, getReactorName, getServiceTypeName, parseDIDFile, runCanisterPipeline, toPascalCase };
+export { type CanisterConfig, type ClientGeneratorOptions, type CodegenConfig, type DeclarationsGeneratorOptions, type DeclarationsGeneratorResult, type GeneratorResult, type MethodInfo, type MethodType, type PipelineOptions, type PipelineResult, type ReactorClassName, type ReactorGeneratorOptions, declarationsExist, extractMethods, generateClientFile, generateDeclarations, generateReactorEntryFile, generateReactorFile, getReactorName, getServiceTypeName, parseDIDFile, runCanisterPipeline, toPascalCase };

package/dist/index.js

@@ -78,14 +78,35 @@ function getServiceTypeName(canisterName) {
 }
 
 // src/generators/reactor.ts
+function getReactorClassImportSource(reactorClass) {
+  switch (reactorClass) {
+    case "Reactor":
+    case "DisplayReactor":
+      return "@ic-reactor/react";
+    case "CandidReactor":
+    case "CandidDisplayReactor":
+    case "MetadataDisplayReactor":
+      return "@ic-reactor/candid";
+  }
+}
 function generateReactorFile(options) {
-  const { canisterName, didFile, clientManagerPath = "../../clients" } = options;
+  const {
+    canisterName,
+    didFile,
+    clientManagerPath = "../../clients",
+    canisterId,
+    reactorClass = "DisplayReactor"
+  } = options;
   const pascalName = toPascalCase(canisterName);
   const reactorName = getReactorName(canisterName);
   const serviceName = getServiceTypeName(canisterName);
   const baseName = path2.basename(didFile, ".did");
   const declarationsPath = `./declarations/${baseName}`;
-  return `import { DisplayReactor, createActorHooks } from "@ic-reactor/react"
+  const reactorImportSource = getReactorClassImportSource(reactorClass);
+  const canisterIdLine = canisterId ? `  canisterId: ${JSON.stringify(canisterId)},
+` : "";
+  return `import { createActorHooks } from "@ic-reactor/react"
+import { ${reactorClass} } from "${reactorImportSource}"
 import { clientManager } from "${clientManagerPath}"
 import { idlFactory, type _SERVICE } from "${declarationsPath}"
 
@@ -95,12 +116,12 @@ export type ${serviceName} = _SERVICE
  * ${pascalName} Reactor
  *
  * Auto-generated by @ic-reactor/codegen \u2014 do not edit.
- * Re-run \`ic-reactor generate\` (or the Vite plugin) to regenerate.
+ * This file is overwritten whenever generation runs.
  */
-export const ${reactorName} = new DisplayReactor<${serviceName}>({
+export const ${reactorName} = new ${reactorClass}<${serviceName}>({
   clientManager,
   idlFactory,
-  name: "${canisterName}",
+${canisterIdLine}  name: "${canisterName}",
 })
 
 export const {
@@ -113,8 +134,30 @@ export const {
 } = createActorHooks(${reactorName})
 `;
 }
+function generateReactorEntryFile() {
+  return `/**
+ * Canister entrypoint.
+ *
+ * Created once by @ic-reactor/codegen and safe to customize.
+ * Keep the re-export below if you want generated hooks and types to stay in sync.
+ */
+export * from "./index.generated"
+`;
+}
 
 // src/pipeline.ts
+function resolveReactorClass(canisterConfig) {
+  return canisterConfig.mode ?? "DisplayReactor";
+}
+function normalizeFileContent(content) {
+  return content.replace(/\r\n/g, "\n").trim();
+}
+function isLegacyGeneratedIndexFile(content) {
+  return content.includes("Auto-generated by @ic-reactor/codegen") && content.includes("createActorHooks(");
+}
+function isManagedEntryWrapper(content, expectedEntryContent) {
+  return normalizeFileContent(content) === normalizeFileContent(expectedEntryContent);
+}
 async function runCanisterPipeline(options) {
   const { canisterConfig, projectRoot, globalConfig } = options;
   const { name, didFile, clientManagerPath } = canisterConfig;
@@ -153,16 +196,33 @@ async function runCanisterPipeline(options) {
       error: `Declarations step failed: ${err instanceof Error ? err.message : String(err)}`
     };
   }
-  const reactorPath = path3.join(canisterOutDir, "index.ts");
+  const reactorPath = path3.join(canisterOutDir, "index.generated.ts");
+  const entryPath = path3.join(canisterOutDir, "index.ts");
+  const reactorClass = resolveReactorClass(canisterConfig);
   try {
     const reactorContent = generateReactorFile({
       canisterName: name,
       didFile: resolvedDidFile,
-      clientManagerPath: resolvedClientManagerPath
+      clientManagerPath: resolvedClientManagerPath,
+      canisterId: canisterConfig.canisterId,
+      reactorClass
     });
+    const entryContent = generateReactorEntryFile();
     fs2.mkdirSync(canisterOutDir, { recursive: true });
     fs2.writeFileSync(reactorPath, reactorContent);
     files.push({ success: true, filePath: reactorPath });
+    if (!fs2.existsSync(entryPath)) {
+      fs2.writeFileSync(entryPath, entryContent);
+      files.push({ success: true, filePath: entryPath });
+    } else {
+      const existingEntryContent = fs2.readFileSync(entryPath, "utf-8");
+      if (isLegacyGeneratedIndexFile(existingEntryContent) || isManagedEntryWrapper(existingEntryContent, entryContent)) {
+        fs2.writeFileSync(entryPath, entryContent);
+        files.push({ success: true, filePath: entryPath });
+      } else {
+        files.push({ success: true, filePath: entryPath, skipped: true });
+      }
+    }
   } catch (err) {
     files.push({
       success: false,
@@ -243,6 +303,7 @@ export {
   extractMethods,
   generateClientFile,
   generateDeclarations,
+  generateReactorEntryFile,
   generateReactorFile,
   getReactorName,
   getServiceTypeName,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ic-reactor/codegen",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "Shared code generation utilities for IC Reactor",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -37,7 +37,7 @@
     "@ic-reactor/parser": "0.4.6"
   },
   "devDependencies": {
-    "@types/node": "^25.2.3",
+    "@types/node": "^25.3.5",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"

package/src/__snapshots__/reactor.test.ts.snap

@@ -0,0 +1,94 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`Reactor generator > keeps default behavior as DisplayReactor > display-reactor-index 1`] = `
+"import { createActorHooks } from "@ic-reactor/react"
+import { DisplayReactor } from "@ic-reactor/react"
+import { clientManager } from "../../clients"
+import { idlFactory, type _SERVICE } from "./declarations/backend"
+
+export type BackendService = _SERVICE
+
+/**
+ * Backend Reactor
+ *
+ * Auto-generated by @ic-reactor/codegen — do not edit.
+ * This file is overwritten whenever generation runs.
+ */
+export const backendReactor = new DisplayReactor<BackendService>({
+  clientManager,
+  idlFactory,
+  name: "backend",
+})
+
+export const {
+  useActorQuery: useBackendQuery,
+  useActorSuspenseQuery: useBackendSuspenseQuery,
+  useActorInfiniteQuery: useBackendInfiniteQuery,
+  useActorSuspenseInfiniteQuery: useBackendSuspenseInfiniteQuery,
+  useActorMutation: useBackendMutation,
+  useActorMethod: useBackendMethod,
+} = createActorHooks(backendReactor)
+"
+`;
+
+exports[`Reactor generator > supports Reactor mode generation > reactor-index 1`] = `
+"import { createActorHooks } from "@ic-reactor/react"
+import { Reactor } from "@ic-reactor/react"
+import { clientManager } from "../../clients"
+import { idlFactory, type _SERVICE } from "./declarations/workflow_engine"
+
+export type WorkflowEngineService = _SERVICE
+
+/**
+ * WorkflowEngine Reactor
+ *
+ * Auto-generated by @ic-reactor/codegen — do not edit.
+ * This file is overwritten whenever generation runs.
+ */
+export const workflowEngineReactor = new Reactor<WorkflowEngineService>({
+  clientManager,
+  idlFactory,
+  name: "workflow_engine",
+})
+
+export const {
+  useActorQuery: useWorkflowEngineQuery,
+  useActorSuspenseQuery: useWorkflowEngineSuspenseQuery,
+  useActorInfiniteQuery: useWorkflowEngineInfiniteQuery,
+  useActorSuspenseInfiniteQuery: useWorkflowEngineSuspenseInfiniteQuery,
+  useActorMutation: useWorkflowEngineMutation,
+  useActorMethod: useWorkflowEngineMethod,
+} = createActorHooks(workflowEngineReactor)
+"
+`;
+
+exports[`Reactor generator > supports candid reactor subclasses > metadata-display-reactor-index 1`] = `
+"import { createActorHooks } from "@ic-reactor/react"
+import { MetadataDisplayReactor } from "@ic-reactor/candid"
+import { clientManager } from "../../clients"
+import { idlFactory, type _SERVICE } from "./declarations/ledger"
+
+export type LedgerService = _SERVICE
+
+/**
+ * Ledger Reactor
+ *
+ * Auto-generated by @ic-reactor/codegen — do not edit.
+ * This file is overwritten whenever generation runs.
+ */
+export const ledgerReactor = new MetadataDisplayReactor<LedgerService>({
+  clientManager,
+  idlFactory,
+  name: "ledger",
+})
+
+export const {
+  useActorQuery: useLedgerQuery,
+  useActorSuspenseQuery: useLedgerSuspenseQuery,
+  useActorInfiniteQuery: useLedgerInfiniteQuery,
+  useActorSuspenseInfiniteQuery: useLedgerSuspenseInfiniteQuery,
+  useActorMutation: useLedgerMutation,
+  useActorMethod: useLedgerMethod,
+} = createActorHooks(ledgerReactor)
+"
+`;

package/src/generators/index.ts

@@ -11,7 +11,7 @@ export type {
   DeclarationsGeneratorResult,
 } from "./declarations.js"
 
-export { generateReactorFile } from "./reactor.js"
+export { generateReactorFile, generateReactorEntryFile } from "./reactor.js"
 export type { ReactorGeneratorOptions } from "./reactor.js"
 
 export { generateClientFile } from "./client.js"

package/src/generators/reactor.ts

@@ -1,7 +1,7 @@
 /**
  * Reactor File Generator
  *
- * Generates the main `index.ts` for a canister — a DisplayReactor instance
+ * Generates the managed `index.generated.ts` implementation for a canister
  * plus the full set of typed hooks via `createActorHooks`.
  *
  * Generated output example (for canister "backend"):
@@ -22,6 +22,7 @@
 
 import path from "node:path"
 import { toPascalCase, getReactorName, getServiceTypeName } from "../naming.js"
+import type { ReactorClassName } from "../types.js"
 
 export interface ReactorGeneratorOptions {
   /** Canister name (e.g. "backend") */
@@ -36,13 +37,40 @@ export interface ReactorGeneratorOptions {
    * Default: "../../clients"
    */
   clientManagerPath?: string
+  /** Optional fixed canister ID for the generated reactor */
+  canisterId?: string
+  /**
+   * Which reactor class should back the generated hooks.
+   * Default: "DisplayReactor" (backward compatible)
+   */
+  reactorClass?: ReactorClassName
+}
+
+function getReactorClassImportSource(
+  reactorClass: ReactorClassName
+): "@ic-reactor/react" | "@ic-reactor/candid" {
+  switch (reactorClass) {
+    case "Reactor":
+    case "DisplayReactor":
+      return "@ic-reactor/react"
+    case "CandidReactor":
+    case "CandidDisplayReactor":
+    case "MetadataDisplayReactor":
+      return "@ic-reactor/candid"
+  }
 }
 
 /**
- * Generate the content of a canister's `index.ts` reactor file.
+ * Generate the content of a canister's managed implementation file.
  */
 export function generateReactorFile(options: ReactorGeneratorOptions): string {
-  const { canisterName, didFile, clientManagerPath = "../../clients" } = options
+  const {
+    canisterName,
+    didFile,
+    clientManagerPath = "../../clients",
+    canisterId,
+    reactorClass = "DisplayReactor",
+  } = options
 
   const pascalName = toPascalCase(canisterName)
   const reactorName = getReactorName(canisterName)
@@ -51,8 +79,13 @@ export function generateReactorFile(options: ReactorGeneratorOptions): string {
   // Derive the declarations import path from the .did filename
   const baseName = path.basename(didFile, ".did")
   const declarationsPath = `./declarations/${baseName}`
+  const reactorImportSource = getReactorClassImportSource(reactorClass)
+  const canisterIdLine = canisterId
+    ? `  canisterId: ${JSON.stringify(canisterId)},\n`
+    : ""
 
-  return `import { DisplayReactor, createActorHooks } from "@ic-reactor/react"
+  return `import { createActorHooks } from "@ic-reactor/react"
+import { ${reactorClass} } from "${reactorImportSource}"
 import { clientManager } from "${clientManagerPath}"
 import { idlFactory, type _SERVICE } from "${declarationsPath}"
 
@@ -62,12 +95,12 @@ export type ${serviceName} = _SERVICE
  * ${pascalName} Reactor
  *
  * Auto-generated by @ic-reactor/codegen — do not edit.
- * Re-run \`ic-reactor generate\` (or the Vite plugin) to regenerate.
+ * This file is overwritten whenever generation runs.
  */
-export const ${reactorName} = new DisplayReactor<${serviceName}>({
+export const ${reactorName} = new ${reactorClass}<${serviceName}>({
   clientManager,
   idlFactory,
-  name: "${canisterName}",
+${canisterIdLine}  name: "${canisterName}",
 })
 
 export const {
@@ -80,3 +113,17 @@ export const {
 } = createActorHooks(${reactorName})
 `
 }
+
+/**
+ * Generate the user-facing `index.ts` wrapper content.
+ */
+export function generateReactorEntryFile(): string {
+  return `/**
+ * Canister entrypoint.
+ *
+ * Created once by @ic-reactor/codegen and safe to customize.
+ * Keep the re-export below if you want generated hooks and types to stay in sync.
+ */
+export * from "./index.generated"
+`
+}

package/src/index.ts

@@ -6,7 +6,12 @@
  */
 
 // Core Types
-export type { CanisterConfig, CodegenConfig, GeneratorResult } from "./types.js"
+export type {
+  CanisterConfig,
+  CodegenConfig,
+  GeneratorResult,
+  ReactorClassName,
+} from "./types.js"
 
 // Pipeline (Primary Entry Point)
 export { runCanisterPipeline } from "./pipeline.js"

package/src/pipeline.test.ts

@@ -0,0 +1,225 @@
+import fs from "node:fs"
+import os from "node:os"
+import path from "node:path"
+import { afterEach, describe, expect, it } from "vitest"
+import { runCanisterPipeline } from "./pipeline"
+
+describe("Codegen pipeline", () => {
+  const tempDirs: string[] = []
+
+  afterEach(() => {
+    for (const dir of tempDirs) {
+      fs.rmSync(dir, { recursive: true, force: true })
+    }
+    tempDirs.length = 0
+  })
+
+  function createTempProject() {
+    const projectRoot = fs.mkdtempSync(
+      path.join(os.tmpdir(), "ic-reactor-codegen-pipeline-")
+    )
+    tempDirs.push(projectRoot)
+    return projectRoot
+  }
+
+  function writeDid(projectRoot: string, fileName: string) {
+    fs.writeFileSync(
+      path.join(projectRoot, fileName),
+      `service : {
+  greet: (text) -> (text) query;
+}`
+    )
+  }
+
+  it("uses per-canister mode to generate Reactor-based hooks", async () => {
+    const projectRoot = createTempProject()
+    writeDid(projectRoot, "workflow_engine.did")
+
+    const result = await runCanisterPipeline({
+      canisterConfig: {
+        name: "workflow_engine",
+        didFile: "workflow_engine.did",
+        mode: "Reactor",
+      },
+      projectRoot,
+      globalConfig: {
+        outDir: "src/declarations",
+        clientManagerPath: "../../clients",
+      },
+    })
+
+    expect(result.success).toBe(true)
+
+    const indexPath = path.join(
+      projectRoot,
+      "src/declarations/workflow_engine/index.generated.ts"
+    )
+    const generated = fs.readFileSync(indexPath, "utf-8")
+
+    expect(generated).toContain("new Reactor<WorkflowEngineService>")
+    expect(generated).not.toContain("new DisplayReactor<WorkflowEngineService>")
+    expect(
+      fs.readFileSync(
+        path.join(projectRoot, "src/declarations/workflow_engine/index.ts"),
+        "utf-8"
+      )
+    ).toContain('export * from "./index.generated"')
+  })
+
+  it("writes a configured canisterId into the generated reactor", async () => {
+    const projectRoot = createTempProject()
+    writeDid(projectRoot, "workflow.did")
+
+    const result = await runCanisterPipeline({
+      canisterConfig: {
+        name: "workflow",
+        didFile: "workflow.did",
+        canisterId: "yq4ns-hyaaa-aaaap-akbna-cai",
+      },
+      projectRoot,
+      globalConfig: {
+        outDir: "src/declarations",
+        clientManagerPath: "../../clients",
+      },
+    })
+
+    expect(result.success).toBe(true)
+
+    const indexPath = path.join(
+      projectRoot,
+      "src/declarations/workflow/index.generated.ts"
+    )
+    const generated = fs.readFileSync(indexPath, "utf-8")
+
+    expect(generated).toContain('canisterId: "yq4ns-hyaaa-aaaap-akbna-cai"')
+    expect(generated).toContain('name: "workflow"')
+  })
+
+  it("does not overwrite user-modified index.ts on regenerate", async () => {
+    const projectRoot = createTempProject()
+    writeDid(projectRoot, "backend.did")
+
+    const options = {
+      canisterConfig: {
+        name: "backend",
+        didFile: "backend.did",
+      },
+      projectRoot,
+      globalConfig: {
+        outDir: "src/declarations",
+        clientManagerPath: "../../clients",
+      },
+    } as const
+
+    const first = await runCanisterPipeline(options)
+    expect(first.success).toBe(true)
+
+    const indexPath = path.join(
+      projectRoot,
+      "src/declarations/backend/index.ts"
+    )
+    fs.writeFileSync(
+      indexPath,
+      `// user custom canister file
+export const customBackendIndex = true
+`
+    )
+
+    const second = await runCanisterPipeline({
+      ...options,
+      canisterConfig: {
+        ...options.canisterConfig,
+        canisterId: "yq4ns-hyaaa-aaaap-akbna-cai",
+      },
+    })
+    expect(second.success).toBe(true)
+
+    const wrapper = fs.readFileSync(indexPath, "utf-8")
+    expect(wrapper).toContain("customBackendIndex = true")
+    const generatedImpl = fs.readFileSync(
+      path.join(projectRoot, "src/declarations/backend/index.generated.ts"),
+      "utf-8"
+    )
+    expect(generatedImpl).toContain('canisterId: "yq4ns-hyaaa-aaaap-akbna-cai"')
+    expect(second.files).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          filePath: indexPath,
+          skipped: true,
+          success: true,
+        }),
+      ])
+    )
+  })
+
+  it("migrates a legacy generated index.ts to the managed wrapper", async () => {
+    const projectRoot = createTempProject()
+    writeDid(projectRoot, "backend.did")
+
+    const canisterOutDir = path.join(projectRoot, "src/declarations/backend")
+    fs.mkdirSync(canisterOutDir, { recursive: true })
+
+    const existingGeneratedIndex = `import { DisplayReactor, createActorHooks } from "@ic-reactor/react"
+import { clientManager } from "../../clients"
+import { idlFactory, type _SERVICE } from "./declarations/backend"
+
+export type BackendService = _SERVICE
+
+/**
+ * Backend Reactor
+ *
+ * Auto-generated by @ic-reactor/codegen — do not edit.
+ */
+export const backendReactor = new DisplayReactor<BackendService>({
+  clientManager,
+  idlFactory,
+  name: "backend",
+})
+
+export const {
+  useActorQuery: useBackendQuery,
+} = createActorHooks(backendReactor)
+`
+    fs.writeFileSync(
+      path.join(canisterOutDir, "index.ts"),
+      existingGeneratedIndex
+    )
+
+    const result = await runCanisterPipeline({
+      canisterConfig: {
+        name: "backend",
+        didFile: "backend.did",
+      },
+      projectRoot,
+      globalConfig: {
+        outDir: "src/declarations",
+        clientManagerPath: "../../clients",
+      },
+    })
+
+    expect(result.success).toBe(true)
+
+    const indexPath = path.join(canisterOutDir, "index.ts")
+    const entry = fs.readFileSync(indexPath, "utf-8")
+    const generated = fs.readFileSync(
+      path.join(canisterOutDir, "index.generated.ts"),
+      "utf-8"
+    )
+    expect(entry).toContain('export * from "./index.generated"')
+    expect(entry).not.toBe(existingGeneratedIndex)
+    expect(generated).toContain("new DisplayReactor<BackendService>")
+    expect(generated).toContain("useBackendMutation")
+    expect(result.files).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          filePath: path.join(canisterOutDir, "index.generated.ts"),
+          success: true,
+        }),
+        expect.objectContaining({
+          filePath: indexPath,
+          success: true,
+        }),
+      ])
+    )
+  })
+})

package/src/pipeline.ts

@@ -7,14 +7,23 @@
  * Pipeline steps (in order):
  *  1. Resolve paths (didFile, outDir)
  *  2. Generate declarations (JS + .d.ts + .did copy)
- *  3. Generate reactor file (index.ts)
+ *  3. Generate reactor implementation (`index.generated.ts`)
+ *  4. Create or migrate the user entry (`index.ts`)
  */
 
 import fs from "node:fs"
 import path from "node:path"
-import type { CanisterConfig, CodegenConfig, GeneratorResult } from "./types.js"
+import type {
+  CanisterConfig,
+  CodegenConfig,
+  GeneratorResult,
+  ReactorClassName,
+} from "./types.js"
 import { generateDeclarations } from "./generators/declarations.js"
-import { generateReactorFile } from "./generators/reactor.js"
+import {
+  generateReactorEntryFile,
+  generateReactorFile,
+} from "./generators/reactor.js"
 
 export interface PipelineOptions {
   /** Canister name and config */
@@ -30,6 +39,30 @@ export interface PipelineOptions {
   globalConfig: Pick<CodegenConfig, "outDir" | "clientManagerPath">
 }
 
+function resolveReactorClass(canisterConfig: CanisterConfig): ReactorClassName {
+  return canisterConfig.mode ?? "DisplayReactor"
+}
+
+function normalizeFileContent(content: string): string {
+  return content.replace(/\r\n/g, "\n").trim()
+}
+
+function isLegacyGeneratedIndexFile(content: string): boolean {
+  return (
+    content.includes("Auto-generated by @ic-reactor/codegen") &&
+    content.includes("createActorHooks(")
+  )
+}
+
+function isManagedEntryWrapper(
+  content: string,
+  expectedEntryContent: string
+): boolean {
+  return (
+    normalizeFileContent(content) === normalizeFileContent(expectedEntryContent)
+  )
+}
+
 export interface PipelineResult {
   canisterName: string
   success: boolean
@@ -108,19 +141,40 @@ export async function runCanisterPipeline(
 
   // ── Step 2: Reactor file ───────────────────────────────────────────────────
 
-  const reactorPath = path.join(canisterOutDir, "index.ts")
+  const reactorPath = path.join(canisterOutDir, "index.generated.ts")
+  const entryPath = path.join(canisterOutDir, "index.ts")
+  const reactorClass = resolveReactorClass(canisterConfig)
 
   try {
     const reactorContent = generateReactorFile({
       canisterName: name,
       didFile: resolvedDidFile,
       clientManagerPath: resolvedClientManagerPath,
+      canisterId: canisterConfig.canisterId,
+      reactorClass,
     })
+    const entryContent = generateReactorEntryFile()
 
     fs.mkdirSync(canisterOutDir, { recursive: true })
     fs.writeFileSync(reactorPath, reactorContent)
-
     files.push({ success: true, filePath: reactorPath })
+
+    if (!fs.existsSync(entryPath)) {
+      fs.writeFileSync(entryPath, entryContent)
+      files.push({ success: true, filePath: entryPath })
+    } else {
+      const existingEntryContent = fs.readFileSync(entryPath, "utf-8")
+
+      if (
+        isLegacyGeneratedIndexFile(existingEntryContent) ||
+        isManagedEntryWrapper(existingEntryContent, entryContent)
+      ) {
+        fs.writeFileSync(entryPath, entryContent)
+        files.push({ success: true, filePath: entryPath })
+      } else {
+        files.push({ success: true, filePath: entryPath, skipped: true })
+      }
+    }
   } catch (err) {
     files.push({
       success: false,

package/src/reactor.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it } from "vitest"
+import { generateReactorEntryFile, generateReactorFile } from "./generators"
+
+describe("Reactor generator", () => {
+  it("keeps default behavior as DisplayReactor", () => {
+    const content = generateReactorFile({
+      canisterName: "backend",
+      didFile: "mock/backend.did",
+      clientManagerPath: "../../clients",
+    })
+
+    expect(content).toMatchSnapshot("display-reactor-index")
+    expect(content).toContain("new DisplayReactor<BackendService>")
+    expect(content).not.toContain("export const BackendReactorMode")
+  })
+
+  it("supports Reactor mode generation", () => {
+    const content = generateReactorFile({
+      canisterName: "workflow_engine",
+      didFile: "mock/workflow_engine.did",
+      reactorClass: "Reactor",
+    })
+
+    expect(content).toMatchSnapshot("reactor-index")
+    expect(content).toContain("new Reactor<WorkflowEngineService>")
+    expect(content).not.toContain("createWorkflowEngineDisplayReactor")
+  })
+
+  it("supports candid reactor subclasses", () => {
+    const content = generateReactorFile({
+      canisterName: "ledger",
+      didFile: "mock/ledger.did",
+      reactorClass: "MetadataDisplayReactor",
+    })
+
+    expect(content).toMatchSnapshot("metadata-display-reactor-index")
+    expect(content).toContain(
+      'import { createActorHooks } from "@ic-reactor/react"'
+    )
+    expect(content).toContain(
+      'import { MetadataDisplayReactor } from "@ic-reactor/candid"'
+    )
+    expect(content).toContain("new MetadataDisplayReactor<LedgerService>")
+  })
+
+  it("writes a fixed canisterId when configured", () => {
+    const content = generateReactorFile({
+      canisterName: "workflow",
+      didFile: "mock/workflow.did",
+      canisterId: "yq4ns-hyaaa-aaaap-akbna-cai",
+    })
+
+    expect(content).toContain('canisterId: "yq4ns-hyaaa-aaaap-akbna-cai"')
+    expect(content).toContain('name: "workflow"')
+  })
+
+  it("generates a stable entry wrapper", () => {
+    const content = generateReactorEntryFile()
+
+    expect(content).toContain('export * from "./index.generated"')
+    expect(content).toContain("safe to customize")
+  })
+})

package/src/types.ts

@@ -24,10 +24,22 @@ export interface CanisterConfig {
    * Example: "../../clients" → `import { clientManager } from "../../clients"`
    */
   clientManagerPath?: string
+  /**
+   * Reactor class used for generated hooks in this canister.
+   * Defaults to DisplayReactor for backward compatibility.
+   */
+  mode?: ReactorClassName
   /** Optional fixed canister ID */
   canisterId?: string
 }
 
+export type ReactorClassName =
+  | "Reactor"
+  | "DisplayReactor"
+  | "CandidReactor"
+  | "CandidDisplayReactor"
+  | "MetadataDisplayReactor"
+
 /**
  * Top-level codegen / CLI configuration (stored in `ic-reactor.json`).
  */