@ic-reactor/codegen 0.7.1 → 0.7.2

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,24 @@ await runCanisterPipeline({
 })
 ```
 
+## Reactor Class Configuration
+
+Set `canisterConfig.mode` to choose the generated reactor class:
+
+- `DisplayReactor` (default)
+- `Reactor`
+- `CandidReactor`
+- `CandidDisplayReactor`
+- `MetadataDisplayReactor`
+
+Codegen writes a single `index.ts`. It overwrites that file only while it is still recognized as a generated file; if you replace it with your own file, regeneration leaves it untouched.
+
 ## 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 `index.ts` file using either `DisplayReactor` or `Reactor`.
 - **`generateClientFile`**: Generates a `ClientManager` boilerplate file.
 
 ## Utilities

package/dist/index.cjs

@@ -123,14 +123,32 @@ 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",
+    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);
+  return `import { createActorHooks } from "@ic-reactor/react"
+import { ${reactorClass} } from "${reactorImportSource}"
 import { clientManager } from "${clientManagerPath}"
 import { idlFactory, type _SERVICE } from "${declarationsPath}"
 
@@ -142,7 +160,7 @@ export type ${serviceName} = _SERVICE
  * Auto-generated by @ic-reactor/codegen \u2014 do not edit.
  * Re-run \`ic-reactor generate\` (or the Vite plugin) to regenerate.
  */
-export const ${reactorName} = new DisplayReactor<${serviceName}>({
+export const ${reactorName} = new ${reactorClass}<${serviceName}>({
   clientManager,
   idlFactory,
   name: "${canisterName}",
@@ -160,6 +178,12 @@ export const {
 }
 
 // src/pipeline.ts
+function resolveReactorClass(canisterConfig) {
+  return canisterConfig.mode ?? "DisplayReactor";
+}
+function isGeneratedIndexFile(content) {
+  return content.includes("Auto-generated by @ic-reactor/codegen") && content.includes("createActorHooks(");
+}
 async function runCanisterPipeline(options) {
   const { canisterConfig, projectRoot, globalConfig } = options;
   const { name, didFile, clientManagerPath } = canisterConfig;
@@ -199,15 +223,27 @@ async function runCanisterPipeline(options) {
     };
   }
   const reactorPath = import_node_path3.default.join(canisterOutDir, "index.ts");
+  const reactorClass = resolveReactorClass(canisterConfig);
   try {
     const reactorContent = generateReactorFile({
       canisterName: name,
       didFile: resolvedDidFile,
-      clientManagerPath: resolvedClientManagerPath
+      clientManagerPath: resolvedClientManagerPath,
+      reactorClass
     });
     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(reactorPath)) {
+      import_node_fs2.default.writeFileSync(reactorPath, reactorContent);
+      files.push({ success: true, filePath: reactorPath });
+    } else {
+      const existingIndexContent = import_node_fs2.default.readFileSync(reactorPath, "utf-8");
+      if (isGeneratedIndexFile(existingIndexContent)) {
+        import_node_fs2.default.writeFileSync(reactorPath, reactorContent);
+        files.push({ success: true, filePath: reactorPath });
+      } else {
+        files.push({ success: true, filePath: reactorPath, skipped: true });
+      }
+    }
   } catch (err) {
     files.push({
       success: false,

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,7 @@ 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 file (`index.ts`)
  */
 
 interface PipelineOptions {
@@ -204,6 +210,7 @@ declare function declarationsExist(outDir: string, canisterName: string): boolea
  *     ...
  *   } = createActorHooks(backendReactor)
  */
+
 interface ReactorGeneratorOptions {
     /** Canister name (e.g. "backend") */
     canisterName: string;
@@ -217,9 +224,14 @@ interface ReactorGeneratorOptions {
      * Default: "../../clients"
      */
     clientManagerPath?: 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 `index.ts` file.
  */
 declare function generateReactorFile(options: ReactorGeneratorOptions): string;
 
@@ -246,4 +258,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, 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,7 @@ 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 file (`index.ts`)
  */
 
 interface PipelineOptions {
@@ -204,6 +210,7 @@ declare function declarationsExist(outDir: string, canisterName: string): boolea
  *     ...
  *   } = createActorHooks(backendReactor)
  */
+
 interface ReactorGeneratorOptions {
     /** Canister name (e.g. "backend") */
     canisterName: string;
@@ -217,9 +224,14 @@ interface ReactorGeneratorOptions {
      * Default: "../../clients"
      */
     clientManagerPath?: 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 `index.ts` file.
  */
 declare function generateReactorFile(options: ReactorGeneratorOptions): string;
 
@@ -246,4 +258,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, generateReactorFile, getReactorName, getServiceTypeName, parseDIDFile, runCanisterPipeline, toPascalCase };

package/dist/index.js

@@ -78,14 +78,32 @@ 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",
+    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);
+  return `import { createActorHooks } from "@ic-reactor/react"
+import { ${reactorClass} } from "${reactorImportSource}"
 import { clientManager } from "${clientManagerPath}"
 import { idlFactory, type _SERVICE } from "${declarationsPath}"
 
@@ -97,7 +115,7 @@ export type ${serviceName} = _SERVICE
  * Auto-generated by @ic-reactor/codegen \u2014 do not edit.
  * Re-run \`ic-reactor generate\` (or the Vite plugin) to regenerate.
  */
-export const ${reactorName} = new DisplayReactor<${serviceName}>({
+export const ${reactorName} = new ${reactorClass}<${serviceName}>({
   clientManager,
   idlFactory,
   name: "${canisterName}",
@@ -115,6 +133,12 @@ export const {
 }
 
 // src/pipeline.ts
+function resolveReactorClass(canisterConfig) {
+  return canisterConfig.mode ?? "DisplayReactor";
+}
+function isGeneratedIndexFile(content) {
+  return content.includes("Auto-generated by @ic-reactor/codegen") && content.includes("createActorHooks(");
+}
 async function runCanisterPipeline(options) {
   const { canisterConfig, projectRoot, globalConfig } = options;
   const { name, didFile, clientManagerPath } = canisterConfig;
@@ -154,15 +178,27 @@ async function runCanisterPipeline(options) {
     };
   }
   const reactorPath = path3.join(canisterOutDir, "index.ts");
+  const reactorClass = resolveReactorClass(canisterConfig);
   try {
     const reactorContent = generateReactorFile({
       canisterName: name,
       didFile: resolvedDidFile,
-      clientManagerPath: resolvedClientManagerPath
+      clientManagerPath: resolvedClientManagerPath,
+      reactorClass
     });
     fs2.mkdirSync(canisterOutDir, { recursive: true });
-    fs2.writeFileSync(reactorPath, reactorContent);
-    files.push({ success: true, filePath: reactorPath });
+    if (!fs2.existsSync(reactorPath)) {
+      fs2.writeFileSync(reactorPath, reactorContent);
+      files.push({ success: true, filePath: reactorPath });
+    } else {
+      const existingIndexContent = fs2.readFileSync(reactorPath, "utf-8");
+      if (isGeneratedIndexFile(existingIndexContent)) {
+        fs2.writeFileSync(reactorPath, reactorContent);
+        files.push({ success: true, filePath: reactorPath });
+      } else {
+        files.push({ success: true, filePath: reactorPath, skipped: true });
+      }
+    }
   } catch (err) {
     files.push({
       success: false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ic-reactor/codegen",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "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.0",
     "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.
+ * Re-run \`ic-reactor generate\` (or the Vite plugin) to regenerate.
+ */
+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.
+ * Re-run \`ic-reactor generate\` (or the Vite plugin) to regenerate.
+ */
+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.
+ * Re-run \`ic-reactor generate\` (or the Vite plugin) to regenerate.
+ */
+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/reactor.ts

@@ -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,37 @@ export interface ReactorGeneratorOptions {
    * Default: "../../clients"
    */
   clientManagerPath?: 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 `index.ts` file.
  */
 export function generateReactorFile(options: ReactorGeneratorOptions): string {
-  const { canisterName, didFile, clientManagerPath = "../../clients" } = options
+  const {
+    canisterName,
+    didFile,
+    clientManagerPath = "../../clients",
+    reactorClass = "DisplayReactor",
+  } = options
 
   const pascalName = toPascalCase(canisterName)
   const reactorName = getReactorName(canisterName)
@@ -51,8 +76,10 @@ 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)
 
-  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}"
 
@@ -64,7 +91,7 @@ export type ${serviceName} = _SERVICE
  * Auto-generated by @ic-reactor/codegen — do not edit.
  * Re-run \`ic-reactor generate\` (or the Vite plugin) to regenerate.
  */
-export const ${reactorName} = new DisplayReactor<${serviceName}>({
+export const ${reactorName} = new ${reactorClass}<${serviceName}>({
   clientManager,
   idlFactory,
   name: "${canisterName}",

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,163 @@
+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.ts"
+    )
+    const generated = fs.readFileSync(indexPath, "utf-8")
+
+    expect(generated).toContain("new Reactor<WorkflowEngineService>")
+    expect(generated).not.toContain("new DisplayReactor<WorkflowEngineService>")
+  })
+
+  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)
+    expect(second.success).toBe(true)
+
+    const wrapper = fs.readFileSync(indexPath, "utf-8")
+    expect(wrapper).toContain("customBackendIndex = true")
+    expect(second.files).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          filePath: indexPath,
+          skipped: true,
+          success: true,
+        }),
+      ])
+    )
+  })
+
+  it("overwrites legacy generated index.ts during regeneration", async () => {
+    const projectRoot = createTempProject()
+    writeDid(projectRoot, "backend.did")
+
+    const canisterOutDir = path.join(projectRoot, "src/declarations/backend")
+    fs.mkdirSync(canisterOutDir, { recursive: true })
+
+    // Simulate a generated index.ts content from older versions.
+    fs.writeFileSync(
+      path.join(canisterOutDir, "index.ts"),
+      `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.
+ * Re-run \`ic-reactor generate\` (or the Vite plugin) to regenerate.
+ */
+export const backendReactor = new DisplayReactor<BackendService>({
+  clientManager,
+  idlFactory,
+  name: "backend",
+})
+
+export const {
+  useActorQuery: useBackendQuery,
+} = createActorHooks(backendReactor)
+`
+    )
+
+    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 generated = fs.readFileSync(indexPath, "utf-8")
+    expect(generated).toContain("new DisplayReactor<BackendService>")
+    expect(generated).toContain("useBackendMutation")
+    expect(generated).not.toContain('export * from "./index.generated"')
+  })
+})

package/src/pipeline.ts

@@ -7,12 +7,17 @@
  * 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 file (`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"
 
@@ -30,6 +35,17 @@ export interface PipelineOptions {
   globalConfig: Pick<CodegenConfig, "outDir" | "clientManagerPath">
 }
 
+function resolveReactorClass(canisterConfig: CanisterConfig): ReactorClassName {
+  return canisterConfig.mode ?? "DisplayReactor"
+}
+
+function isGeneratedIndexFile(content: string): boolean {
+  return (
+    content.includes("Auto-generated by @ic-reactor/codegen") &&
+    content.includes("createActorHooks(")
+  )
+}
+
 export interface PipelineResult {
   canisterName: string
   success: boolean
@@ -109,18 +125,30 @@ export async function runCanisterPipeline(
   // ── Step 2: Reactor file ───────────────────────────────────────────────────
 
   const reactorPath = path.join(canisterOutDir, "index.ts")
+  const reactorClass = resolveReactorClass(canisterConfig)
 
   try {
     const reactorContent = generateReactorFile({
       canisterName: name,
       didFile: resolvedDidFile,
       clientManagerPath: resolvedClientManagerPath,
+      reactorClass,
     })
 
     fs.mkdirSync(canisterOutDir, { recursive: true })
-    fs.writeFileSync(reactorPath, reactorContent)
-
-    files.push({ success: true, filePath: reactorPath })
+    if (!fs.existsSync(reactorPath)) {
+      fs.writeFileSync(reactorPath, reactorContent)
+      files.push({ success: true, filePath: reactorPath })
+    } else {
+      const existingIndexContent = fs.readFileSync(reactorPath, "utf-8")
+
+      if (isGeneratedIndexFile(existingIndexContent)) {
+        fs.writeFileSync(reactorPath, reactorContent)
+        files.push({ success: true, filePath: reactorPath })
+      } else {
+        files.push({ success: true, filePath: reactorPath, skipped: true })
+      }
+    }
   } catch (err) {
     files.push({
       success: false,

package/src/reactor.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from "vitest"
+import { 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>")
+  })
+})

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`).
  */