fix: clean up renderer functions on unmount (#3209)

CHANGELOG.md

@@ -31,9 +31,11 @@ After a release, run `/update-changelog` in Claude Code to analyze commits, writ
 #### Changed
 
 - **[Pro]** **Pro generator now creates the Node Renderer at `renderer/node-renderer.js`**: The canonical location for the Node Renderer entry point is now a dedicated top-level `renderer/` directory instead of `client/`, making it straightforward to exclude from production Docker builds that strip JS sources after bundling. Docs and Pro `spec/dummy` now use the new path consistently. Existing apps are unaffected — the generator skips files that already exist (including a legacy `client/node-renderer.js`). Fixes [Issue 3073](https://github.com/shakacode/react_on_rails/issues/3073). [PR 3165](https://github.com/shakacode/react_on_rails/pull/3165) by [justin808](https://github.com/justin808).
+- **Turbo cleanup now runs before Turbo snapshots pages**: React on Rails now unmounts on `turbo:before-cache` instead of `turbo:before-render`, preventing live React DOM from being frozen into Turbo's snapshot cache. Apps with custom `turbo:before-render` cleanup workarounds may need to remove those workarounds to avoid double cleanup. [PR 3210](https://github.com/shakacode/react_on_rails/pull/3210) by [AbanoubGhadban](https://github.com/AbanoubGhadban).
 
 #### Fixed
 
+- **Renderer functions now clean up on Turbo unload and same-id replacement**: Renderer functions that return teardown callbacks are now cleaned up when the page unloads or when the same `domNodeId` is replaced, including async renderer teardown promises, preventing leaked roots during Turbo caching and dynamic HTML replacement. [PR 3210](https://github.com/shakacode/react_on_rails/pull/3210) by [AbanoubGhadban](https://github.com/AbanoubGhadban).
 - **[Pro]** **Node renderer now exposes `performance` when `supportModules: true`**: React 19's development build of `React.lazy` calls `performance.now()`, which previously threw `ReferenceError: performance is not defined` inside the node renderer's VM context unless users manually added `performance` via `additionalContext`. `performance` is now included in the default globals alongside `Buffer`, `process`, etc. Fixes [Issue 3154](https://github.com/shakacode/react_on_rails/issues/3154). [PR 3158](https://github.com/shakacode/react_on_rails/pull/3158) by [justin808](https://github.com/justin808).
 - **Client startup now recovers if initialization begins during `interactive` after `DOMContentLoaded` already fired**: React on Rails now still initializes the page when the client bundle starts in the browser timing window after `DOMContentLoaded` but before the document reaches `complete`. Fixes [Issue 3150](https://github.com/shakacode/react_on_rails/issues/3150). [PR 3151](https://github.com/shakacode/react_on_rails/pull/3151) by [ihabadham](https://github.com/ihabadham).
 - **Doctor accepts TypeScript server bundle entrypoints**: `react_on_rails:doctor` now resolves common source entrypoint suffixes (`.js`, `.jsx`, `.ts`, `.tsx`, `.mjs`, `.cjs`) before warning that the server bundle is missing, preventing false positives when apps use `server-bundle.ts`. [PR 3111](https://github.com/shakacode/react_on_rails/pull/3111) by [justin808](https://github.com/justin808).

packages/react-on-rails-pro/src/wrapServerComponentRenderer/client.tsx

@@ -14,7 +14,7 @@
 
 import * as React from 'react';
 import * as ReactDOMClient from 'react-dom/client';
-import { ReactComponentOrRenderFunction, RenderFunction } from 'react-on-rails/types';
+import type { ReactComponent, ReactComponentOrRenderFunction, RenderFunction } from 'react-on-rails/types';
 import isRenderFunction from 'react-on-rails/isRenderFunction';
 import { ensureReactUseAvailable } from 'react-on-rails/reactApis';
 import { createRSCProvider } from '../RSCProvider.tsx';
@@ -52,7 +52,7 @@ const wrapServerComponentRenderer = (
   const wrapper: RenderFunction = async (props, railsContext, domNodeId) => {
     const Component = isRenderFunction(componentOrRenderFunction)
       ? await componentOrRenderFunction(props, railsContext, domNodeId)
-      : componentOrRenderFunction;
+      : (componentOrRenderFunction as ReactComponent);
 
     if (typeof Component !== 'function') {
       throw new Error(`wrapServerComponentRenderer: component '${componentName}' is not a function`);

packages/react-on-rails-pro/src/wrapServerComponentRenderer/server.tsx

@@ -13,7 +13,7 @@
  */
 
 import * as React from 'react';
-import type { RenderFunction, ReactComponentOrRenderFunction } from 'react-on-rails/types';
+import type { ReactComponent, ReactComponentOrRenderFunction, RenderFunction } from 'react-on-rails/types';
 import isRenderFunction from 'react-on-rails/isRenderFunction';
 import { assertRailsContextWithServerStreamingCapabilities } from 'react-on-rails/types';
 import getReactServerComponent from '../getReactServerComponent.server.ts';
@@ -69,7 +69,7 @@ const wrapServerComponentRenderer = (
 
     const Component = isRenderFunction(componentOrRenderFunction)
       ? await componentOrRenderFunction(props, railsContext)
-      : componentOrRenderFunction;
+      : (componentOrRenderFunction as ReactComponent);
 
     if (typeof Component !== 'function') {
       throw new Error(`wrapServerComponentRenderer: component '${componentName}' is not a function`);

packages/react-on-rails/src/ClientRenderer.ts

@@ -1,5 +1,13 @@
 import type { ReactElement } from 'react';
-import type { RegisteredComponent, RailsContext, RenderReturnType } from './types/index.ts';
+import type {
+  RegisteredComponent,
+  RailsContext,
+  RendererFunction,
+  RendererResolvedResult,
+  RendererResult,
+  RendererTeardown,
+  RenderReturnType,
+} from './types/index.ts';
 import ComponentRegistry from './ComponentRegistry.ts';
 import StoreRegistry from './StoreRegistry.ts';
 import createReactOutput from './createReactOutput.ts';
@@ -11,8 +19,17 @@ import { supportsRootApi, unmountComponentAtNode } from './reactApis.cts';
 
 const REACT_ON_RAILS_STORE_ATTRIBUTE = 'data-js-react-on-rails-store';
 
-// Track all rendered roots for cleanup
-const renderedRoots = new Map<string, { root: RenderReturnType; domNode: Element }>();
+type RenderedRoot = {
+  domNode: Element;
+  root?: RenderReturnType;
+  teardown?: RendererTeardown;
+  pendingTeardown?: Promise<RendererResolvedResult>;
+  isRenderer?: true;
+};
+
+// Track all rendered roots and renderer-function teardowns for cleanup
+const renderedRoots = new Map<string, RenderedRoot>();
+const pendingUnmounts = new Map<string, Promise<void>>();
 
 function initializeStore(el: Element, railsContext: RailsContext): void {
   const name = el.getAttribute(REACT_ON_RAILS_STORE_ATTRIBUTE) || '';
@@ -33,11 +50,75 @@ function domNodeIdForEl(el: Element): string {
   return el.getAttribute('data-dom-id') || '';
 }
 
+function isRendererTeardown(value: unknown): value is RendererTeardown {
+  return typeof value === 'function';
+}
+
+function isPromiseLikeRendererResult(value: RendererResult): value is PromiseLike<RendererResolvedResult> {
+  return typeof (value as { then?: unknown })?.then === 'function';
+}
+
+function trackRendererTeardown(
+  domNodeId: string,
+  domNode: Element,
+  rendererResult: RendererResult,
+  componentName: string,
+): void {
+  const renderedRoot: RenderedRoot = { domNode, isRenderer: true };
+  renderedRoots.set(domNodeId, renderedRoot);
+
+  const storeTeardown = (resolvedResult: RendererResolvedResult): RendererResolvedResult => {
+    if (!isRendererTeardown(resolvedResult)) return undefined;
+
+    // Cache for synchronous unmounts and keep pendingTeardown resolving to the
+    // same function for async renderer results.
+    renderedRoot.teardown = resolvedResult;
+    renderedRoot.pendingTeardown = undefined;
+    return resolvedResult;
+  };
+
+  if (isPromiseLikeRendererResult(rendererResult)) {
+    renderedRoot.pendingTeardown = Promise.resolve(rendererResult)
+      .then(storeTeardown)
+      .catch((error: unknown) => {
+        console.error(`Error resolving renderer teardown for component ${componentName}:`, error);
+        return undefined;
+      });
+    return;
+  }
+
+  storeTeardown(rendererResult);
+}
+
+async function unmountRenderedRoot(renderedRoot: RenderedRoot): Promise<void> {
+  const { root, domNode, isRenderer } = renderedRoot;
+  const teardown =
+    renderedRoot.teardown ?? (renderedRoot.pendingTeardown ? await renderedRoot.pendingTeardown : undefined);
+
+  if (teardown) {
+    await teardown();
+    return;
+  }
+
+  // Renderer functions own their mounted tree. Without a returned teardown,
+  // the framework has no React root or DOM contract it can safely unmount.
+  if (isRenderer) return;
+
+  if (supportsRootApi && root && typeof root === 'object' && 'unmount' in root) {
+    // React 18+ Root API
+    root.unmount();
+  } else {
+    // React 16-17 legacy API
+    unmountComponentAtNode(domNode);
+  }
+}
+
 function delegateToRenderer(
   componentObj: RegisteredComponent,
   props: Record<string, unknown>,
   railsContext: RailsContext,
   domNodeId: string,
+  domNode: Element,
   trace: boolean,
 ): boolean {
   const { name, component, isRenderer } = componentObj;
@@ -53,17 +134,36 @@ DELEGATING TO RENDERER ${name} for dom node with id: ${domNodeId} with props, ra
     }
 
     // Call the renderer function with the expected signature
-    (component as (props: Record<string, unknown>, railsContext: RailsContext, domNodeId: string) => void)(
-      props,
-      railsContext,
-      domNodeId,
-    );
+    const rendererResult = (component as RendererFunction)(props, railsContext, domNodeId);
+    trackRendererTeardown(domNodeId, domNode, rendererResult, name);
     return true;
   }
 
   return false;
 }
 
+function queueRenderAfterPendingUnmount(
+  domNodeId: string,
+  pendingUnmount: Promise<void>,
+  render: () => void,
+): void {
+  const queuedRenderRef: { current?: Promise<void> } = {};
+  const queuedRender = pendingUnmount.then(() => {
+    if (pendingUnmounts.get(domNodeId) !== queuedRenderRef.current) return;
+
+    pendingUnmounts.delete(domNodeId);
+    render();
+  });
+  queuedRenderRef.current = queuedRender;
+
+  pendingUnmounts.set(domNodeId, queuedRender);
+  void queuedRender.catch(() => {
+    if (pendingUnmounts.get(domNodeId) === queuedRender) {
+      pendingUnmounts.delete(domNodeId);
+    }
+  });
+}
+
 /**
  * Used for client rendering by ReactOnRails. Either calls ReactDOM.hydrate, ReactDOM.render, or
  * delegates to a renderer registered by the user.
@@ -78,6 +178,12 @@ function renderElement(el: Element, railsContext: RailsContext): void {
   try {
     const domNode = document.getElementById(domNodeId);
     if (domNode) {
+      const pendingUnmount = pendingUnmounts.get(domNodeId);
+      if (pendingUnmount) {
+        queueRenderAfterPendingUnmount(domNodeId, pendingUnmount, () => renderElement(el, railsContext));
+        return;
+      }
+
       // Check if this component was already rendered by a previous call
       // This prevents hydration errors when reactOnRailsPageLoaded() is called multiple times
       // (e.g., for asynchronously loaded content)
@@ -94,28 +200,31 @@ function renderElement(el: Element, railsContext: RailsContext): void {
           return;
         }
         // DOM node was replaced (e.g., via async HTML injection) - clean up the old root
-        try {
-          if (
-            supportsRootApi &&
-            existing.root &&
-            typeof existing.root === 'object' &&
-            'unmount' in existing.root
-          ) {
-            existing.root.unmount();
-          } else {
-            unmountComponentAtNode(existing.domNode);
-          }
-        } catch (unmountError) {
+        renderedRoots.delete(domNodeId);
+        if (existing.isRenderer) {
+          const replacementUnmount = unmountRenderedRoot(existing).catch((unmountError: unknown) => {
+            // Ignore unmount errors for replaced nodes
+            if (trace) {
+              console.log(`Error unmounting replaced component: ${name}`, unmountError);
+            }
+          });
+
+          queueRenderAfterPendingUnmount(domNodeId, replacementUnmount, () =>
+            renderElement(el, railsContext),
+          );
+          return;
+        }
+
+        void unmountRenderedRoot(existing).catch((unmountError: unknown) => {
           // Ignore unmount errors for replaced nodes
           if (trace) {
             console.log(`Error unmounting replaced component: ${name}`, unmountError);
           }
-        }
-        renderedRoots.delete(domNodeId);
+        });
       }
 
       const componentObj = ComponentRegistry.get(name);
-      if (delegateToRenderer(componentObj, props, railsContext, domNodeId, trace)) {
+      if (delegateToRenderer(componentObj, props, railsContext, domNodeId, domNode, trace)) {
         return;
       }
 
@@ -204,21 +313,19 @@ export function reactOnRailsComponentLoaded(domId: string): Promise<void> {
  * Unmount all rendered React components and clear roots.
  * This should be called on page unload to prevent memory leaks.
  */
-function unmountAllComponents(): void {
-  renderedRoots.forEach(({ root, domNode }) => {
-    try {
-      if (supportsRootApi && root && typeof root === 'object' && 'unmount' in root) {
-        // React 18+ Root API
-        root.unmount();
-      } else {
-        // React 16-17 legacy API
-        unmountComponentAtNode(domNode);
-      }
-    } catch (error) {
-      console.error('Error unmounting component:', error);
+async function unmountAllComponents(): Promise<void> {
+  const renderedRootEntries = [...renderedRoots.values()];
+  renderedRoots.clear();
+  pendingUnmounts.clear();
+
+  const results = await Promise.allSettled(
+    renderedRootEntries.map((renderedRoot) => unmountRenderedRoot(renderedRoot)),
+  );
+  results.forEach((result) => {
+    if (result.status === 'rejected') {
+      console.error('Error unmounting component:', result.reason);
     }
   });
-  renderedRoots.clear();
 }
 
 // Register cleanup on page unload

packages/react-on-rails/src/capabilities/core.ts

@@ -11,6 +11,7 @@ import type {
 import * as Authenticity from '../Authenticity.ts';
 import buildConsoleReplay, { consoleReplay } from '../buildConsoleReplay.ts';
 import reactHydrateOrRender from '../reactHydrateOrRender.ts';
+import { refreshPageEventListeners } from '../pageLifecycle.ts';
 import createReactOutput from '../createReactOutput.ts';
 
 const DEFAULT_OPTIONS = {
@@ -73,6 +74,9 @@ export function createCoreCapability(registries: Registries) {
 
       if (typeof turbo !== 'undefined') {
         this.options.turbo = turbo;
+        if (turbo) {
+          refreshPageEventListeners();
+        }
       }
 
       if (typeof debugMode !== 'undefined') {