feat(typescript): add recreateTransformersOnRebuild option; default to legacy watch behavior\n\n- Gate watch-mode transformer recreation behind new option (default false)\n- Plumb option through plugin options -> watch host\n- Types/README: document option and clarify getProgram semantics\n- Tests: enable option for watch-mode freshness tests

CharlieHelps · CharlieHelps · commit 6e4160fbeedd · 2025-10-23T00:45:01.000Z
diff --git a/packages/typescript/README.md b/packages/typescript/README.md
@@ -150,7 +150,10 @@ Supported transformer factories:
   ```js
   {
     type: 'program',
-    // In watch mode, the optional `getProgram` returns the latest Program
+    // An optional `getProgram` getter is always provided. In non‑watch it returns
+    // the same Program as the first argument. In watch mode, enabling the
+    // `recreateTransformersOnRebuild` option makes the getter reflect the latest
+    // Program across rebuilds; otherwise it refers to the initial Program.
     factory: (program: Program, getProgram?: () => Program) =>
       TransformerFactory | CustomTransformerFactory
   }
@@ -169,11 +172,18 @@ typescript({
   transformers: {
     before: [
       {
-        // Allow the transformer to get a Program reference in its factory
-        // and, in watch mode, access the latest Program via `getProgram()`
+        // Allow the transformer to get a Program reference in its factory.
+        // Prefer deferring `getProgram()` usage to transformation time so watch
+        // mode can see the freshest Program when `recreateTransformersOnRebuild`
+        // is enabled.
         type: 'program',
         factory: (program, getProgram) => {
-          return ProgramRequiringTransformerFactory(getProgram ? getProgram() : program);
+          const get = getProgram ?? (() => program);
+          return (context) => (source) => {
+            const latest = get();
+            // use `latest` here
+            return ts.visitEachChild(source, (n) => n, context);
+          };
         }
       },
       {
@@ -250,7 +260,31 @@ typescript({
 
 Note on watch mode
 
-When running Rollup in watch mode, this plugin recreates custom transformer factories after each TypeScript program rebuild so they receive the current Program and TypeChecker. If your transformer needs to query the latest type information across rebuilds, prefer using the optional `getProgram()` parameter provided to `program`-based transformer factories.
+By default (legacy behavior), this plugin reuses the same custom transformer factories for the lifetime of a watch session. Advanced users can opt into recreating factories on every TypeScript rebuild by enabling the `recreateTransformersOnRebuild` option. When enabled, both `program`- and `typeChecker`-based factories are rebuilt per watch cycle, and `getProgram()` (when used) reflects the latest Program across rebuilds.
+
+### `recreateTransformersOnRebuild`
+
+Type: `Boolean`<br>
+Default: `false` (legacy behavior)
+
+When `true`, the plugin recreates custom transformer factories on each TypeScript watch rebuild. This ensures factories capture the current `Program`/`TypeChecker` per cycle and that the optional `getProgram()` getter provided to `program`-based factories reflects the latest `Program` across rebuilds. Most users do not need this; enable it if your transformers depend on up‑to‑date Program/TypeChecker identities.
+
+```js
+// Opt-in to per-rebuild transformer recreation in watch mode
+typescript({
+  recreateTransformersOnRebuild: true,
+  transformers: {
+    before: [
+      {
+        type: 'program',
+        factory(program, getProgram) {
+          /* ... */
+        }
+      }
+    ]
+  }
+});
+```
 
 ### `cacheDir`
 
diff --git a/packages/typescript/src/index.ts b/packages/typescript/src/index.ts
@@ -35,6 +35,7 @@ export default function typescript(options: RollupTypescriptOptions = {}): Plugi
     outputToFilesystem,
     noForceEmit,
     transformers,
+    recreateTransformersOnRebuild,
     tsconfig,
     tslib,
     typescript: ts
@@ -180,7 +181,8 @@ export default function typescript(options: RollupTypescriptOptions = {}): Plugi
           status(diagnostic) {
             watchProgramHelper.handleStatus(diagnostic);
           },
-          transformers
+          transformers,
+          recreateTransformersOnRebuild
         });
       }
     },
diff --git a/packages/typescript/src/options/plugin.ts b/packages/typescript/src/options/plugin.ts
@@ -21,6 +21,7 @@ export const getPluginOptions = (options: RollupTypescriptOptions) => {
     filterRoot,
     noForceEmit,
     transformers,
+    recreateTransformersOnRebuild,
     tsconfig,
     tslib,
     typescript,
@@ -41,6 +42,7 @@ export const getPluginOptions = (options: RollupTypescriptOptions) => {
     typescript: typescript || defaultTs,
     tslib: tslib || getTsLibPath(),
     transformers,
+    recreateTransformersOnRebuild,
     outputToFilesystem
   };
 };
diff --git a/packages/typescript/src/watchProgram.ts b/packages/typescript/src/watchProgram.ts
@@ -42,6 +42,12 @@ interface CreateProgramOptions {
   resolveModule: Resolver;
   /** Custom TypeScript transformers */
   transformers?: CustomTransformerFactories | ((program: Program) => CustomTransformers);
+  /**
+   * Advanced: when true, recreate custom transformer factories on each
+   * TypeScript watch rebuild. Defaults to legacy behavior (false), which
+   * reuses the same factories for the lifetime of the watch session.
+   */
+  recreateTransformersOnRebuild?: boolean;
 }
 
 type DeferredResolve = ((value: boolean | PromiseLike<boolean>) => void) | (() => void);
@@ -142,7 +148,8 @@ function createWatchHost(
     writeFile,
     status,
     resolveModule,
-    transformers
+    transformers,
+    recreateTransformersOnRebuild
   }: CreateProgramOptions
 ): WatchCompilerHostOfFilesAndCompilerOptions<BuilderProgram> {
   const createProgram = ts.createEmitAndSemanticDiagnosticsBuilderProgram;
@@ -162,10 +169,13 @@ function createWatchHost(
     ...baseHost,
     /** Override the created program so an in-memory emit is used */
     afterProgramCreate(program) {
-      // Ensure we recompute custom transformers for each new builder program in watch mode
-      // so factories capture the current Program/TypeChecker and any provided getters return
-      // the latest values. This avoids freezing the initial Program across rebuilds.
-      createdTransformers = void 0;
+      // Optionally recompute custom transformers for each new builder program in watch mode
+      // so factories capture the current Program/TypeChecker and any provided getters can
+      // return the latest values. When disabled (default), legacy behavior reuses the
+      // same factories across rebuilds.
+      if (recreateTransformersOnRebuild) {
+        createdTransformers = void 0;
+      }
       const origEmit = program.emit;
       // eslint-disable-next-line no-param-reassign
       program.emit = (
diff --git a/packages/typescript/test/test.js b/packages/typescript/test/test.js
@@ -1714,6 +1714,7 @@ test.serial(
         typescript({
           tsconfig: false,
           compilerOptions: { module: 'esnext' },
+          recreateTransformersOnRebuild: true,
           // Use a fake TS that simulates two watch rebuilds by calling afterProgramCreate twice
           typescript: fakeTypescript({
             createWatchProgram(host) {
@@ -1795,6 +1796,7 @@ test.serial('recreates typeChecker-based transformers per rebuild in watch mode'
       typescript({
         tsconfig: false,
         compilerOptions: { module: 'esnext' },
+        recreateTransformersOnRebuild: true,
         // Fake TS that simulates two watch rebuilds, each returning a distinct TypeChecker
         typescript: fakeTypescript({
           createWatchProgram(host) {
diff --git a/packages/typescript/types/index.d.ts b/packages/typescript/types/index.d.ts
@@ -29,8 +29,14 @@ interface ProgramTransformerFactory<T extends TransformerStage> {
   type: 'program';
 
   /**
-   * Factory that may receive a getter for the latest Program when running in watch mode.
-   * The second parameter is optional to preserve backwards compatibility with existing
+   * Factory receives the current Program and may also receive a getter for retrieving
+   * the Program at call time. The getter is provided in all modes. In non-watch it
+   * returns the same Program as the first argument. In watch mode:
+   *  - When `recreateTransformersOnRebuild` is enabled (plugin option), the getter
+   *    reflects the latest Program across rebuilds.
+   *  - When disabled (default, legacy behavior), factories are reused and the getter
+   *    refers to the initial Program from when the factory was created.
+   * The second parameter remains optional for backwards compatibility with existing
    * transformer factories.
    */
   factory(program: Program, getProgram?: () => Program): StagedTransformerFactory<T>;
@@ -94,6 +100,14 @@ export interface RollupTypescriptPluginOptions {
    * Override force setting of `noEmit` and `emitDeclarationOnly` and use what is defined in `tsconfig.json`
    */
   noForceEmit?: boolean;
+  /**
+   * Advanced: when true, recreate custom transformer factories on each TypeScript
+   * watch rebuild so that `program`/`typeChecker`-based factories are rebuilt and
+   * `getProgram()` (when used) reflects the latest Program across rebuilds.
+   * Defaults to false (legacy behavior), which reuses factories for the lifetime
+   * of the watch session.
+   */
+  recreateTransformersOnRebuild?: boolean;
 }
 
 export interface FlexibleCompilerOptions extends CompilerOptions {
