feat(client): adopt renderer-function teardown in dummy apps + docs (#3578)

Follow-up to #3209 / #3576, which shipped the renderer-function teardown
contract. This adopts the contract across the in-tree dummy renderer functions
and documents the optional teardown return value. None of these change the
public contract.

In-tree dummy renderers (each now captures its root and returns a teardown so
React on Rails unmounts it on Turbo/Turbolinks navigation or same-id node
replacement instead of leaking it):

- OSS modern (spec/dummy/client/app/startup): ManualRenderApp, ReduxApp,
  ReduxSharedStoreApp
- OSS legacy React 16 (spec/dummy/client/app-react16/startup): ManualRenderApp,
  ReduxApp, ReduxSharedStoreApp (unmount via ReactDOM.unmountComponentAtNode)
- Pro auto-load (ror-auto-load-components): ManualRenderApp, ReduxApp,
  ReduxSharedStoreApp, ApolloGraphQLApp, LazyApolloGraphQLApp
- Pro loadable: loadable-client.imports-loadable (returns a promise resolving to
  the teardown, since the root is created inside loadableReady)

The React 18 createRoot renderers that have a module.hot path now unmount the
previous root before re-mounting, so hot reload no longer leaks a root or calls
createRoot twice on one node. The React 16/17 renderers re-render into the same
container idempotently, so their HMR path is unchanged.

Docs:
- core-concepts/render-functions.md: the LazyHydrate example captures the root
  and returns a teardown
- api-reference/view-helpers-api.md: new "Cleaning up on Turbo/Turbolinks
  navigation" subsection with a Turbo-navigation example (React 18 + legacy) and
  the async best-effort caveat
- api-reference/javascript-api.md: short reference note on the teardown return

Imperative ReactOnRails.render(...) (item 3, separately scoped in #3209):
documented the caller's cleanup responsibility in the render() JSDoc rather than
auto-tracking the root. Auto-tracking would risk double-unmount for callers that
already manage unmount() and was explicitly deferred as out of scope, so this is
a documentation decision only with no behavior change.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: justin808

docs/oss/api-reference/javascript-api.md

@@ -30,7 +30,10 @@ The best source of docs is the `interface ReactOnRails` in [types/index.ts](http
  * - 2 params, or any function with `.renderFunction = true`: Render-Function — called with (props, railsContext),
  *   returns a React component, `{ renderedHtml }` object, or Promise (Pro Node renderer only)
  * - 3 params: Renderer function — called with (props, railsContext, domNodeId),
- *   responsible for calling ReactDOM.render/hydrate directly (client-only)
+ *   responsible for calling ReactDOM.render/hydrate directly (client-only).
+ *   May optionally return a teardown callback `() => void | Promise<void>` (or a promise resolving
+ *   to one); React on Rails runs it on Turbo/Turbolinks navigation or same-id node replacement to
+ *   unmount the renderer's root instead of leaking it. See the view-helpers renderer-function docs.
  *
  * Render-Functions can return:
  * - A React component (function or class) — used with `react_component`

docs/oss/api-reference/view-helpers-api.md

@@ -106,6 +106,45 @@ Why would you want to take over mounting yourself? One use case is code splittin
 > [!IMPORTANT]
 > **Renderer functions are strictly client-only.** There is no DOM on the server, so a renderer function cannot produce SSR output. React on Rails detects renderer functions at registration time and will throw a descriptive error like `Detected a renderer while server rendering component 'X'. See https://reactonrails.com/docs/core-concepts/render-functions for more information.` if you attempt to use one with `react_component(... prerender: true)`, `react_component_hash` (which forces prerendering), or `stream_react_component` (which is server-streaming only). For rendering that needs to run on the server, use a regular render function instead.
 
+#### Cleaning up on Turbo/Turbolinks navigation (optional teardown)
+
+Because a renderer function owns the React root it creates, React on Rails cannot unmount that root for you the way it does for the components it mounts itself. With [Turbo](https://turbo.hotwired.dev/) or Turbolinks, the page swaps without a full reload, so a renderer that never unmounts leaks its root (and any subscriptions or timers it holds) on every navigation.
+
+To opt in to cleanup, **return a teardown callback** — `() => void | Promise<void>`, or a promise resolving to one — from the renderer. React on Rails stores it and runs it when the mount is torn down: on Turbo/Turbolinks navigation (page unload) or when the same `domNodeId` node is replaced. Returning nothing keeps the previous (leaky) behavior, so existing renderers are unaffected.
+
+```jsx
+import ReactDOMClient from 'react-dom/client';
+
+// Renderer function: 3 params, mounts itself, returns a teardown.
+const MyRenderer = (props, _railsContext, domNodeId) => {
+  const domNode = document.getElementById(domNodeId);
+  const root = domNode.innerHTML
+    ? ReactDOMClient.hydrateRoot(domNode, <MyComponent {...props} />)
+    : ReactDOMClient.createRoot(domNode);
+  if (!domNode.innerHTML) {
+    root.render(<MyComponent {...props} />);
+  }
+
+  // Unmounted automatically on the next Turbo navigation (or same-id node replacement).
+  return () => root.unmount();
+};
+```
+
+Under the React 16/17 legacy API there is no root handle, so unmount by container node instead:
+
+```jsx
+import ReactDOM from 'react-dom';
+
+const MyLegacyRenderer = (props, _railsContext, domNodeId) => {
+  const domNode = document.getElementById(domNodeId);
+  ReactDOM.render(<MyComponent {...props} />, domNode);
+  return () => ReactDOM.unmountComponentAtNode(domNode);
+};
+```
+
+> [!NOTE]
+> Synchronous teardowns are always honored. An **async** teardown is best-effort in the open-source package: if a navigation or node replacement happens before the renderer resolves its teardown, that still-pending teardown may be dropped. React on Rails Pro's client renderer awaits the renderer and handles this race reliably.
+
 ---
 
 ### React Router

docs/oss/core-concepts/render-functions.md

@@ -38,14 +38,16 @@ const HelloHash = (props) => {
 };
 HelloHash.renderFunction = true;
 
-// Renderer Function — 3 params, handles hydration itself, CLIENT ONLY
-const LazyHydrate = (props, railsContext, domNodeId) => {
+// Renderer Function — 3 params, handles hydration itself, CLIENT ONLY.
+// Optionally return a teardown (or a promise resolving to one); React on Rails runs it on
+// Turbo/Turbolinks navigation (or same-id node replacement) so the root is unmounted, not leaked.
+const LazyHydrate = (props, railsContext, domNodeId) =>
   // whenVisible is a hypothetical helper that resolves when the element scrolls into view
   whenVisible(domNodeId).then(() => {
-    const root = document.getElementById(domNodeId);
-    ReactDOM.hydrateRoot(root, <HelloMessage {...props} />);
+    const domNode = document.getElementById(domNodeId);
+    const root = ReactDOM.hydrateRoot(domNode, <HelloMessage {...props} />);
+    return () => root.unmount();
   });
-};
 
 ReactOnRails.register({ HelloMessage, HelloWithContext, HelloHash, LazyHydrate });
 ```

packages/react-on-rails/src/types/index.ts

@@ -465,6 +465,17 @@ export interface ReactOnRailsInternal extends ReactOnRails {
    * ```
    * under React 18+.
    *
+   * @remarks
+   * **Cleanup is the caller's responsibility.** Unlike the components React on Rails mounts itself
+   * (which are unmounted automatically on Turbo/Turbolinks navigation and same-id node replacement),
+   * a root created by this imperative API is **not** tracked internally. The returned root is handed
+   * back to you, and you must call `unmount()` on it yourself — e.g. on a Turbo `turbo:before-render`
+   * / Turbolinks `turbolinks:before-render` event, or in your framework's teardown hook — to avoid
+   * leaking the root (and any subscriptions or timers it holds) across navigations. If you want
+   * automatic cleanup instead, register a renderer function (the 3-argument render-function form) and
+   * return a {@link RendererTeardown}; React on Rails tracks those mounts and runs the teardown for
+   * you.
+   *
    * @param name Name of your registered component
    * @param props Props to pass to your component
    * @param domNodeId HTML ID of the node the component will be rendered at

react_on_rails/spec/dummy/client/app-react16/startup/ManualRenderApp.jsx

@@ -18,4 +18,9 @@ export default (props, _railsContext, domNodeId) => {
   } else {
     ReactDOM.render(reactElement, domNode);
   }
+
+  // Return a teardown so React on Rails unmounts this tree on Turbo/Turbolinks navigation
+  // (page unload) or same-id node replacement instead of leaking it. The React 16/17 API unmounts
+  // by container node rather than via a root handle.
+  return () => ReactDOM.unmountComponentAtNode(domNode);
 };

react_on_rails/spec/dummy/client/app-react16/startup/ReduxApp.client.jsx

@@ -27,6 +27,8 @@ export default (props, railsContext, domNodeId) => {
   // eslint-disable-next-line no-param-reassign
   delete props.prerender;
 
+  const domNode = document.getElementById(domNodeId);
+
   const combinedReducer = combineReducers(reducers);
   const combinedProps = composeInitialState(props, railsContext);
 
@@ -39,14 +41,16 @@ export default (props, railsContext, domNodeId) => {
 
   // Provider uses this.props.children, so we're not typical React syntax.
   // This allows redux to add additional props to the HelloWorldContainer.
+  // The React 16/17 API re-renders into the same container idempotently, so hot reload reuses the
+  // existing tree (no separate root to unmount first).
   const renderApp = (Komponent) => {
     const element = wrapElementInStrictMode(
       <Provider store={store}>
         <Komponent />
       </Provider>,
     );
 
-    render(element, document.getElementById(domNodeId));
+    render(element, domNode);
   };
 
   renderApp(HelloWorldContainer);
@@ -57,4 +61,9 @@ export default (props, railsContext, domNodeId) => {
       renderApp(HelloWorldContainer);
     });
   }
+
+  // Return a teardown so React on Rails unmounts this tree on Turbo/Turbolinks navigation
+  // (page unload) or same-id node replacement instead of leaking it. The React 16/17 API unmounts
+  // by container node rather than via a root handle.
+  return () => ReactDOM.unmountComponentAtNode(domNode);
 };

react_on_rails/spec/dummy/client/app-react16/startup/ReduxSharedStoreApp.client.jsx

@@ -21,6 +21,8 @@ export default (props, _railsContext, domNodeId) => {
   // eslint-disable-next-line no-param-reassign
   delete props.prerender;
 
+  const domNode = document.getElementById(domNodeId);
+
   // This is where we get the existing store.
   const store = ReactOnRails.getStore('SharedReduxStore');
 
@@ -29,13 +31,15 @@ export default (props, _railsContext, domNodeId) => {
 
   // Provider uses this.props.children, so we're not typical React syntax.
   // This allows redux to add additional props to the HelloWorldContainer.
+  // The React 16/17 API re-renders into the same container idempotently, so hot reload reuses the
+  // existing tree (no separate root to unmount first).
   const renderApp = (Component) => {
     const element = wrapElementInStrictMode(
       <Provider store={store}>
         <Component />
       </Provider>,
     );
-    render(element, document.getElementById(domNodeId));
+    render(element, domNode);
   };
 
   renderApp(HelloWorldContainer);
@@ -45,4 +49,9 @@ export default (props, _railsContext, domNodeId) => {
       renderApp(HelloWorldContainer);
     });
   }
+
+  // Return a teardown so React on Rails unmounts this tree on Turbo/Turbolinks navigation
+  // (page unload) or same-id node replacement instead of leaking it. The React 16/17 API unmounts
+  // by container node rather than via a root handle.
+  return () => ReactDOM.unmountComponentAtNode(domNode);
 };

react_on_rails/spec/dummy/client/app/startup/ManualRenderApp.jsx

@@ -11,10 +11,15 @@ export default (props, _railsContext, domNodeId) => {
   );
 
   const domNode = document.getElementById(domNodeId);
+  let root;
   if (props.prerender) {
-    ReactDOMClient.hydrateRoot(domNode, reactElement);
+    root = ReactDOMClient.hydrateRoot(domNode, reactElement);
   } else {
-    const root = ReactDOMClient.createRoot(domNode);
+    root = ReactDOMClient.createRoot(domNode);
     root.render(reactElement);
   }
+
+  // Return a teardown so React on Rails unmounts this root on Turbo/Turbolinks navigation
+  // (page unload) or same-id node replacement instead of leaking it.
+  return () => root.unmount();
 };

react_on_rails/spec/dummy/client/app/startup/ReduxApp.client.jsx

@@ -21,15 +21,19 @@ import { wrapElementInStrictMode } from '../strictModeSupport';
  *
  */
 export default (props, railsContext, domNodeId) => {
-  const render = props.prerender
-    ? ReactDOMClient.hydrateRoot
-    : (domNode, element) => {
-        const root = ReactDOMClient.createRoot(domNode);
-        root.render(element);
-      };
+  const { prerender } = props;
   // eslint-disable-next-line no-param-reassign
   delete props.prerender;
 
+  const hydrateOrRender = (domNode, element) => {
+    if (prerender) {
+      return ReactDOMClient.hydrateRoot(domNode, element);
+    }
+    const newRoot = ReactDOMClient.createRoot(domNode);
+    newRoot.render(element);
+    return newRoot;
+  };
+
   const combinedReducer = combineReducers(reducers);
   const combinedProps = composeInitialState(props, railsContext);
 
@@ -40,6 +44,10 @@ export default (props, railsContext, domNodeId) => {
   // renderApp is a function required for hot reloading. see
   // https://github.com/retroalgic/react-on-rails-hot-minimal/blob/master/client/src/entry.js
 
+  // Track the current root so we can unmount it on Turbo navigation (via the returned teardown) and
+  // before re-mounting on hot reload (so we never leak a root or call createRoot twice on one node).
+  let root;
+
   // Provider uses this.props.children, so we're not typical React syntax.
   // This allows redux to add additional props to the HelloWorldContainer.
   const renderApp = (Komponent) => {
@@ -49,7 +57,10 @@ export default (props, railsContext, domNodeId) => {
       </Provider>,
     );
 
-    render(document.getElementById(domNodeId), element);
+    if (root) {
+      root.unmount();
+    }
+    root = hydrateOrRender(document.getElementById(domNodeId), element);
   };
 
   renderApp(HelloWorldContainer);
@@ -60,4 +71,10 @@ export default (props, railsContext, domNodeId) => {
       renderApp(HelloWorldContainer);
     });
   }
+
+  return () => {
+    if (root) {
+      root.unmount();
+    }
+  };
 };

react_on_rails/spec/dummy/client/app/startup/ReduxSharedStoreApp.client.jsx

@@ -15,21 +15,29 @@ import { wrapElementInStrictMode } from '../strictModeSupport';
  *  React will see that the state is the same and not do anything.
  */
 export default (props, _railsContext, domNodeId) => {
-  const render = props.prerender
-    ? ReactDOMClient.hydrateRoot
-    : (domNode, element) => {
-        const root = ReactDOMClient.createRoot(domNode);
-        root.render(element);
-      };
+  const { prerender } = props;
   // eslint-disable-next-line no-param-reassign
   delete props.prerender;
 
+  const hydrateOrRender = (domNode, element) => {
+    if (prerender) {
+      return ReactDOMClient.hydrateRoot(domNode, element);
+    }
+    const newRoot = ReactDOMClient.createRoot(domNode);
+    newRoot.render(element);
+    return newRoot;
+  };
+
   // This is where we get the existing store.
   const store = ReactOnRails.getStore('SharedReduxStore');
 
   // renderApp is a function required for hot reloading. see
   // https://github.com/retroalgic/react-on-rails-hot-minimal/blob/master/client/src/entry.js
 
+  // Track the current root so we can unmount it on Turbo navigation (via the returned teardown) and
+  // before re-mounting on hot reload (so we never leak a root or call createRoot twice on one node).
+  let root;
+
   // Provider uses this.props.children, so we're not typical React syntax.
   // This allows redux to add additional props to the HelloWorldContainer.
   const renderApp = (Component) => {
@@ -38,7 +46,10 @@ export default (props, _railsContext, domNodeId) => {
         <Component />
       </Provider>,
     );
-    render(document.getElementById(domNodeId), element);
+    if (root) {
+      root.unmount();
+    }
+    root = hydrateOrRender(document.getElementById(domNodeId), element);
   };
 
   renderApp(HelloWorldContainer);
@@ -48,4 +59,10 @@ export default (props, _railsContext, domNodeId) => {
       renderApp(HelloWorldContainer);
     });
   }
+
+  return () => {
+    if (root) {
+      root.unmount();
+    }
+  };
 };