Add TanStack Router SSR integration utility

Add createTanStackRouterRenderFunction() to the react-on-rails npm
package, providing a render function factory for TanStack Router apps
with server-side rendering support.

This encapsulates the private API workarounds needed for synchronous
SSR (router.__store.setState() and router.ssr flag) inside
ShakaCode-maintained code, so consumer apps only use public APIs.

Server-side: synchronously injects route matches and renders with
renderToString. Client-side: hydrates with browser history and
dehydrated router state from the server.

Also includes an async path (serverRenderTanStackAppAsync) for use
with React on Rails Pro NodeRenderer when rendering_returns_promises
is enabled.

Related: #2298, #2299
Ref: printivity/printivity#2571, shakacode/react-on-rails-demos#104

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: justin808

packages/react-on-rails/package.json

@@ -53,11 +53,18 @@
     "./@internal/base/full": {
       "react-server": "./lib/base/full.rsc.js",
       "default": "./lib/base/full.js"
-    }
+    },
+    "./tanstack-router": "./lib/tanstack-router/index.js"
   },
   "peerDependencies": {
     "react": ">= 16",
-    "react-dom": ">= 16"
+    "react-dom": ">= 16",
+    "@tanstack/react-router": ">= 1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@tanstack/react-router": {
+      "optional": true
+    }
   },
   "files": [
     "README.md",

packages/react-on-rails/src/tanstack-router/clientHydrate.ts

@@ -0,0 +1,89 @@
+import { createElement, useEffect, useRef, type ReactElement } from 'react';
+import type { TanStackRouter, TanStackRouterOptions, DehydratedRouterState } from './types.ts';
+import type { RailsContext } from '../types/index.ts';
+
+/* eslint-disable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access, no-underscore-dangle, import/prefer-default-export */
+
+/**
+ * Client-side hydration for a TanStack Router app.
+ *
+ * Flow:
+ * 1. Create router with browser history
+ * 2. Synchronously inject route matches (same as server) to prevent hydration mismatch
+ * 3. Set router.ssr = true to skip auto-load on mount (Transitioner behavior)
+ * 4. After hydration, trigger router.load() to enable client-side navigation
+ * 5. Return a React component that renders RouterProvider
+ */
+export function clientHydrateTanStackApp(
+  options: TanStackRouterOptions,
+  props: Record<string, unknown>,
+  _railsContext: RailsContext & { serverSide: false },
+  RouterProvider: React.ComponentType<any>,
+  createBrowserHistory: () => any,
+): ReactElement {
+  const dehydratedState = props.__tanstackRouterDehydratedState as DehydratedRouterState | undefined;
+
+  // Create the app component that manages router lifecycle
+  const AppComponent = () => {
+    const routerRef = useRef<TanStackRouter | null>(null);
+
+    if (routerRef.current === null) {
+      const router = options.createRouter();
+
+      // Set browser history for client-side navigation
+      const browserHistory = createBrowserHistory();
+      router.update({ history: browserHistory });
+
+      // Synchronously inject route matches to match server output.
+      // This prevents hydration mismatches by ensuring the client renders
+      // the same route tree as the server.
+      if (typeof router.matchRoutes === 'function' && router.__store?.setState) {
+        const matches = router.matchRoutes(router.state.location.pathname, router.state.location.search);
+        router.__store.setState((s: Record<string, unknown>) => ({
+          ...s,
+          status: 'idle',
+          resolvedLocation: (s as { location: unknown }).location,
+          matches,
+        }));
+      }
+
+      // Set SSR flag to prevent Transitioner from auto-calling router.load() on mount.
+      // This avoids refetching data that was already loaded during SSR.
+      (router as any).ssr = true;
+
+      // Hydrate router with dehydrated state from server
+      if (dehydratedState?.dehydratedRouter && typeof router.hydrate === 'function') {
+        router.hydrate(dehydratedState.dehydratedRouter);
+      }
+
+      routerRef.current = router;
+    }
+
+    const router = routerRef.current;
+
+    // After mount, trigger router.load() to enable client-side navigation.
+    // The SSR flag prevented auto-loading, so we do it manually here.
+    const isFirstRender = useRef(true);
+    useEffect(() => {
+      if (isFirstRender.current) {
+        isFirstRender.current = false;
+
+        // If the router isn't fully loaded yet, trigger loading
+        if (router.state.status !== 'idle') {
+          router.load().catch((err: unknown) => {
+            console.error('react-on-rails/tanstack-router: Error loading routes after hydration:', err);
+          });
+        }
+      }
+    }, []); // eslint-disable-line react-hooks/exhaustive-deps -- router is a ref, intentionally stable
+
+    let app: ReactElement = createElement(RouterProvider, { router });
+    if (options.AppWrapper) {
+      app = createElement(options.AppWrapper, { ...props, children: app } as any);
+    }
+
+    return app;
+  };
+
+  return createElement(AppComponent);
+}

packages/react-on-rails/src/tanstack-router/index.ts

@@ -0,0 +1,134 @@
+/**
+ * TanStack Router integration for React on Rails.
+ *
+ * This module provides utilities to use TanStack Router with React on Rails' SSR pipeline.
+ * It encapsulates the workarounds needed for synchronous server-side rendering
+ * (TanStack Router's route loading is async, but renderToString is sync).
+ *
+ * @example
+ * ```typescript
+ * import { createTanStackRouterRenderFunction } from 'react-on-rails/tanstack-router';
+ * import { createRouter, RouterProvider, createMemoryHistory, createBrowserHistory } from '@tanstack/react-router';
+ * import { routeTree } from './routeTree.gen';
+ * import ReactOnRails from 'react-on-rails';
+ *
+ * const TanStackApp = createTanStackRouterRenderFunction(
+ *   {
+ *     createRouter: () => createRouter({ routeTree }),
+ *   },
+ *   { RouterProvider, createMemoryHistory, createBrowserHistory },
+ * );
+ *
+ * ReactOnRails.register({ TanStackApp });
+ * ```
+ *
+ * @remarks
+ * This integration uses internal TanStack Router APIs for synchronous SSR.
+ * ShakaCode maintains compatibility with TanStack Router versions.
+ * If you encounter issues after upgrading @tanstack/react-router, update react-on-rails
+ * or file an issue at https://github.com/shakacode/react_on_rails/issues
+ *
+ * @packageDocumentation
+ */
+
+import type { RailsContext, RenderFunction, RenderFunctionResult } from '../types/index.ts';
+import type { TanStackRouterOptions } from './types.ts';
+import { serverRenderTanStackApp } from './serverRender.ts';
+import { clientHydrateTanStackApp } from './clientHydrate.ts';
+
+export type { TanStackRouterOptions, DehydratedRouterState } from './types.ts';
+
+/* eslint-disable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-return */
+
+interface TanStackRouterDeps {
+  /**
+   * The RouterProvider component from @tanstack/react-router.
+   * We require this as a parameter to avoid a direct dependency on @tanstack/react-router.
+   */
+  RouterProvider: React.ComponentType<any>;
+  /**
+   * The createMemoryHistory function from @tanstack/react-router.
+   * Used for server-side rendering.
+   */
+  createMemoryHistory: (opts: { initialEntries: string[] }) => any;
+  /**
+   * The createBrowserHistory function from @tanstack/react-router.
+   * Used for client-side hydration.
+   */
+  createBrowserHistory: () => any;
+}
+
+/**
+ * Creates a React on Rails render function for a TanStack Router application.
+ *
+ * This function returns a render function that can be registered with `ReactOnRails.register()`.
+ * It handles both server-side rendering (with synchronous route matching) and client-side
+ * hydration (with browser history).
+ *
+ * @param options - Configuration for the TanStack Router app
+ * @param deps - TanStack Router dependencies (RouterProvider, createMemoryHistory, createBrowserHistory)
+ * @returns A render function compatible with ReactOnRails.register()
+ *
+ * @example
+ * ```typescript
+ * import { createTanStackRouterRenderFunction } from 'react-on-rails/tanstack-router';
+ * import { createRouter, RouterProvider, createMemoryHistory, createBrowserHistory } from '@tanstack/react-router';
+ * import { routeTree } from './routeTree.gen';
+ * import ReactOnRails from 'react-on-rails';
+ *
+ * const TanStackApp = createTanStackRouterRenderFunction(
+ *   {
+ *     createRouter: () => createRouter({ routeTree }),
+ *   },
+ *   { RouterProvider, createMemoryHistory, createBrowserHistory },
+ * );
+ *
+ * ReactOnRails.register({ TanStackApp });
+ * ```
+ */
+export function createTanStackRouterRenderFunction(
+  options: TanStackRouterOptions,
+  deps: TanStackRouterDeps,
+): RenderFunction {
+  const { RouterProvider, createMemoryHistory, createBrowserHistory } = deps;
+
+  const renderFn = (
+    props: Record<string, unknown> = {},
+    railsContext?: RailsContext,
+  ): RenderFunctionResult => {
+    if (!railsContext) {
+      throw new Error(
+        'react-on-rails/tanstack-router: railsContext is required. ' +
+          'Ensure the component is rendered via react_component helper.',
+      );
+    }
+
+    if (railsContext.serverSide) {
+      // Server-side: return a ReactElement that will be passed to renderToString.
+      // The createReactOutput pipeline handles ReactElement results from render functions
+      // (it calls renderToString on them).
+      return serverRenderTanStackApp(
+        options,
+        props,
+        railsContext as RailsContext & { serverSide: true },
+        RouterProvider,
+        createMemoryHistory,
+      ) as any;
+    }
+
+    // Client-side: return a ReactElement that React on Rails will hydrate/render.
+    return clientHydrateTanStackApp(
+      options,
+      props,
+      railsContext as RailsContext & { serverSide: false },
+      RouterProvider,
+      createBrowserHistory,
+    ) as any;
+  };
+
+  // Mark as a render function so React on Rails executes it rather than treating it
+  // as a React component.
+  renderFn.renderFunction = true as const;
+
+  return renderFn;
+}