@ic-reactor/codegen 0.7.2 → 0.8.0

package/README.md

@@ -38,14 +38,15 @@ Set `canisterConfig.mode` to choose the generated reactor class:
 - `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.
+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 using either `DisplayReactor` or `Reactor`.
+- **`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,
@@ -139,6 +140,7 @@ function generateReactorFile(options) {
     canisterName,
     didFile,
     clientManagerPath = "../../clients",
+    canisterId,
     reactorClass = "DisplayReactor"
   } = options;
   const pascalName = toPascalCase(canisterName);
@@ -147,6 +149,8 @@ function generateReactorFile(options) {
   const baseName = import_node_path2.default.basename(didFile, ".did");
   const declarationsPath = `./declarations/${baseName}`;
   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}"
@@ -158,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 ${reactorClass}<${serviceName}>({
   clientManager,
   idlFactory,
-  name: "${canisterName}",
+${canisterIdLine}  name: "${canisterName}",
 })
 
 export const {
@@ -176,14 +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 isGeneratedIndexFile(content) {
+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;
@@ -222,26 +242,31 @@ 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,
+      canisterId: canisterConfig.canisterId,
       reactorClass
     });
+    const entryContent = generateReactorEntryFile();
     import_node_fs2.default.mkdirSync(canisterOutDir, { recursive: true });
-    if (!import_node_fs2.default.existsSync(reactorPath)) {
-      import_node_fs2.default.writeFileSync(reactorPath, reactorContent);
-      files.push({ success: true, filePath: reactorPath });
+    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 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 });
+      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: reactorPath, skipped: true });
+        files.push({ success: true, filePath: entryPath, skipped: true });
       }
     }
   } catch (err) {
@@ -325,6 +350,7 @@ export const clientManager = new ClientManager({
   extractMethods,
   generateClientFile,
   generateDeclarations,
+  generateReactorEntryFile,
   generateReactorFile,
   getReactorName,
   getServiceTypeName,

package/dist/index.d.cts

@@ -68,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 {
@@ -192,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"):
@@ -224,6 +225,8 @@ 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)
@@ -231,9 +234,13 @@ interface ReactorGeneratorOptions {
     reactorClass?: ReactorClassName;
 }
 /**
- * Generate the content of a canister's `index.ts` 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
@@ -258,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 ReactorClassName, 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

@@ -68,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 {
@@ -192,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"):
@@ -224,6 +225,8 @@ 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)
@@ -231,9 +234,13 @@ interface ReactorGeneratorOptions {
     reactorClass?: ReactorClassName;
 }
 /**
- * Generate the content of a canister's `index.ts` 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
@@ -258,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 ReactorClassName, 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

@@ -94,6 +94,7 @@ function generateReactorFile(options) {
     canisterName,
     didFile,
     clientManagerPath = "../../clients",
+    canisterId,
     reactorClass = "DisplayReactor"
   } = options;
   const pascalName = toPascalCase(canisterName);
@@ -102,6 +103,8 @@ function generateReactorFile(options) {
   const baseName = path2.basename(didFile, ".did");
   const declarationsPath = `./declarations/${baseName}`;
   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}"
@@ -113,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 ${reactorClass}<${serviceName}>({
   clientManager,
   idlFactory,
-  name: "${canisterName}",
+${canisterIdLine}  name: "${canisterName}",
 })
 
 export const {
@@ -131,14 +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 isGeneratedIndexFile(content) {
+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;
@@ -177,26 +196,31 @@ 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,
+      canisterId: canisterConfig.canisterId,
       reactorClass
     });
+    const entryContent = generateReactorEntryFile();
     fs2.mkdirSync(canisterOutDir, { recursive: true });
-    if (!fs2.existsSync(reactorPath)) {
-      fs2.writeFileSync(reactorPath, reactorContent);
-      files.push({ success: true, filePath: reactorPath });
+    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 existingIndexContent = fs2.readFileSync(reactorPath, "utf-8");
-      if (isGeneratedIndexFile(existingIndexContent)) {
-        fs2.writeFileSync(reactorPath, reactorContent);
-        files.push({ success: true, filePath: reactorPath });
+      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: reactorPath, skipped: true });
+        files.push({ success: true, filePath: entryPath, skipped: true });
       }
     }
   } catch (err) {
@@ -279,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.2",
+  "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.3.0",
+    "@types/node": "^25.3.5",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"

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

@@ -12,7 +12,7 @@ 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.
+ * This file is overwritten whenever generation runs.
  */
 export const backendReactor = new DisplayReactor<BackendService>({
   clientManager,
@@ -43,7 +43,7 @@ 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.
+ * This file is overwritten whenever generation runs.
  */
 export const workflowEngineReactor = new Reactor<WorkflowEngineService>({
   clientManager,
@@ -74,7 +74,7 @@ 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.
+ * This file is overwritten whenever generation runs.
  */
 export const ledgerReactor = new MetadataDisplayReactor<LedgerService>({
   clientManager,

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"):
@@ -37,6 +37,8 @@ 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)
@@ -59,13 +61,14 @@ function getReactorClassImportSource(
 }
 
 /**
- * Generate the content of a canister's `index.ts` file.
+ * Generate the content of a canister's managed implementation file.
  */
 export function generateReactorFile(options: ReactorGeneratorOptions): string {
   const {
     canisterName,
     didFile,
     clientManagerPath = "../../clients",
+    canisterId,
     reactorClass = "DisplayReactor",
   } = options
 
@@ -77,6 +80,9 @@ export function generateReactorFile(options: ReactorGeneratorOptions): string {
   const baseName = path.basename(didFile, ".did")
   const declarationsPath = `./declarations/${baseName}`
   const reactorImportSource = getReactorClassImportSource(reactorClass)
+  const canisterIdLine = canisterId
+    ? `  canisterId: ${JSON.stringify(canisterId)},\n`
+    : ""
 
   return `import { createActorHooks } from "@ic-reactor/react"
 import { ${reactorClass} } from "${reactorImportSource}"
@@ -89,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 ${reactorClass}<${serviceName}>({
   clientManager,
   idlFactory,
-  name: "${canisterName}",
+${canisterIdLine}  name: "${canisterName}",
 })
 
 export const {
@@ -107,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/pipeline.test.ts

@@ -52,12 +52,47 @@ describe("Codegen pipeline", () => {
 
     const indexPath = path.join(
       projectRoot,
-      "src/declarations/workflow_engine/index.ts"
+      "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 () => {
@@ -90,11 +125,22 @@ export const customBackendIndex = true
 `
     )
 
-    const second = await runCanisterPipeline(options)
+    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({
@@ -106,17 +152,14 @@ export const customBackendIndex = true
     )
   })
 
-  it("overwrites legacy generated index.ts during regeneration", async () => {
+  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 })
 
-    // Simulate a generated index.ts content from older versions.
-    fs.writeFileSync(
-      path.join(canisterOutDir, "index.ts"),
-      `import { DisplayReactor, createActorHooks } from "@ic-reactor/react"
+    const existingGeneratedIndex = `import { DisplayReactor, createActorHooks } from "@ic-reactor/react"
 import { clientManager } from "../../clients"
 import { idlFactory, type _SERVICE } from "./declarations/backend"
 
@@ -126,7 +169,6 @@ 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,
@@ -138,6 +180,9 @@ export const {
   useActorQuery: useBackendQuery,
 } = createActorHooks(backendReactor)
 `
+    fs.writeFileSync(
+      path.join(canisterOutDir, "index.ts"),
+      existingGeneratedIndex
     )
 
     const result = await runCanisterPipeline({
@@ -155,9 +200,26 @@ export const {
     expect(result.success).toBe(true)
 
     const indexPath = path.join(canisterOutDir, "index.ts")
-    const generated = fs.readFileSync(indexPath, "utf-8")
+    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(generated).not.toContain('export * from "./index.generated"')
+    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,7 +7,8 @@
  * 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"
@@ -19,7 +20,10 @@ import type {
   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 */
@@ -39,13 +43,26 @@ function resolveReactorClass(canisterConfig: CanisterConfig): ReactorClassName {
   return canisterConfig.mode ?? "DisplayReactor"
 }
 
-function isGeneratedIndexFile(content: string): boolean {
+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
@@ -124,7 +141,8 @@ 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 {
@@ -132,21 +150,29 @@ export async function runCanisterPipeline(
       canisterName: name,
       didFile: resolvedDidFile,
       clientManagerPath: resolvedClientManagerPath,
+      canisterId: canisterConfig.canisterId,
       reactorClass,
     })
+    const entryContent = generateReactorEntryFile()
 
     fs.mkdirSync(canisterOutDir, { recursive: true })
-    if (!fs.existsSync(reactorPath)) {
-      fs.writeFileSync(reactorPath, reactorContent)
-      files.push({ success: true, filePath: reactorPath })
-    } else {
-      const existingIndexContent = fs.readFileSync(reactorPath, "utf-8")
+    fs.writeFileSync(reactorPath, reactorContent)
+    files.push({ success: true, filePath: reactorPath })
 
-      if (isGeneratedIndexFile(existingIndexContent)) {
-        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: reactorPath, skipped: true })
+        files.push({ success: true, filePath: entryPath, skipped: true })
       }
     }
   } catch (err) {

package/src/reactor.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest"
-import { generateReactorFile } from "./generators"
+import { generateReactorEntryFile, generateReactorFile } from "./generators"
 
 describe("Reactor generator", () => {
   it("keeps default behavior as DisplayReactor", () => {
@@ -42,4 +42,22 @@ describe("Reactor generator", () => {
     )
     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")
+  })
 })