From b0747116d98aaee933e991453dcfff3cd54b6f4c Mon Sep 17 00:00:00 2001
From: Abanoub Ghadban <abanoub@shakacode.com>
Date: Tue, 15 Apr 2025 14:30:28 +0200
Subject: [PATCH 01/50] replace RSCPayloadContainer with RSC injection utils

---
 node_package/src/RSCClientRoot.ts             |  13 +-
 node_package/src/RSCPayloadContainer.tsx      | 128 ----------------
 node_package/src/RSCPayloadGenerator.ts       |  57 ++++++++
 node_package/src/RSCServerRoot.tsx            |  40 ++---
 node_package/src/ReactOnRails.node.ts         |   4 +
 node_package/src/injectRSCPayload.ts          |  86 +++++++++++
 .../src/streamServerRenderedReactComponent.ts |  17 ++-
 .../transformRSCStreamAndReplayConsoleLogs.ts |  43 +++---
 node_package/src/types/index.ts               |  31 ++++
 node_package/tests/injectRSCPayload.test.ts   | 138 ++++++++++++++++++
 10 files changed, 363 insertions(+), 194 deletions(-)
 delete mode 100644 node_package/src/RSCPayloadContainer.tsx
 create mode 100644 node_package/src/RSCPayloadGenerator.ts
 create mode 100644 node_package/src/injectRSCPayload.ts
 create mode 100644 node_package/tests/injectRSCPayload.test.ts

diff --git a/node_package/src/RSCClientRoot.ts b/node_package/src/RSCClientRoot.ts
index 08b5c2fad3..49cb294303 100644
--- a/node_package/src/RSCClientRoot.ts
+++ b/node_package/src/RSCClientRoot.ts
@@ -5,14 +5,14 @@ import * as ReactDOMClient from 'react-dom/client';
 import { createFromReadableStream } from 'react-on-rails-rsc/client';
 import { fetch } from './utils.ts';
 import transformRSCStreamAndReplayConsoleLogs from './transformRSCStreamAndReplayConsoleLogs.ts';
-import { RailsContext, RenderFunction, RSCPayloadChunk } from './types/index.ts';
+import { RailsContext, RenderFunction } from './types/index.ts';
 import { ensureReactUseAvailable } from './reactApis.cts';
 
 ensureReactUseAvailable();
 
 declare global {
   interface Window {
-    REACT_ON_RAILS_RSC_PAYLOAD?: RSCPayloadChunk[];
+    REACT_ON_RAILS_RSC_PAYLOAD?: string[];
   }
 }
 
@@ -39,13 +39,13 @@ const fetchRSC = ({ componentName, rscPayloadGenerationUrlPath, componentProps }
 };
 
 const createRSCStreamFromPage = () => {
-  let streamController: ReadableStreamController<RSCPayloadChunk> | undefined;
-  const stream = new ReadableStream<RSCPayloadChunk>({
+  let streamController: ReadableStreamController<string> | undefined;
+  const stream = new ReadableStream<string>({
     start(controller) {
       if (typeof window === 'undefined') {
         return;
       }
-      const handleChunk = (chunk: RSCPayloadChunk) => {
+      const handleChunk = (chunk: string) => {
         controller.enqueue(chunk);
       };
 
@@ -67,9 +67,10 @@ const createRSCStreamFromPage = () => {
         window.REACT_ON_RAILS_RSC_PAYLOAD = [];
       }
       window.REACT_ON_RAILS_RSC_PAYLOAD.forEach(handleChunk);
+      const originalPush = window.REACT_ON_RAILS_RSC_PAYLOAD.push;
       window.REACT_ON_RAILS_RSC_PAYLOAD.push = (...chunks) => {
         chunks.forEach(handleChunk);
-        return chunks.length;
+        return originalPush.call(window.REACT_ON_RAILS_RSC_PAYLOAD, ...chunks);
       };
       streamController = controller;
     },
diff --git a/node_package/src/RSCPayloadContainer.tsx b/node_package/src/RSCPayloadContainer.tsx
deleted file mode 100644
index d1c58fe29a..0000000000
--- a/node_package/src/RSCPayloadContainer.tsx
+++ /dev/null
@@ -1,128 +0,0 @@
-import * as React from 'react';
-
-type StreamChunk = {
-  chunk: string;
-  isLastChunk: boolean;
-};
-
-type RSCPayloadContainerProps = {
-  RSCPayloadStream: NodeJS.ReadableStream;
-};
-
-type RSCPayloadContainerInnerProps = {
-  chunkIndex: number;
-  getChunkPromise: (chunkIndex: number) => Promise<StreamChunk>;
-};
-
-// In JavaScript, when an escape sequence with a backslash (\) is followed by a character
-// that isn't a recognized escape character, the backslash is ignored, and the character
-// is treated as-is.
-// This behavior allows us to use the backslash to escape characters that might be
-// interpreted as HTML tags, preventing them from being processed by the HTML parser.
-// For example, we can escape the comment tag <!-- as <\!-- and the script tag </script>
-// as <\/script>.
-// This ensures that these tags are not prematurely closed or misinterpreted by the browser.
-function escapeScript(script: string) {
-  return script.replace(/<!--/g, '<\\!--').replace(/<\/(script)/gi, '</\\$1');
-}
-
-/**
- * RSCPayloadContainer is a React component that handles the server-to-client transfer
- * of React Server Component (RSC) payloads. It works in conjunction with RSCClientRoot
- * to ensure reliable delivery of RSC chunks.
- *
- * How it works:
- * 1. Receives a NodeJS.ReadableStream containing RSC payload chunks from the server
- * 2. Creates a series of promises to handle each chunk asynchronously
- * 3. For each chunk:
- *    - Creates a script tag that pushes the chunk to window.REACT_ON_RAILS_RSC_PAYLOAD
- *    - Uses React.use() to handle the async chunk loading
- *    - Recursively renders the next chunk using Suspense
- *
- * The component ensures that:
- * - Chunks are processed in order
- * - Server-side console logs are preserved
- * - The transfer is resilient to network conditions
- * - The client receives all chunks reliably
- */
-const RSCPayloadContainer = ({
-  chunkIndex,
-  getChunkPromise,
-}: RSCPayloadContainerInnerProps): React.ReactNode => {
-  const chunkPromise = getChunkPromise(chunkIndex);
-  const chunk = React.use(chunkPromise);
-
-  const scriptElement = (
-    <script
-      // eslint-disable-next-line react/no-danger
-      dangerouslySetInnerHTML={{
-        __html: escapeScript(`(self.REACT_ON_RAILS_RSC_PAYLOAD||=[]).push(${chunk.chunk})`),
-      }}
-    />
-  );
-
-  if (chunk.isLastChunk) {
-    return scriptElement;
-  }
-
-  return (
-    <>
-      {scriptElement}
-      <React.Suspense fallback={null}>
-        <RSCPayloadContainer chunkIndex={chunkIndex + 1} getChunkPromise={getChunkPromise} />
-      </React.Suspense>
-    </>
-  );
-};
-
-export default function RSCPayloadContainerWrapper({ RSCPayloadStream }: RSCPayloadContainerProps) {
-  const [chunkPromises] = React.useState<Promise<StreamChunk>[]>(() => {
-    const promises: Promise<StreamChunk>[] = [];
-    let resolveCurrentPromise: (streamChunk: StreamChunk) => void = () => {};
-    let rejectCurrentPromise: (error: unknown) => void = () => {};
-    const decoder = new TextDecoder();
-
-    const createNewPromise = () => {
-      const promise = new Promise<StreamChunk>((resolve, reject) => {
-        resolveCurrentPromise = resolve;
-        rejectCurrentPromise = reject;
-      });
-
-      promises.push(promise);
-    };
-
-    createNewPromise();
-    RSCPayloadStream.on('data', (streamChunk) => {
-      resolveCurrentPromise({ chunk: decoder.decode(streamChunk as Uint8Array), isLastChunk: false });
-      createNewPromise();
-    });
-
-    RSCPayloadStream.on('error', (error) => {
-      rejectCurrentPromise(error);
-      createNewPromise();
-    });
-
-    RSCPayloadStream.on('end', () => {
-      resolveCurrentPromise({ chunk: '', isLastChunk: true });
-    });
-
-    return promises;
-  });
-
-  const getChunkPromise = React.useCallback(
-    (chunkIndex: number) => {
-      if (chunkIndex >= chunkPromises.length) {
-        throw new Error('React on Rails Error: RSC Chunk index out of bounds');
-      }
-
-      return chunkPromises[chunkIndex];
-    },
-    [chunkPromises],
-  );
-
-  return (
-    <React.Suspense fallback={null}>
-      <RSCPayloadContainer chunkIndex={0} getChunkPromise={getChunkPromise} />
-    </React.Suspense>
-  );
-}
diff --git a/node_package/src/RSCPayloadGenerator.ts b/node_package/src/RSCPayloadGenerator.ts
new file mode 100644
index 0000000000..0157b4b292
--- /dev/null
+++ b/node_package/src/RSCPayloadGenerator.ts
@@ -0,0 +1,57 @@
+import { PassThrough } from 'stream';
+import { RailsContext } from './types';
+
+declare global {
+  function generateRSCPayload(
+    componentName: string,
+    props: Record<string, unknown>,
+    railsContext: RailsContext,
+  ): Promise<NodeJS.ReadableStream>;
+}
+
+const mapRailsContextToRSCPayloadStreams = new Map<
+  RailsContext,
+  {
+    componentName: string;
+    stream: NodeJS.ReadableStream;
+  }[]
+>();
+
+export const getRSCPayloadStream = async (
+  componentName: string,
+  props: Record<string, unknown>,
+  railsContext: RailsContext,
+): Promise<NodeJS.ReadableStream> => {
+  if (typeof generateRSCPayload !== 'function') {
+    throw new Error(
+      'generateRSCPayload is not defined. Please ensure that you are using at least version 4.0.0 of ' +
+        'React on Rails Pro and the Node renderer, and that ReactOnRailsPro.configuration.enable_rsc_support ' +
+        'is set to true.',
+    );
+  }
+
+  const stream = await generateRSCPayload(componentName, props, railsContext);
+  const streams = mapRailsContextToRSCPayloadStreams.get(railsContext) ?? [];
+  const stream1 = new PassThrough();
+  stream.pipe(stream1);
+  const stream2 = new PassThrough();
+  stream1.pipe(stream2);
+
+  streams.push({
+    componentName,
+    stream: stream2,
+  });
+  mapRailsContextToRSCPayloadStreams.set(railsContext, streams);
+  return stream1;
+};
+
+export const getRSCPayloadStreams = (
+  railsContext: RailsContext,
+): {
+  componentName: string;
+  stream: NodeJS.ReadableStream;
+}[] => mapRailsContextToRSCPayloadStreams.get(railsContext) ?? [];
+
+export const clearRSCPayloadStreams = (railsContext: RailsContext) => {
+  mapRailsContextToRSCPayloadStreams.delete(railsContext);
+};
diff --git a/node_package/src/RSCServerRoot.tsx b/node_package/src/RSCServerRoot.tsx
index 39ecb23896..bccf43f2cc 100644
--- a/node_package/src/RSCServerRoot.tsx
+++ b/node_package/src/RSCServerRoot.tsx
@@ -1,22 +1,12 @@
 import * as React from 'react';
 import { createFromNodeStream } from 'react-on-rails-rsc/client.node';
-import { PassThrough } from 'stream';
 import type { RenderFunction, RailsContext } from './types/index.ts';
 import transformRSCStream from './transformRSCNodeStream.ts';
 import loadJsonFile from './loadJsonFile.ts';
-import RSCPayloadContainer from './RSCPayloadContainer.tsx';
 import { ensureReactUseAvailable } from './reactApis.cts';
 
 ensureReactUseAvailable();
 
-declare global {
-  function generateRSCPayload(
-    componentName: string,
-    props: Record<string, unknown>,
-    railsContext: RailsContext,
-  ): Promise<NodeJS.ReadableStream>;
-}
-
 type RSCServerRootProps = {
   componentName: string;
   componentProps: Record<string, unknown>;
@@ -82,11 +72,9 @@ const RSCServerRoot: RenderFunction = async (
     );
   }
 
-  if (typeof generateRSCPayload !== 'function') {
+  if (typeof ReactOnRails.getRSCPayloadStream !== 'function') {
     throw new Error(
-      'generateRSCPayload is not defined. Please ensure that you are using at least version 4.0.0 of ' +
-        'React on Rails Pro and the Node renderer, and that ReactOnRailsPro.configuration.enable_rsc_support ' +
-        'is set to true.',
+      'ReactOnRails.getRSCPayloadStream is not defined. This likely means that you are not building the server bundle correctly. Please ensure that your server bundle is targeting Node.js',
     );
   }
 
@@ -94,24 +82,14 @@ const RSCServerRoot: RenderFunction = async (
     railsContext.reactServerClientManifestFileName,
     railsContext.reactClientManifestFileName,
   );
-  const rscPayloadStream = await generateRSCPayload(componentName, componentProps, railsContext);
-
-  // Tee the stream to pass it to the server component and the payload container
-  const rscPayloadStream1 = new PassThrough();
-  rscPayloadStream.pipe(rscPayloadStream1);
-  const rscPayloadStream2 = new PassThrough();
-  rscPayloadStream.pipe(rscPayloadStream2);
-  const serverComponentElement = createFromReactOnRailsNodeStream(rscPayloadStream1, ssrManifest);
+  const rscPayloadStream = await ReactOnRails.getRSCPayloadStream(
+    componentName,
+    componentProps,
+    railsContext,
+  );
 
-  return () => {
-    const resolvedServerComponent = use(serverComponentElement);
-    return (
-      <>
-        {resolvedServerComponent}
-        <RSCPayloadContainer RSCPayloadStream={rscPayloadStream2} />
-      </>
-    );
-  };
+  const serverComponentElement = createFromReactOnRailsNodeStream(rscPayloadStream, ssrManifest);
+  return () => use(serverComponentElement);
 };
 
 export default RSCServerRoot;
diff --git a/node_package/src/ReactOnRails.node.ts b/node_package/src/ReactOnRails.node.ts
index 407d2658b9..39507cef9f 100644
--- a/node_package/src/ReactOnRails.node.ts
+++ b/node_package/src/ReactOnRails.node.ts
@@ -1,7 +1,11 @@
 import ReactOnRails from './ReactOnRails.full.ts';
 import streamServerRenderedReactComponent from './streamServerRenderedReactComponent.ts';
+import { getRSCPayloadStream, getRSCPayloadStreams, clearRSCPayloadStreams } from './RSCPayloadGenerator.ts';
 
 ReactOnRails.streamServerRenderedReactComponent = streamServerRenderedReactComponent;
+ReactOnRails.getRSCPayloadStream = getRSCPayloadStream;
+ReactOnRails.getRSCPayloadStreams = getRSCPayloadStreams;
+ReactOnRails.clearRSCPayloadStreams = clearRSCPayloadStreams;
 
 export * from './ReactOnRails.full.ts';
 // eslint-disable-next-line no-restricted-exports -- see https://github.com/eslint/eslint/issues/15617
diff --git a/node_package/src/injectRSCPayload.ts b/node_package/src/injectRSCPayload.ts
new file mode 100644
index 0000000000..0c94e0dac3
--- /dev/null
+++ b/node_package/src/injectRSCPayload.ts
@@ -0,0 +1,86 @@
+import { PipeableStream } from 'react-dom/server';
+import { PassThrough, Transform } from 'stream';
+import { RailsContext } from './types';
+
+// In JavaScript, when an escape sequence with a backslash (\) is followed by a character
+// that isn't a recognized escape character, the backslash is ignored, and the character
+// is treated as-is.
+// This behavior allows us to use the backslash to escape characters that might be
+// interpreted as HTML tags, preventing them from being processed by the HTML parser.
+// For example, we can escape the comment tag <!-- as <\!-- and the script tag </script>
+// as <\/script>.
+// This ensures that these tags are not prematurely closed or misinterpreted by the browser.
+function escapeScript(script: string) {
+  return script.replace(/<!--/g, '<\\!--').replace(/<\/(script)/gi, '</\\$1');
+}
+
+function writeChunk(chunk: string, transform: Transform) {
+  transform.push(`<script>${escapeScript(`(self.REACT_ON_RAILS_RSC_PAYLOAD||=[]).push(${chunk})`)}</script>`);
+}
+
+export default function injectRSCPayload(
+  pipeableHtmlStream: NodeJS.ReadableStream | PipeableStream,
+  railsContext: RailsContext,
+) {
+  const htmlStream = new PassThrough();
+  pipeableHtmlStream.pipe(htmlStream);
+  const decoder = new TextDecoder();
+  let rscPromise: Promise<void> | null = null;
+  const htmlBuffer: string[] = [];
+  let timeout: NodeJS.Timeout | null = null;
+  const resultStream = new PassThrough();
+
+  // Start reading RSC stream immediately
+  const startRSC = async () => {
+    try {
+      for await (const chunk of ReactOnRails.getRSCPayloadStreams?.(railsContext)?.[0]?.stream ?? []) {
+        try {
+          const decodedChunk = typeof chunk === 'string' ? chunk : decoder.decode(chunk);
+          writeChunk(JSON.stringify(decodedChunk), resultStream);
+        } catch (_) {
+          const decodedChunk = typeof chunk === 'string' ? chunk : String.fromCodePoint(...chunk);
+          const base64 = JSON.stringify(btoa(decodedChunk));
+          writeChunk(`Uint8Array.from(atob(${base64}), m => m.codePointAt(0))`, resultStream);
+        }
+      }
+    } catch (err) {
+      resultStream.emit('error', err);
+    }
+  };
+
+  const writeHTMLChunks = () => {
+    for (const htmlChunk of htmlBuffer) {
+      resultStream.push(htmlChunk);
+    }
+    htmlBuffer.length = 0;
+  };
+
+  htmlStream.on('data', (chunk: Buffer) => {
+    const buf = decoder.decode(chunk);
+    htmlBuffer.push(buf);
+    if (timeout) {
+      return;
+    }
+
+    timeout = setTimeout(() => {
+      writeHTMLChunks();
+      if (!rscPromise) {
+        rscPromise = startRSC();
+      }
+      timeout = null;
+    }, 0);
+  });
+
+  htmlStream.on('end', () => {
+    if (timeout) {
+      clearTimeout(timeout);
+    }
+    writeHTMLChunks();
+    if (!rscPromise) {
+      rscPromise = startRSC();
+    }
+    rscPromise.then(() => resultStream.end()).catch((err: unknown) => resultStream.emit('error', err));
+  });
+
+  return resultStream;
+}
diff --git a/node_package/src/streamServerRenderedReactComponent.ts b/node_package/src/streamServerRenderedReactComponent.ts
index 1519f6e443..c681bb7999 100644
--- a/node_package/src/streamServerRenderedReactComponent.ts
+++ b/node_package/src/streamServerRenderedReactComponent.ts
@@ -9,6 +9,7 @@ import handleError from './handleError.ts';
 import { renderToPipeableStream, PipeableStream } from './ReactDOMServer.cts';
 import { createResultObject, convertToError, validateComponent } from './serverRenderUtils.ts';
 import type { RenderParams, StreamRenderState, StreamableComponentResult } from './types/index.ts';
+import injectRSCPayload from './injectRSCPayload.ts';
 
 type BufferedEvent = {
   event: 'data' | 'error' | 'end';
@@ -132,8 +133,8 @@ export const transformRenderStreamChunksToResultObject = (renderState: StreamRen
     },
   });
 
-  let pipedStream: PipeableStream | null = null;
-  const pipeToTransform = (pipeableStream: PipeableStream) => {
+  let pipedStream: PipeableStream | NodeJS.ReadableStream | null = null;
+  const pipeToTransform = (pipeableStream: PipeableStream | NodeJS.ReadableStream) => {
     pipeableStream.pipe(transformStream);
     pipedStream = pipeableStream;
   };
@@ -147,7 +148,9 @@ export const transformRenderStreamChunksToResultObject = (renderState: StreamRen
   const writeChunk = (chunk: string) => transformStream.write(chunk);
   const endStream = () => {
     transformStream.end();
-    pipedStream?.abort();
+    if (pipedStream && 'abort' in pipedStream) {
+      pipedStream.abort();
+    }
   };
   return { readableStream, pipeToTransform, writeChunk, emitError, endStream };
 };
@@ -181,6 +184,11 @@ const streamRenderReactComponent = (
     endStream();
   };
 
+  const { railsContext } = options;
+  if (!railsContext) {
+    throw new Error('railsContext is required to stream a React component');
+  }
+
   Promise.resolve(reactRenderingResult)
     .then((reactRenderedElement) => {
       if (typeof reactRenderedElement === 'string') {
@@ -201,7 +209,7 @@ const streamRenderReactComponent = (
         },
         onShellReady() {
           renderState.isShellReady = true;
-          pipeToTransform(renderingStream);
+          pipeToTransform(injectRSCPayload(renderingStream, railsContext));
         },
         onError(e) {
           reportError(convertToError(e));
@@ -214,7 +222,6 @@ const streamRenderReactComponent = (
       reportError(error);
       sendErrorHtml(error);
     });
-
   return readableStream;
 };
 
diff --git a/node_package/src/transformRSCStreamAndReplayConsoleLogs.ts b/node_package/src/transformRSCStreamAndReplayConsoleLogs.ts
index 91131e9b06..31d35c4f93 100644
--- a/node_package/src/transformRSCStreamAndReplayConsoleLogs.ts
+++ b/node_package/src/transformRSCStreamAndReplayConsoleLogs.ts
@@ -1,8 +1,6 @@
 import { RSCPayloadChunk } from './types/index.ts';
 
-export default function transformRSCStreamAndReplayConsoleLogs(
-  stream: ReadableStream<Uint8Array | RSCPayloadChunk>,
-) {
+export default function transformRSCStreamAndReplayConsoleLogs(stream: ReadableStream<Uint8Array | string>) {
   return new ReadableStream({
     async start(controller) {
       const reader = stream.getReader();
@@ -28,27 +26,24 @@ export default function transformRSCStreamAndReplayConsoleLogs(
       };
 
       while (!done) {
-        if (ArrayBuffer.isView(value)) {
-          const decodedValue = lastIncompleteChunk + decoder.decode(value);
-          const chunks = decodedValue.split('\n');
-          lastIncompleteChunk = chunks.pop() ?? '';
-
-          const jsonChunks = chunks
-            .filter((line) => line.trim() !== '')
-            .map((line) => {
-              try {
-                return JSON.parse(line) as RSCPayloadChunk;
-              } catch (error) {
-                console.error('Error parsing JSON:', line, error);
-                throw error;
-              }
-            });
-
-          for (const jsonChunk of jsonChunks) {
-            handleJsonChunk(jsonChunk);
-          }
-        } else if (value) {
-          handleJsonChunk(value);
+        const decodedValue = typeof value === 'string' ? value : decoder.decode(value);
+        const decodedChunks = lastIncompleteChunk + decodedValue;
+        const chunks = decodedChunks.split('\n');
+        lastIncompleteChunk = chunks.pop() ?? '';
+
+        const jsonChunks = chunks
+          .filter((line) => line.trim() !== '')
+          .map((line) => {
+            try {
+              return JSON.parse(line) as RSCPayloadChunk;
+            } catch (error) {
+              console.error('Error parsing JSON:', line, error);
+              throw error;
+            }
+          });
+
+        for (const jsonChunk of jsonChunks) {
+          handleJsonChunk(jsonChunk);
         }
 
         // eslint-disable-next-line no-await-in-loop
diff --git a/node_package/src/types/index.ts b/node_package/src/types/index.ts
index 4d13a27bcd..1c940a9135 100644
--- a/node_package/src/types/index.ts
+++ b/node_package/src/types/index.ts
@@ -396,6 +396,37 @@ export interface ReactOnRailsInternal extends ReactOnRails {
    * Indicates if the RSC bundle is being used.
    */
   isRSCBundle: boolean;
+
+  // These functions are intended for use in Node.js environments only. They should be used on the server side and excluded from client-side bundles to reduce bundle size.
+  /**
+   * Generates a ReadableStream for a given component's RSC payload.
+   * @param componentName - The name of the component.
+   * @param props - The properties to pass to the component.
+   * @param railsContext - The Rails context of the current rendering request.
+   * @returns A promise that resolves to a NodeJS.ReadableStream.
+   */
+  getRSCPayloadStream?: (
+    componentName: string,
+    props: Record<string, unknown>,
+    railsContext: RailsContext,
+  ) => Promise<NodeJS.ReadableStream>;
+
+  /**
+   /**
+    * Retrieves all React Server Component (RSC) payload streams generated for a specific rendering request.
+    * @param railsContext - The Rails context of the current rendering request.
+    * @returns An array of objects, each containing the component name and its corresponding NodeJS.ReadableStream.
+    */
+  getRSCPayloadStreams?: (railsContext: RailsContext) => {
+    componentName: string;
+    stream: NodeJS.ReadableStream;
+  }[];
+
+  /**
+   * Clears all RSC payload streams generated for the rendering request of the given Rails context.
+   * @param railsContext - The Rails context of the current rendering request.
+   */
+  clearRSCPayloadStreams?: (railsContext: RailsContext) => void;
 }
 
 export type RenderStateHtml = FinalHtmlResult | Promise<FinalHtmlResult>;
diff --git a/node_package/tests/injectRSCPayload.test.ts b/node_package/tests/injectRSCPayload.test.ts
new file mode 100644
index 0000000000..4a8d04bd80
--- /dev/null
+++ b/node_package/tests/injectRSCPayload.test.ts
@@ -0,0 +1,138 @@
+import { Readable, PassThrough } from 'stream';
+import ReactOnRails, { RailsContext } from '../src/ReactOnRails.node';
+import injectRSCPayload from '../src/injectRSCPayload';
+
+describe('injectRSCPayload', () => {
+  const createMockStream = (chunks: (string | Buffer)[] | { [key: number]: string | string[] }) => {
+    if (Array.isArray(chunks)) {
+      return Readable.from(
+        chunks.map((chunk) => (typeof chunk === 'string' ? new TextEncoder().encode(chunk) : chunk)),
+      );
+    }
+    const passThrough = new PassThrough();
+    const entries = Object.entries(chunks);
+    const keysLength = entries.length;
+    entries.forEach(([delay, value], index) => {
+      setTimeout(() => {
+        const chunksArray = Array.isArray(value) ? value : [value];
+        chunksArray.forEach((chunk) => {
+          passThrough.push(new TextEncoder().encode(chunk));
+        });
+        if (index === keysLength - 1) {
+          passThrough.push(null);
+        }
+      }, +delay);
+    });
+    return passThrough;
+  };
+
+  const collectStreamData = async (stream: Readable) => {
+    const chunks: string[] = [];
+    for await (const chunk of stream) {
+      chunks.push(new TextDecoder().decode(chunk as Buffer));
+    }
+    return chunks.join('');
+  };
+
+  it('should inject RSC payload as script tags', async () => {
+    const mockRSC = createMockStream(['{"test": "data"}']);
+    const mockHTML = createMockStream(['<html><body><div>Hello, world!</div></body></html>']);
+
+    jest
+      .spyOn(ReactOnRails, 'getRSCPayloadStreams')
+      .mockReturnValue([{ stream: mockRSC, componentName: 'test' }]);
+
+    const result = injectRSCPayload(mockHTML, {} as RailsContext);
+    const resultStr = await collectStreamData(result);
+
+    expect(resultStr).toContain(
+      '<script>(self.REACT_ON_RAILS_RSC_PAYLOAD||=[]).push("{\\"test\\": \\"data\\"}")</script>',
+    );
+  });
+
+  it('should handle multiple RSC payloads', async () => {
+    const mockRSC = createMockStream(['{"test": "data"}', '{"test": "data2"}']);
+    const mockHTML = createMockStream(['<html><body><div>Hello, world!</div></body></html>']);
+
+    jest
+      .spyOn(ReactOnRails, 'getRSCPayloadStreams')
+      .mockReturnValue([{ stream: mockRSC, componentName: 'test' }]);
+
+    const result = injectRSCPayload(mockHTML, {} as RailsContext);
+    const resultStr = await collectStreamData(result);
+
+    expect(resultStr).toContain(
+      '<script>(self.REACT_ON_RAILS_RSC_PAYLOAD||=[]).push("{\\"test\\": \\"data\\"}")</script>',
+    );
+    expect(resultStr).toContain(
+      '<script>(self.REACT_ON_RAILS_RSC_PAYLOAD||=[]).push("{\\"test\\": \\"data2\\"}")</script>',
+    );
+  });
+
+  it('should add all ready html chunks before adding RSC payloads', async () => {
+    const mockRSC = createMockStream(['{"test": "data"}', '{"test": "data2"}']);
+    const mockHTML = createMockStream([
+      '<html><body><div>Hello, world!</div></body></html>',
+      '<div>Next chunk</div>',
+    ]);
+    jest
+      .spyOn(ReactOnRails, 'getRSCPayloadStreams')
+      .mockReturnValue([{ stream: mockRSC, componentName: 'test' }]);
+
+    const result = injectRSCPayload(mockHTML, {} as RailsContext);
+    const resultStr = await collectStreamData(result);
+
+    expect(resultStr).toEqual(
+      '<html><body><div>Hello, world!</div></body></html>' +
+        '<div>Next chunk</div>' +
+        '<script>(self.REACT_ON_RAILS_RSC_PAYLOAD||=[]).push("{\\"test\\": \\"data\\"}")</script>' +
+        '<script>(self.REACT_ON_RAILS_RSC_PAYLOAD||=[]).push("{\\"test\\": \\"data2\\"}")</script>',
+    );
+  });
+
+  it('adds delayed html chunks after RSC payloads', async () => {
+    const mockRSC = createMockStream(['{"test": "data"}', '{"test": "data2"}']);
+    const mockHTML = createMockStream({
+      0: '<html><body><div>Hello, world!</div></body></html>',
+      100: '<div>Next chunk</div>',
+    });
+    jest
+      .spyOn(ReactOnRails, 'getRSCPayloadStreams')
+      .mockReturnValue([{ stream: mockRSC, componentName: 'test' }]);
+
+    const result = injectRSCPayload(mockHTML, {} as RailsContext);
+    const resultStr = await collectStreamData(result);
+
+    expect(resultStr).toEqual(
+      '<html><body><div>Hello, world!</div></body></html>' +
+        '<script>(self.REACT_ON_RAILS_RSC_PAYLOAD||=[]).push("{\\"test\\": \\"data\\"}")</script>' +
+        '<script>(self.REACT_ON_RAILS_RSC_PAYLOAD||=[]).push("{\\"test\\": \\"data2\\"}")</script>' +
+        '<div>Next chunk</div>',
+    );
+  });
+
+  it('handles the case when html is delayed', async () => {
+    const mockRSC = createMockStream({
+      0: '{"test": "data"}',
+      150: '{"test": "data2"}',
+    });
+    const mockHTML = createMockStream({
+      100: ['<html><body><div>Hello, world!</div></body></html>', '<div>Next chunk</div>'],
+      200: '<div>Third chunk</div>',
+    });
+    jest
+      .spyOn(ReactOnRails, 'getRSCPayloadStreams')
+      .mockReturnValue([{ stream: mockRSC, componentName: 'test' }]);
+
+    const result = injectRSCPayload(mockHTML, {} as RailsContext);
+    const resultStr = await collectStreamData(result);
+
+    expect(resultStr).toEqual(
+      '<html><body><div>Hello, world!</div></body></html>' +
+        '<div>Next chunk</div>' +
+        '<script>(self.REACT_ON_RAILS_RSC_PAYLOAD||=[]).push("{\\"test\\": \\"data\\"}")</script>' +
+        '<script>(self.REACT_ON_RAILS_RSC_PAYLOAD||=[]).push("{\\"test\\": \\"data2\\"}")</script>' +
+        '<div>Third chunk</div>',
+    );
+  });
+});

From 9ed0eddce2f94a69de0be9c37d6e91ac36003233 Mon Sep 17 00:00:00 2001
From: Abanoub Ghadban <abanoub@shakacode.com>
Date: Wed, 16 Apr 2025 12:15:15 +0200
Subject: [PATCH 02/50] Add renderRequestId to rendering options and context
 for improved request tracking

- Introduced renderRequestId in render options to uniquely identify each render request.
- Updated server rendering code to include renderRequestId in the context.
- Enhanced client-side rendering to handle and log renderRequestId.
- Modified type definitions to accommodate the new renderRequestId field in RailsContext.
- Improved debugging output in RailsContext component for better visibility of context data.
---
 lib/react_on_rails/helper.rb                     |  3 ++-
 .../react_component/render_options.rb            |  9 ++++++++-
 lib/react_on_rails/server_rendering_js_code.rb   |  1 +
 node_package/src/ClientSideRenderer.ts           | 16 ++++++++++++++--
 node_package/src/types/index.ts                  |  9 +++++++++
 .../dummy/client/app/components/RailsContext.jsx |  3 ++-
 6 files changed, 36 insertions(+), 5 deletions(-)

diff --git a/lib/react_on_rails/helper.rb b/lib/react_on_rails/helper.rb
index 4c8532d313..52844ab6d7 100644
--- a/lib/react_on_rails/helper.rb
+++ b/lib/react_on_rails/helper.rb
@@ -651,7 +651,8 @@ def internal_react_component(react_component_name, options = {})
                                                 "data-trace" => (render_options.trace ? true : nil),
                                                 "data-dom-id" => render_options.dom_id,
                                                 "data-store-dependencies" => render_options.store_dependencies&.to_json,
-                                                "data-force-load" => (render_options.force_load ? true : nil))
+                                                "data-force-load" => (render_options.force_load ? true : nil),
+                                                "data-render-request-id" => render_options.render_request_id)
 
       if render_options.force_load
         component_specification_tag.concat(
diff --git a/lib/react_on_rails/react_component/render_options.rb b/lib/react_on_rails/react_component/render_options.rb
index 9cf334257b..b9d128db61 100644
--- a/lib/react_on_rails/react_component/render_options.rb
+++ b/lib/react_on_rails/react_component/render_options.rb
@@ -15,9 +15,16 @@ class RenderOptions
       def initialize(react_component_name: required("react_component_name"), options: required("options"))
         @react_component_name = react_component_name.camelize
         @options = options
+        # The render_request_id serves as a unique identifier for each render request.
+        # We cannot rely solely on dom_id, as it should be unique for each component on the page,
+        # but the server can render the same page multiple times concurrently for different users.
+        # Therefore, we need an additional unique identifier that can be used both on the client and server.
+        # This ID can also be used to associate specific data with a particular rendered component
+        # on either the server or client.
+        @render_request_id = SecureRandom.uuid
       end
 
-      attr_reader :react_component_name
+      attr_reader :react_component_name, :render_request_id
 
       def throw_js_errors
         options.fetch(:throw_js_errors, false)
diff --git a/lib/react_on_rails/server_rendering_js_code.rb b/lib/react_on_rails/server_rendering_js_code.rb
index dc807b7a28..cd0b8b6773 100644
--- a/lib/react_on_rails/server_rendering_js_code.rb
+++ b/lib/react_on_rails/server_rendering_js_code.rb
@@ -38,6 +38,7 @@ def render(props_string, rails_context, redux_stores, react_component_name, rend
         <<-JS
         (function() {
           var railsContext = #{rails_context};
+          railsContext.componentSpecificMetadata = {renderRequestId: '#{render_options.render_request_id}'};
         #{redux_stores}
           var props = #{props_string};
           return ReactOnRails.serverRenderReactComponent({
diff --git a/node_package/src/ClientSideRenderer.ts b/node_package/src/ClientSideRenderer.ts
index b4978c5985..e1b5239dd0 100644
--- a/node_package/src/ClientSideRenderer.ts
+++ b/node_package/src/ClientSideRenderer.ts
@@ -83,6 +83,18 @@ class ComponentRenderer {
     const { domNodeId } = this;
     const props = el.textContent !== null ? (JSON.parse(el.textContent) as Record<string, unknown>) : {};
     const trace = el.getAttribute('data-trace') === 'true';
+    const renderRequestId = el.getAttribute('data-render-request-id');
+
+    if (!renderRequestId) {
+      console.error(`renderRequestId is missing for ${name} in dom node with id: ${domNodeId}`);
+    }
+
+    const componentSpecificRailsContext = {
+      ...railsContext,
+      componentSpecificMetadata: {
+        renderRequestId: renderRequestId || '',
+      },
+    };
 
     try {
       const domNode = document.getElementById(domNodeId);
@@ -93,7 +105,7 @@ class ComponentRenderer {
         }
 
         if (
-          (await delegateToRenderer(componentObj, props, railsContext, domNodeId, trace)) ||
+          (await delegateToRenderer(componentObj, props, componentSpecificRailsContext, domNodeId, trace)) ||
           // @ts-expect-error The state can change while awaiting delegateToRenderer
           this.state === 'unmounted'
         ) {
@@ -108,7 +120,7 @@ class ComponentRenderer {
           props,
           domNodeId,
           trace,
-          railsContext,
+          railsContext: componentSpecificRailsContext,
           shouldHydrate,
         });
 
diff --git a/node_package/src/types/index.ts b/node_package/src/types/index.ts
index 1c940a9135..19c4b64321 100644
--- a/node_package/src/types/index.ts
+++ b/node_package/src/types/index.ts
@@ -35,6 +35,15 @@ export type RailsContext = {
   search: string | null;
   httpAcceptLanguage: string;
   rscPayloadGenerationUrl?: string;
+  componentSpecificMetadata?: {
+    // The renderRequestId serves as a unique identifier for each render request.
+    // We cannot rely solely on nodeDomId, as it should be unique for each component on the page,
+    // but the server can render the same page multiple times concurrently for different users.
+    // Therefore, we need an additional unique identifier that can be used both on the client and server.
+    // This ID can also be used to associate specific data with a particular rendered component
+    // on either the server or client.
+    renderRequestId: string;
+  };
 } & (
   | {
       serverSide: false;
diff --git a/spec/dummy/client/app/components/RailsContext.jsx b/spec/dummy/client/app/components/RailsContext.jsx
index acfb01a41b..68d5cec378 100644
--- a/spec/dummy/client/app/components/RailsContext.jsx
+++ b/spec/dummy/client/app/components/RailsContext.jsx
@@ -9,12 +9,13 @@ function renderContextRows(railsContext) {
     (accum, value, key) => {
       if (key !== 'serverSide') {
         const className = `js-${key}`;
+        const stringifiedValue = typeof value === 'object' ? JSON.stringify(value) : value;
         accum.push(
           <tr key={className}>
             <td>
               <strong>{key}:&nbsp;</strong>
             </td>
-            <td className={className}>{`${value}`}</td>
+            <td className={className}>{`${stringifiedValue}`}</td>
           </tr>,
         );
       }

From c99b3d3342a1c580393ab4cb6acd64adc398ceaa Mon Sep 17 00:00:00 2001
From: Abanoub Ghadban <abanoub@shakacode.com>
Date: Thu, 17 Apr 2025 09:28:11 +0200
Subject: [PATCH 03/50] tmp

---
 node_package/src/RSCClientRoot.ts             | 105 ++++--------------
 node_package/src/RSCPayloadGenerator.ts       |   7 +-
 node_package/src/RSCProvider.tsx              |  48 ++++++++
 node_package/src/RSCRoute.ts                  |  14 +++
 node_package/src/RSCServerRoot.tsx            |  92 +++------------
 .../src/getReactServerComponent.client.ts     |  98 ++++++++++++++++
 .../src/getReactServerComponent.server.ts     |  90 +++++++++++++++
 node_package/src/injectRSCPayload.ts          |  14 ++-
 node_package/src/types/index.ts               |   3 +-
 package.json                                  |   3 +-
 10 files changed, 303 insertions(+), 171 deletions(-)
 create mode 100644 node_package/src/RSCProvider.tsx
 create mode 100644 node_package/src/RSCRoute.ts
 create mode 100644 node_package/src/getReactServerComponent.client.ts
 create mode 100644 node_package/src/getReactServerComponent.server.ts

diff --git a/node_package/src/RSCClientRoot.ts b/node_package/src/RSCClientRoot.ts
index 49cb294303..f93c256e3f 100644
--- a/node_package/src/RSCClientRoot.ts
+++ b/node_package/src/RSCClientRoot.ts
@@ -2,97 +2,19 @@
 
 import * as React from 'react';
 import * as ReactDOMClient from 'react-dom/client';
-import { createFromReadableStream } from 'react-on-rails-rsc/client';
-import { fetch } from './utils.ts';
-import transformRSCStreamAndReplayConsoleLogs from './transformRSCStreamAndReplayConsoleLogs.ts';
 import { RailsContext, RenderFunction } from './types/index.ts';
 import { ensureReactUseAvailable } from './reactApis.cts';
+import { createRSCProvider } from './RSCProvider.tsx';
+import { getReactServerComponent, getPreloadedReactServerComponents } from './getReactServerComponent.client.ts';
+import RSCRoute from './RSCRoute.ts';
 
 ensureReactUseAvailable();
 
-declare global {
-  interface Window {
-    REACT_ON_RAILS_RSC_PAYLOAD?: string[];
-  }
-}
-
 export type RSCClientRootProps = {
   componentName: string;
-  rscPayloadGenerationUrlPath: string;
   componentProps?: unknown;
 };
 
-const createFromFetch = async (fetchPromise: Promise<Response>) => {
-  const response = await fetchPromise;
-  const stream = response.body;
-  if (!stream) {
-    throw new Error('No stream found in response');
-  }
-  const transformedStream = transformRSCStreamAndReplayConsoleLogs(stream);
-  return createFromReadableStream<React.ReactNode>(transformedStream);
-};
-
-const fetchRSC = ({ componentName, rscPayloadGenerationUrlPath, componentProps }: RSCClientRootProps) => {
-  const propsString = JSON.stringify(componentProps);
-  const strippedUrlPath = rscPayloadGenerationUrlPath.replace(/^\/|\/$/g, '');
-  return createFromFetch(fetch(`/${strippedUrlPath}/${componentName}?props=${propsString}`));
-};
-
-const createRSCStreamFromPage = () => {
-  let streamController: ReadableStreamController<string> | undefined;
-  const stream = new ReadableStream<string>({
-    start(controller) {
-      if (typeof window === 'undefined') {
-        return;
-      }
-      const handleChunk = (chunk: string) => {
-        controller.enqueue(chunk);
-      };
-
-      // The RSC payload transfer mechanism works in two possible scenarios:
-      // 1. RSCClientRoot executes first:
-      //    - Initializes REACT_ON_RAILS_RSC_PAYLOAD as an empty array
-      //    - Overrides the push function to handle incoming chunks
-      //    - When server scripts run later, they use the overridden push function
-      // 2. Server scripts execute first:
-      //    - Initialize REACT_ON_RAILS_RSC_PAYLOAD as an empty array
-      //    - Buffer RSC payload chunks in the array
-      //    - When RSCClientRoot runs, it reads buffered chunks and overrides push
-      //
-      // Key points:
-      // - The array is never reassigned, ensuring data consistency
-      // - The push function override ensures all chunks are properly handled
-      // - Execution order is irrelevant - both scenarios work correctly
-      if (!window.REACT_ON_RAILS_RSC_PAYLOAD) {
-        window.REACT_ON_RAILS_RSC_PAYLOAD = [];
-      }
-      window.REACT_ON_RAILS_RSC_PAYLOAD.forEach(handleChunk);
-      const originalPush = window.REACT_ON_RAILS_RSC_PAYLOAD.push;
-      window.REACT_ON_RAILS_RSC_PAYLOAD.push = (...chunks) => {
-        chunks.forEach(handleChunk);
-        return originalPush.call(window.REACT_ON_RAILS_RSC_PAYLOAD, ...chunks);
-      };
-      streamController = controller;
-    },
-  });
-
-  if (typeof document !== 'undefined' && document.readyState === 'loading') {
-    document.addEventListener('DOMContentLoaded', () => {
-      streamController?.close();
-    });
-  } else {
-    streamController?.close();
-  }
-
-  return stream;
-};
-
-const createFromRSCStream = () => {
-  const stream = createRSCStreamFromPage();
-  const transformedStream = transformRSCStreamAndReplayConsoleLogs(stream);
-  return createFromReadableStream<React.ReactNode>(transformedStream);
-};
-
 /**
  * RSCClientRoot is a React component that handles client-side rendering of React Server Components (RSC).
  * It manages the fetching, caching, and rendering of RSC payloads from the server.
@@ -107,10 +29,25 @@ const createFromRSCStream = () => {
  * @requires react-on-rails-rsc
  */
 const RSCClientRoot: RenderFunction = async (
-  { componentName, rscPayloadGenerationUrlPath, componentProps }: RSCClientRootProps,
-  _railsContext?: RailsContext,
+  { componentName, componentProps }: RSCClientRootProps,
+  railsContext?: RailsContext,
   domNodeId?: string,
 ) => {
+  if (!railsContext) {
+    throw new Error('RSCClientRoot: No railsContext provided');
+  }
+
+  const RSCProvider = await createRSCProvider({
+    railsContext,
+    getServerComponent: getReactServerComponent,
+    getPreloadedComponents: getPreloadedReactServerComponents,
+  });
+
+  // eslint-disable-next-line react/no-children-prop
+  const root = React.createElement(RSCProvider, {
+    children: React.createElement(RSCRoute, { componentName, componentProps }),
+  });
+
   if (!domNodeId) {
     throw new Error('RSCClientRoot: No domNodeId provided');
   }
@@ -119,10 +56,8 @@ const RSCClientRoot: RenderFunction = async (
     throw new Error(`RSCClientRoot: No DOM node found for id: ${domNodeId}`);
   }
   if (domNode.innerHTML) {
-    const root = await createFromRSCStream();
     ReactDOMClient.hydrateRoot(domNode, root);
   } else {
-    const root = await fetchRSC({ componentName, rscPayloadGenerationUrlPath, componentProps });
     ReactDOMClient.createRoot(domNode).render(root);
   }
   // Added only to satisfy the return type of RenderFunction
diff --git a/node_package/src/RSCPayloadGenerator.ts b/node_package/src/RSCPayloadGenerator.ts
index 0157b4b292..dafca75ac6 100644
--- a/node_package/src/RSCPayloadGenerator.ts
+++ b/node_package/src/RSCPayloadGenerator.ts
@@ -4,7 +4,7 @@ import { RailsContext } from './types';
 declare global {
   function generateRSCPayload(
     componentName: string,
-    props: Record<string, unknown>,
+    props: unknown,
     railsContext: RailsContext,
   ): Promise<NodeJS.ReadableStream>;
 }
@@ -13,13 +13,14 @@ const mapRailsContextToRSCPayloadStreams = new Map<
   RailsContext,
   {
     componentName: string;
+    props: unknown;
     stream: NodeJS.ReadableStream;
   }[]
 >();
 
 export const getRSCPayloadStream = async (
   componentName: string,
-  props: Record<string, unknown>,
+  props: unknown,
   railsContext: RailsContext,
 ): Promise<NodeJS.ReadableStream> => {
   if (typeof generateRSCPayload !== 'function') {
@@ -39,6 +40,7 @@ export const getRSCPayloadStream = async (
 
   streams.push({
     componentName,
+    props,
     stream: stream2,
   });
   mapRailsContextToRSCPayloadStreams.set(railsContext, streams);
@@ -49,6 +51,7 @@ export const getRSCPayloadStreams = (
   railsContext: RailsContext,
 ): {
   componentName: string;
+  props: unknown;
   stream: NodeJS.ReadableStream;
 }[] => mapRailsContextToRSCPayloadStreams.get(railsContext) ?? [];
 
diff --git a/node_package/src/RSCProvider.tsx b/node_package/src/RSCProvider.tsx
new file mode 100644
index 0000000000..7485bd5a58
--- /dev/null
+++ b/node_package/src/RSCProvider.tsx
@@ -0,0 +1,48 @@
+import * as React from 'react';
+import { RailsContext } from './types';
+import { getReactServerComponent, getPreloadedReactServerComponents } from './getReactServerComponent.client';
+
+type RSCContextType = {
+  getCachedComponent: (componentName: string, componentProps: unknown) => React.ReactNode;
+
+  getComponent: (componentName: string, componentProps: unknown) => Promise<React.ReactNode>;
+};
+
+const RSCContext = React.createContext<RSCContextType | undefined>(undefined);
+
+export const createRSCProvider = async ({
+  railsContext,
+  getServerComponent,
+  getPreloadedComponents,
+}: {
+  railsContext: RailsContext;
+  getServerComponent: typeof getReactServerComponent;
+  getPreloadedComponents?: typeof getPreloadedReactServerComponents;
+}) => {
+  const cachedComponents = (await getPreloadedComponents?.(railsContext)) ?? {};
+  const getCachedComponent = (componentName: string, componentProps: unknown) => {
+    const key = `${componentName}-${JSON.stringify(componentProps)}`;
+    return cachedComponents[key];
+  };
+
+  const getComponent = async (componentName: string, componentProps: unknown) => {
+    const cachedComponent = getCachedComponent(componentName, componentProps);
+    if (cachedComponent) {
+      return cachedComponent;
+    }
+    return getServerComponent({ componentName, componentProps, railsContext });
+  };
+
+  return ({ children }: { children: React.ReactNode }) => {
+    // eslint-disable-next-line react/jsx-no-constructed-context-values
+    return <RSCContext.Provider value={{ getCachedComponent, getComponent }}>{children}</RSCContext.Provider>;
+  };
+};
+
+export const useRSC = () => {
+  const context = React.useContext(RSCContext);
+  if (!context) {
+    throw new Error('useRSC must be used within a RSCProvider');
+  }
+  return context;
+};
diff --git a/node_package/src/RSCRoute.ts b/node_package/src/RSCRoute.ts
new file mode 100644
index 0000000000..34e214b628
--- /dev/null
+++ b/node_package/src/RSCRoute.ts
@@ -0,0 +1,14 @@
+import * as React from 'react';
+import { RSCClientRootProps } from './RSCClientRoot';
+import { useRSC } from './RSCProvider';
+
+const RSCRoute = ({ componentName, componentProps }: RSCClientRootProps) => {
+  const { getComponent, getCachedComponent } = useRSC();
+  let component = getCachedComponent(componentName, componentProps);
+  if (!component) {
+    component = React.use(getComponent(componentName, componentProps));
+  }
+  return component;
+};
+
+export default RSCRoute;
diff --git a/node_package/src/RSCServerRoot.tsx b/node_package/src/RSCServerRoot.tsx
index bccf43f2cc..450d00840e 100644
--- a/node_package/src/RSCServerRoot.tsx
+++ b/node_package/src/RSCServerRoot.tsx
@@ -1,95 +1,33 @@
 import * as React from 'react';
-import { createFromNodeStream } from 'react-on-rails-rsc/client.node';
 import type { RenderFunction, RailsContext } from './types/index.ts';
-import transformRSCStream from './transformRSCNodeStream.ts';
-import loadJsonFile from './loadJsonFile.ts';
-import { ensureReactUseAvailable } from './reactApis.cts';
-
-ensureReactUseAvailable();
+import getReactServerComponent from './getReactServerComponent.server.ts';
+import { createRSCProvider } from './RSCProvider.tsx';
+import RSCRoute from './RSCRoute.ts';
 
 type RSCServerRootProps = {
   componentName: string;
-  componentProps: Record<string, unknown>;
-};
-
-const { use } = React;
-
-const createFromReactOnRailsNodeStream = (
-  stream: NodeJS.ReadableStream,
-  ssrManifest: Record<string, unknown>,
-) => {
-  const transformedStream = transformRSCStream(stream);
-  return createFromNodeStream(transformedStream, ssrManifest);
-};
-
-const createSSRManifest = async (
-  reactServerManifestFileName: string,
-  reactClientManifestFileName: string,
-) => {
-  const [reactServerManifest, reactClientManifest] = await Promise.all([
-    loadJsonFile(reactServerManifestFileName) as Promise<Record<string, { id: string; chunks: string[] }>>,
-    loadJsonFile(reactClientManifestFileName) as Promise<Record<string, { id: string }>>,
-  ]);
-
-  const moduleMap: Record<string, unknown> = {};
-  Object.entries(reactClientManifest).forEach(([aboluteFileUrl, clientFileBundlingInfo]) => {
-    const { id, chunks } = reactServerManifest[aboluteFileUrl];
-    moduleMap[clientFileBundlingInfo.id] = {
-      '*': {
-        id,
-        chunks,
-        name: '*',
-      },
-    };
-  });
-
-  const ssrManifest = {
-    // The `moduleLoading` property is utilized by the React runtime to load JavaScript modules.
-    // It can accept options such as `prefix` and `crossOrigin` to specify the path and crossorigin attribute for the modules.
-    // In our case, since the server code is bundled into a single bundle, there is no need to load additional JavaScript modules.
-    // As a result, we set this property to an empty object because it will not be used.
-    moduleLoading: {},
-    moduleMap,
-  };
-
-  return ssrManifest;
+  componentProps: unknown;
 };
 
 const RSCServerRoot: RenderFunction = async (
   { componentName, componentProps }: RSCServerRootProps,
   railsContext?: RailsContext,
 ) => {
-  if (
-    !railsContext?.serverSide ||
-    !railsContext?.reactClientManifestFileName ||
-    !railsContext?.reactServerClientManifestFileName
-  ) {
-    throw new Error(
-      'serverClientManifestFileName and reactServerClientManifestFileName are required. ' +
-        'Please ensure that React Server Component webpack configurations are properly set ' +
-        'as stated in the React Server Component tutorial. ' +
-        'Make sure to use "stream_react_component" instead of "react_component" to SSR a server component.',
-    );
-  }
-
-  if (typeof ReactOnRails.getRSCPayloadStream !== 'function') {
-    throw new Error(
-      'ReactOnRails.getRSCPayloadStream is not defined. This likely means that you are not building the server bundle correctly. Please ensure that your server bundle is targeting Node.js',
-    );
+  if (!railsContext) {
+    throw new Error('RSCClientRoot: No railsContext provided');
   }
 
-  const ssrManifest = await createSSRManifest(
-    railsContext.reactServerClientManifestFileName,
-    railsContext.reactClientManifestFileName,
-  );
-  const rscPayloadStream = await ReactOnRails.getRSCPayloadStream(
-    componentName,
-    componentProps,
+  const RSCProvider = await createRSCProvider({
     railsContext,
-  );
+    getServerComponent: getReactServerComponent,
+  });
+
+  // eslint-disable-next-line react/no-children-prop
+  const root = React.createElement(RSCProvider, {
+    children: React.createElement(RSCRoute, { componentName, componentProps }),
+  });
 
-  const serverComponentElement = createFromReactOnRailsNodeStream(rscPayloadStream, ssrManifest);
-  return () => use(serverComponentElement);
+  return () => root;
 };
 
 export default RSCServerRoot;
diff --git a/node_package/src/getReactServerComponent.client.ts b/node_package/src/getReactServerComponent.client.ts
new file mode 100644
index 0000000000..d5f30dc692
--- /dev/null
+++ b/node_package/src/getReactServerComponent.client.ts
@@ -0,0 +1,98 @@
+import * as React from 'react';
+import { createFromReadableStream } from 'react-on-rails-rsc/client';
+import { fetch } from './utils';
+import transformRSCStreamAndReplayConsoleLogs from './transformRSCStreamAndReplayConsoleLogs';
+import { RailsContext } from './types';
+
+declare global {
+  interface Window {
+    REACT_ON_RAILS_RSC_PAYLOADS?: Record<string, string[]>;
+  }
+}
+
+export type ClientGetReactServerComponentProps = {
+  componentName: string;
+  componentProps: unknown;
+  railsContext: RailsContext;
+};
+
+const createFromFetch = async (fetchPromise: Promise<Response>) => {
+  const response = await fetchPromise;
+  const stream = response.body;
+  if (!stream) {
+    throw new Error('No stream found in response');
+  }
+  const transformedStream = transformRSCStreamAndReplayConsoleLogs(stream);
+  return createFromReadableStream<React.ReactNode>(transformedStream);
+};
+
+const fetchRSC = ({ componentName, componentProps, railsContext }: ClientGetReactServerComponentProps) => {
+  const propsString = JSON.stringify(componentProps);
+  const { rscPayloadGenerationUrl } = railsContext;
+  const strippedUrlPath = rscPayloadGenerationUrl?.replace(/^\/|\/$/g, '');
+  return createFromFetch(fetch(`/${strippedUrlPath}/${componentName}?props=${propsString}`));
+};
+
+const createRSCStreamFromArray = (payloads: string[]) => {
+  let streamController: ReadableStreamController<string> | undefined;
+  const stream = new ReadableStream<string>({
+    start(controller) {
+      if (typeof window === 'undefined') {
+        return;
+      }
+      const handleChunk = (chunk: string) => {
+        controller.enqueue(chunk);
+      };
+
+      payloads.forEach(handleChunk);
+      const originalPush = payloads.push;
+      // eslint-disable-next-line no-param-reassign
+      payloads.push = (...chunks) => {
+        chunks.forEach(handleChunk);
+        return originalPush.call(payloads, ...chunks);
+      };
+      streamController = controller;
+    },
+  });
+
+  if (typeof document !== 'undefined' && document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', () => {
+      streamController?.close();
+    });
+  } else {
+    streamController?.close();
+  }
+
+  return stream;
+};
+
+const createFromPreloadedPayloads = (payloads: string[]) => {
+  const stream = createRSCStreamFromArray(payloads);
+  const transformedStream = transformRSCStreamAndReplayConsoleLogs(stream);
+  return createFromReadableStream<React.ReactNode>(transformedStream);
+};
+
+export const getReactServerComponent = ({
+  componentName,
+  componentProps,
+  railsContext,
+}: ClientGetReactServerComponentProps) => {
+  const componentKey = `${componentName}-${JSON.stringify(componentProps)}-${railsContext.componentSpecificMetadata?.renderRequestId}`;
+  const payloads = window.REACT_ON_RAILS_RSC_PAYLOADS?.[componentKey];
+  if (payloads) {
+    return createFromPreloadedPayloads(payloads);
+  }
+  return fetchRSC({ componentName, componentProps, railsContext });
+};
+
+export const getPreloadedReactServerComponents = (railsContext: RailsContext) => {
+  return Promise.all(
+    Object.entries(window.REACT_ON_RAILS_RSC_PAYLOADS ?? {})
+      .filter(([cacheKey]) =>
+        cacheKey.includes(railsContext.componentSpecificMetadata?.renderRequestId ?? ''),
+      )
+      .map(async ([cacheKey, payloads]) => ({
+        [cacheKey]: await createFromPreloadedPayloads(payloads),
+      })),
+  ).then((components) => Object.assign({}, ...components) as Record<string, React.ReactNode>);
+};
diff --git a/node_package/src/getReactServerComponent.server.ts b/node_package/src/getReactServerComponent.server.ts
new file mode 100644
index 0000000000..909ec08467
--- /dev/null
+++ b/node_package/src/getReactServerComponent.server.ts
@@ -0,0 +1,90 @@
+import { createFromNodeStream } from 'react-on-rails-rsc/client.node';
+import transformRSCStream from './transformRSCNodeStream';
+import loadJsonFile from './loadJsonFile';
+import { RailsContext } from './types';
+
+type RSCServerRootProps = {
+  componentName: string;
+  componentProps: unknown;
+  railsContext: RailsContext;
+};
+
+const createFromReactOnRailsNodeStream = (
+  stream: NodeJS.ReadableStream,
+  ssrManifest: Record<string, unknown>,
+) => {
+  const transformedStream = transformRSCStream(stream);
+  return createFromNodeStream(transformedStream, ssrManifest);
+};
+
+const createSSRManifest = async (
+  reactServerManifestFileName: string,
+  reactClientManifestFileName: string,
+) => {
+  const [reactServerManifest, reactClientManifest] = await Promise.all([
+    loadJsonFile(reactServerManifestFileName) as Promise<Record<string, { id: string; chunks: string[] }>>,
+    loadJsonFile(reactClientManifestFileName) as Promise<Record<string, { id: string }>>,
+  ]);
+
+  const moduleMap: Record<string, unknown> = {};
+  Object.entries(reactClientManifest).forEach(([aboluteFileUrl, clientFileBundlingInfo]) => {
+    const { id, chunks } = reactServerManifest[aboluteFileUrl];
+    moduleMap[clientFileBundlingInfo.id] = {
+      '*': {
+        id,
+        chunks,
+        name: '*',
+      },
+    };
+  });
+
+  const ssrManifest = {
+    // The `moduleLoading` property is utilized by the React runtime to load JavaScript modules.
+    // It can accept options such as `prefix` and `crossOrigin` to specify the path and crossorigin attribute for the modules.
+    // In our case, since the server code is bundled into a single bundle, there is no need to load additional JavaScript modules.
+    // As a result, we set this property to an empty object because it will not be used.
+    moduleLoading: {},
+    moduleMap,
+  };
+
+  return ssrManifest;
+};
+
+const getReactServerComponent = async ({
+  componentName,
+  componentProps,
+  railsContext,
+}: RSCServerRootProps) => {
+  if (
+    !railsContext?.serverSide ||
+    !railsContext?.reactClientManifestFileName ||
+    !railsContext?.reactServerClientManifestFileName
+  ) {
+    throw new Error(
+      'serverClientManifestFileName and reactServerClientManifestFileName are required. ' +
+        'Please ensure that React Server Component webpack configurations are properly set ' +
+        'as stated in the React Server Component tutorial. ' +
+        'Make sure to use "stream_react_component" instead of "react_component" to SSR a server component.',
+    );
+  }
+
+  if (typeof ReactOnRails.getRSCPayloadStream !== 'function') {
+    throw new Error(
+      'ReactOnRails.getRSCPayloadStream is not defined. This likely means that you are not building the server bundle correctly. Please ensure that your server bundle is targeting Node.js',
+    );
+  }
+
+  const ssrManifest = await createSSRManifest(
+    railsContext.reactServerClientManifestFileName,
+    railsContext.reactClientManifestFileName,
+  );
+  const rscPayloadStream = await ReactOnRails.getRSCPayloadStream(
+    componentName,
+    componentProps,
+    railsContext,
+  );
+
+  return createFromReactOnRailsNodeStream(rscPayloadStream, ssrManifest);
+};
+
+export default getReactServerComponent;
diff --git a/node_package/src/injectRSCPayload.ts b/node_package/src/injectRSCPayload.ts
index 0c94e0dac3..d40a62c0dc 100644
--- a/node_package/src/injectRSCPayload.ts
+++ b/node_package/src/injectRSCPayload.ts
@@ -14,8 +14,10 @@ function escapeScript(script: string) {
   return script.replace(/<!--/g, '<\\!--').replace(/<\/(script)/gi, '</\\$1');
 }
 
-function writeChunk(chunk: string, transform: Transform) {
-  transform.push(`<script>${escapeScript(`(self.REACT_ON_RAILS_RSC_PAYLOAD||=[]).push(${chunk})`)}</script>`);
+function writeChunk(chunk: string, transform: Transform, cacheKey: string) {
+  transform.push(
+    `<script>${escapeScript(`((self.REACT_ON_RAILS_RSC_PAYLOADS||={})[${cacheKey}]||=[]).push(${chunk})`)}</script>`,
+  );
 }
 
 export default function injectRSCPayload(
@@ -33,14 +35,16 @@ export default function injectRSCPayload(
   // Start reading RSC stream immediately
   const startRSC = async () => {
     try {
-      for await (const chunk of ReactOnRails.getRSCPayloadStreams?.(railsContext)?.[0]?.stream ?? []) {
+      const { stream, props, componentName } = ReactOnRails.getRSCPayloadStreams?.(railsContext)?.[0] ?? {};
+      const cacheKey = `${componentName}-${JSON.stringify(props)}-${railsContext.componentSpecificMetadata?.renderRequestId}`;
+      for await (const chunk of stream ?? []) {
         try {
           const decodedChunk = typeof chunk === 'string' ? chunk : decoder.decode(chunk);
-          writeChunk(JSON.stringify(decodedChunk), resultStream);
+          writeChunk(JSON.stringify(decodedChunk), resultStream, cacheKey);
         } catch (_) {
           const decodedChunk = typeof chunk === 'string' ? chunk : String.fromCodePoint(...chunk);
           const base64 = JSON.stringify(btoa(decodedChunk));
-          writeChunk(`Uint8Array.from(atob(${base64}), m => m.codePointAt(0))`, resultStream);
+          writeChunk(`Uint8Array.from(atob(${base64}), m => m.codePointAt(0))`, resultStream, cacheKey);
         }
       }
     } catch (err) {
diff --git a/node_package/src/types/index.ts b/node_package/src/types/index.ts
index 19c4b64321..18d50b205e 100644
--- a/node_package/src/types/index.ts
+++ b/node_package/src/types/index.ts
@@ -416,7 +416,7 @@ export interface ReactOnRailsInternal extends ReactOnRails {
    */
   getRSCPayloadStream?: (
     componentName: string,
-    props: Record<string, unknown>,
+    props: unknown,
     railsContext: RailsContext,
   ) => Promise<NodeJS.ReadableStream>;
 
@@ -428,6 +428,7 @@ export interface ReactOnRailsInternal extends ReactOnRails {
     */
   getRSCPayloadStreams?: (railsContext: RailsContext) => {
     componentName: string;
+    props: unknown;
     stream: NodeJS.ReadableStream;
   }[];
 
diff --git a/package.json b/package.json
index 872632fde2..f72040c0e9 100644
--- a/package.json
+++ b/package.json
@@ -15,7 +15,8 @@
     "./registerServerComponent/server": {
       "react-server": "./node_package/lib/registerServerComponent/server.rsc.js",
       "default": "./node_package/lib/registerServerComponent/server.js"
-    }
+    },
+    "./RSCServerRoot": "./node_package/lib/RSCServerRoot.js"
   },
   "directories": {
     "doc": "docs"

From 5ca2a9cad47695dfaa77ed8d7c93c93877b7cd91 Mon Sep 17 00:00:00 2001
From: Abanoub Ghadban <abanoub@shakacode.com>
Date: Fri, 25 Apr 2025 10:24:28 +0300
Subject: [PATCH 04/50] trace used rsc payload streams on server and pass them
 to client

---
 lib/react_on_rails/packs_generator.rb         | 43 ++++++++++++--
 .../{RSCClientRoot.ts => RSCClientRoot.tsx}   | 19 +++---
 node_package/src/RSCPayloadGenerator.ts       | 40 +++++++++----
 node_package/src/RSCProvider.tsx              | 20 ++++++-
 node_package/src/RSCRoute.ts                  |  8 ++-
 node_package/src/RSCServerRoot.tsx            | 19 +++---
 node_package/src/ReactOnRails.node.ts         |  8 ++-
 .../baseRegisterServerComponent/client.tsx    | 59 +++++++++++++++++++
 .../baseRegisterServerComponent/server.tsx    | 53 +++++++++++++++++
 .../src/getReactServerComponent.server.ts     |  4 +-
 node_package/src/injectRSCPayload.ts          | 46 +++++++++++----
 node_package/src/registerRouter/client.tsx    | 19 ++++++
 node_package/src/registerRouter/server.rsc.ts |  5 ++
 node_package/src/registerRouter/server.tsx    | 26 ++++++++
 .../src/registerServerComponent/client.ts     | 29 ++-------
 .../src/registerServerComponent/server.ts     | 15 ++---
 node_package/src/types/index.ts               |  8 +++
 package.json                                  | 12 +++-
 18 files changed, 341 insertions(+), 92 deletions(-)
 rename node_package/src/{RSCClientRoot.ts => RSCClientRoot.tsx} (83%)
 create mode 100644 node_package/src/baseRegisterServerComponent/client.tsx
 create mode 100644 node_package/src/baseRegisterServerComponent/server.tsx
 create mode 100644 node_package/src/registerRouter/client.tsx
 create mode 100644 node_package/src/registerRouter/server.rsc.ts
 create mode 100644 node_package/src/registerRouter/server.tsx

diff --git a/lib/react_on_rails/packs_generator.rb b/lib/react_on_rails/packs_generator.rb
index ae4169162f..c6f18d6526 100644
--- a/lib/react_on_rails/packs_generator.rb
+++ b/lib/react_on_rails/packs_generator.rb
@@ -87,11 +87,30 @@ def client_entrypoint?(file_path)
       first_js_statement_in_code(content).match?(/^["']use client["'](?:;|\s|$)/)
     end
 
+    def router_entrypoint?(file_path)
+      content = File.read(file_path)
+      # has "use router" directive. It can be "use router" or 'use router'
+      first_js_statement_in_code(content).match?(/^["']use router["'](?:;|\s|$)/)
+    end
+
     def pack_file_contents(file_path)
       registered_component_name = component_name(file_path)
       load_server_components = ReactOnRails::Utils.react_on_rails_pro? &&
                                ReactOnRailsPro.configuration.enable_rsc_support
 
+      # Check for router component first
+      if load_server_components && router_entrypoint?(file_path)
+        relative_component_path = relative_component_path_from_generated_pack(file_path)
+        return <<~FILE_CONTENT.strip
+          import registerRouter from 'react-on-rails/registerRouter/client';
+          import #{registered_component_name} from '#{relative_component_path}';
+
+          registerRouter({
+            #{registered_component_name},
+          });
+        FILE_CONTENT
+      end
+
       if load_server_components && !client_entrypoint?(file_path)
         rsc_payload_generation_url_path = ReactOnRailsPro.configuration.rsc_payload_generation_url_path
 
@@ -121,11 +140,12 @@ def create_server_pack
       puts(Rainbow("Generated Server Bundle: #{generated_server_bundle_file_path}").orange)
     end
 
-    def build_server_pack_content(component_on_server_imports, server_components, client_components)
+    def build_server_pack_content(component_on_server_imports, server_components, client_components, router_components)
       content = <<~FILE_CONTENT
         import ReactOnRails from 'react-on-rails';
 
         #{component_on_server_imports.join("\n")}\n
+        #{router_components.any? ? "import registerRouter from 'react-on-rails/registerRouter/server';" : ''}
       FILE_CONTENT
 
       if server_components.any?
@@ -135,10 +155,16 @@ def build_server_pack_content(component_on_server_imports, server_components, cl
         FILE_CONTENT
       end
 
+      if router_components.any?
+        content += <<~FILE_CONTENT
+          registerRouter({#{router_components.join(",\n")}});\n
+        FILE_CONTENT
+      end
+
       content + "ReactOnRails.register({#{client_components.join(",\n")}});"
     end
 
-    def generated_server_pack_file_content
+    def generated_server_pack_file_content # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity
       common_components_for_server_bundle = common_component_to_path.delete_if { |k| server_component_to_path.key?(k) }
       component_for_server_registration_to_path = common_components_for_server_bundle.merge(server_component_to_path)
 
@@ -148,15 +174,24 @@ def generated_server_pack_file_content
 
       load_server_components = ReactOnRails::Utils.react_on_rails_pro? &&
                                ReactOnRailsPro.configuration.enable_rsc_support
+
+      # Identify router components
+      router_components = component_for_server_registration_to_path.keys.select do |name|
+        component_path = component_for_server_registration_to_path[name]
+        router_entrypoint?(component_path)
+      end
+
       server_components = component_for_server_registration_to_path.keys.delete_if do |name|
         next true unless load_server_components
+        next true if router_components.include?(name)
 
         component_path = component_for_server_registration_to_path[name]
         client_entrypoint?(component_path)
       end
-      client_components = component_for_server_registration_to_path.keys - server_components
 
-      build_server_pack_content(component_on_server_imports, server_components, client_components)
+      client_components = component_for_server_registration_to_path.keys - server_components - router_components
+
+      build_server_pack_content(component_on_server_imports, server_components, client_components, router_components)
     end
 
     def add_generated_pack_to_server_bundle
diff --git a/node_package/src/RSCClientRoot.ts b/node_package/src/RSCClientRoot.tsx
similarity index 83%
rename from node_package/src/RSCClientRoot.ts
rename to node_package/src/RSCClientRoot.tsx
index f93c256e3f..b80aa6b0f5 100644
--- a/node_package/src/RSCClientRoot.ts
+++ b/node_package/src/RSCClientRoot.tsx
@@ -6,14 +6,10 @@ import { RailsContext, RenderFunction } from './types/index.ts';
 import { ensureReactUseAvailable } from './reactApis.cts';
 import { createRSCProvider } from './RSCProvider.tsx';
 import { getReactServerComponent, getPreloadedReactServerComponents } from './getReactServerComponent.client.ts';
-import RSCRoute from './RSCRoute.ts';
 
 ensureReactUseAvailable();
 
-export type RSCClientRootProps = {
-  componentName: string;
-  componentProps?: unknown;
-};
+export type RSCClientRootProps = { ServerComponentContainer: ReactComponent };
 
 /**
  * RSCClientRoot is a React component that handles client-side rendering of React Server Components (RSC).
@@ -29,7 +25,7 @@ export type RSCClientRootProps = {
  * @requires react-on-rails-rsc
  */
 const RSCClientRoot: RenderFunction = async (
-  { componentName, componentProps }: RSCClientRootProps,
+  { ServerComponentContainer }: RSCClientRootProps,
   railsContext?: RailsContext,
   domNodeId?: string,
 ) => {
@@ -43,10 +39,13 @@ const RSCClientRoot: RenderFunction = async (
     getPreloadedComponents: getPreloadedReactServerComponents,
   });
 
-  // eslint-disable-next-line react/no-children-prop
-  const root = React.createElement(RSCProvider, {
-    children: React.createElement(RSCRoute, { componentName, componentProps }),
-  });
+  const SuspensableRSCRoute = (
+    <React.Suspense fallback={null}>
+      <ServerComponentContainer />
+    </React.Suspense>
+  );
+
+  const root = <RSCProvider>{SuspensableRSCRoute}</RSCProvider>;
 
   if (!domNodeId) {
     throw new Error('RSCClientRoot: No domNodeId provided');
diff --git a/node_package/src/RSCPayloadGenerator.ts b/node_package/src/RSCPayloadGenerator.ts
index dafca75ac6..57fadf1ab4 100644
--- a/node_package/src/RSCPayloadGenerator.ts
+++ b/node_package/src/RSCPayloadGenerator.ts
@@ -9,14 +9,27 @@ declare global {
   ): Promise<NodeJS.ReadableStream>;
 }
 
-const mapRailsContextToRSCPayloadStreams = new Map<
-  RailsContext,
-  {
-    componentName: string;
-    props: unknown;
-    stream: NodeJS.ReadableStream;
-  }[]
->();
+export type RSCPayloadStreamInfo = {
+  stream: NodeJS.ReadableStream;
+  props: unknown;
+  componentName: string;
+};
+
+export type RSCPayloadCallback = (streamInfo: RSCPayloadStreamInfo) => void;
+
+const mapRailsContextToRSCPayloadStreams = new Map<RailsContext, RSCPayloadStreamInfo[]>();
+
+const rscPayloadCallbacks = new Map<RailsContext, Array<RSCPayloadCallback>>();
+
+export const onRSCPayloadGenerated = (railsContext: RailsContext, callback: RSCPayloadCallback) => {
+  const callbacks = rscPayloadCallbacks.get(railsContext) || [];
+  callbacks.push(callback);
+  rscPayloadCallbacks.set(railsContext, callbacks);
+
+  // Call callback for any existing streams for this context
+  const existingStreams = mapRailsContextToRSCPayloadStreams.get(railsContext) || [];
+  existingStreams.forEach((streamInfo) => callback(streamInfo));
+};
 
 export const getRSCPayloadStream = async (
   componentName: string,
@@ -38,12 +51,18 @@ export const getRSCPayloadStream = async (
   const stream2 = new PassThrough();
   stream1.pipe(stream2);
 
-  streams.push({
+  const streamInfo: RSCPayloadStreamInfo = {
     componentName,
     props,
     stream: stream2,
-  });
+  };
+  streams.push(streamInfo);
   mapRailsContextToRSCPayloadStreams.set(railsContext, streams);
+
+  // Notify callbacks about the new stream
+  const callbacks = rscPayloadCallbacks.get(railsContext) || [];
+  callbacks.forEach((callback) => callback(streamInfo));
+
   return stream1;
 };
 
@@ -57,4 +76,5 @@ export const getRSCPayloadStreams = (
 
 export const clearRSCPayloadStreams = (railsContext: RailsContext) => {
   mapRailsContextToRSCPayloadStreams.delete(railsContext);
+  rscPayloadCallbacks.delete(railsContext);
 };
diff --git a/node_package/src/RSCProvider.tsx b/node_package/src/RSCProvider.tsx
index 7485bd5a58..873b62dcb3 100644
--- a/node_package/src/RSCProvider.tsx
+++ b/node_package/src/RSCProvider.tsx
@@ -20,8 +20,14 @@ export const createRSCProvider = async ({
   getPreloadedComponents?: typeof getPreloadedReactServerComponents;
 }) => {
   const cachedComponents = (await getPreloadedComponents?.(railsContext)) ?? {};
+  const fetchRSCPromises: Record<string, Promise<React.ReactNode>> = {};
+
+  const generateCacheKey = (componentName: string, componentProps: unknown) => {
+    return `${componentName}-${JSON.stringify(componentProps)}-${railsContext.componentSpecificMetadata?.renderRequestId}`;
+  };
+
   const getCachedComponent = (componentName: string, componentProps: unknown) => {
-    const key = `${componentName}-${JSON.stringify(componentProps)}`;
+    const key = generateCacheKey(componentName, componentProps);
     return cachedComponents[key];
   };
 
@@ -30,7 +36,17 @@ export const createRSCProvider = async ({
     if (cachedComponent) {
       return cachedComponent;
     }
-    return getServerComponent({ componentName, componentProps, railsContext });
+    const key = generateCacheKey(componentName, componentProps);
+    if (key in fetchRSCPromises) {
+      return fetchRSCPromises[key];
+    }
+
+    const promise = getServerComponent({ componentName, componentProps, railsContext }).then((rsc) => {
+      cachedComponents[key] = rsc;
+      return rsc;
+    });
+    fetchRSCPromises[key] = promise;
+    return promise;
   };
 
   return ({ children }: { children: React.ReactNode }) => {
diff --git a/node_package/src/RSCRoute.ts b/node_package/src/RSCRoute.ts
index 34e214b628..188217b4d2 100644
--- a/node_package/src/RSCRoute.ts
+++ b/node_package/src/RSCRoute.ts
@@ -1,8 +1,12 @@
 import * as React from 'react';
-import { RSCClientRootProps } from './RSCClientRoot';
 import { useRSC } from './RSCProvider';
 
-const RSCRoute = ({ componentName, componentProps }: RSCClientRootProps) => {
+export type RSCRouteProps = {
+  componentName: string;
+  componentProps: unknown;
+};
+
+const RSCRoute = ({ componentName, componentProps }: RSCRouteProps) => {
   const { getComponent, getCachedComponent } = useRSC();
   let component = getCachedComponent(componentName, componentProps);
   if (!component) {
diff --git a/node_package/src/RSCServerRoot.tsx b/node_package/src/RSCServerRoot.tsx
index 450d00840e..9ce591a74f 100644
--- a/node_package/src/RSCServerRoot.tsx
+++ b/node_package/src/RSCServerRoot.tsx
@@ -2,15 +2,11 @@ import * as React from 'react';
 import type { RenderFunction, RailsContext } from './types/index.ts';
 import getReactServerComponent from './getReactServerComponent.server.ts';
 import { createRSCProvider } from './RSCProvider.tsx';
-import RSCRoute from './RSCRoute.ts';
 
-type RSCServerRootProps = {
-  componentName: string;
-  componentProps: unknown;
-};
+type RSCServerRootProps = { ServerComponentContainer: ReactComponent };
 
 const RSCServerRoot: RenderFunction = async (
-  { componentName, componentProps }: RSCServerRootProps,
+  { ServerComponentContainer }: RSCServerRootProps,
   railsContext?: RailsContext,
 ) => {
   if (!railsContext) {
@@ -22,10 +18,13 @@ const RSCServerRoot: RenderFunction = async (
     getServerComponent: getReactServerComponent,
   });
 
-  // eslint-disable-next-line react/no-children-prop
-  const root = React.createElement(RSCProvider, {
-    children: React.createElement(RSCRoute, { componentName, componentProps }),
-  });
+  const suspensableServerComponent = (
+    <React.Suspense fallback={null}>
+      <ServerComponentContainer />
+    </React.Suspense>
+  );
+
+  const root = <RSCProvider>{suspensableServerComponent}</RSCProvider>;
 
   return () => root;
 };
diff --git a/node_package/src/ReactOnRails.node.ts b/node_package/src/ReactOnRails.node.ts
index 39507cef9f..7c6bcbe412 100644
--- a/node_package/src/ReactOnRails.node.ts
+++ b/node_package/src/ReactOnRails.node.ts
@@ -1,11 +1,17 @@
 import ReactOnRails from './ReactOnRails.full.ts';
 import streamServerRenderedReactComponent from './streamServerRenderedReactComponent.ts';
-import { getRSCPayloadStream, getRSCPayloadStreams, clearRSCPayloadStreams } from './RSCPayloadGenerator.ts';
+import {
+  getRSCPayloadStream,
+  getRSCPayloadStreams,
+  clearRSCPayloadStreams,
+  onRSCPayloadGenerated,
+} from './RSCPayloadGenerator.ts';
 
 ReactOnRails.streamServerRenderedReactComponent = streamServerRenderedReactComponent;
 ReactOnRails.getRSCPayloadStream = getRSCPayloadStream;
 ReactOnRails.getRSCPayloadStreams = getRSCPayloadStreams;
 ReactOnRails.clearRSCPayloadStreams = clearRSCPayloadStreams;
+ReactOnRails.onRSCPayloadGenerated = onRSCPayloadGenerated;
 
 export * from './ReactOnRails.full.ts';
 // eslint-disable-next-line no-restricted-exports -- see https://github.com/eslint/eslint/issues/15617
diff --git a/node_package/src/baseRegisterServerComponent/client.tsx b/node_package/src/baseRegisterServerComponent/client.tsx
new file mode 100644
index 0000000000..9ecd67f265
--- /dev/null
+++ b/node_package/src/baseRegisterServerComponent/client.tsx
@@ -0,0 +1,59 @@
+import * as React from 'react';
+import ReactOnRails from '../ReactOnRails.client';
+import RSCClientRoot from '../RSCClientRoot';
+import { RailsContext, ReactComponentOrRenderFunction, ReactComponent } from '../types';
+
+/**
+ * Registers React Server Components (RSC) with React on Rails.
+ * This function wraps server components with RSCClientRoot to handle client-side rendering
+ * and hydration of RSC payloads.
+ *
+ * Important: Components registered with this function are not included in the client bundle.
+ * Instead, when the component needs to be rendered:
+ * 1. A request is made to `${rscPayloadGenerationUrlPath}/${componentName}`
+ * 2. The server returns an RSC payload containing:
+ *    - Server component rendered output
+ *    - References to client components that need hydration
+ *    - Data props passed to client components
+ * 3. The RSC payload is processed and rendered as HTML on the client
+ *
+ * This approach enables:
+ * - Smaller client bundles (server components code stays on server)
+ * - Progressive loading of components
+ * - Automatic handling of data requirements
+ *
+ * @param options - Configuration options for RSC rendering
+ * @param options.rscPayloadGenerationUrlPath - The base URL path where RSC payloads will be fetched from
+ * @param componentNames - Names of server components to register
+ *
+ * @example
+ * ```js
+ * registerServerComponent({
+ *   rscPayloadGenerationUrlPath: '/rsc_payload'
+ * }, 'ServerComponent1', 'ServerComponent2');
+ *
+ * // When ServerComponent1 renders, it will fetch from: /rsc_payload/ServerComponent1
+ * ```
+ */
+const registerServerComponent = (WrapperComponent: ReactComponent, ...componentNames: string[]) => {
+  const componentsWrappedInRSCClientRoot: Record<string, ReactComponentOrRenderFunction> = {};
+  for (const name of componentNames) {
+    componentsWrappedInRSCClientRoot[name] = (
+      componentProps?: unknown,
+      railsContext?: RailsContext,
+      domNodeId?: string,
+    ) =>
+      RSCClientRoot(
+        {
+          ServerComponentContainer: () => (
+            <WrapperComponent componentName={name} componentProps={componentProps} />
+          ),
+        },
+        railsContext,
+        domNodeId,
+      );
+  }
+  ReactOnRails.register(componentsWrappedInRSCClientRoot);
+};
+
+export default registerServerComponent;
diff --git a/node_package/src/baseRegisterServerComponent/server.tsx b/node_package/src/baseRegisterServerComponent/server.tsx
new file mode 100644
index 0000000000..d35337a158
--- /dev/null
+++ b/node_package/src/baseRegisterServerComponent/server.tsx
@@ -0,0 +1,53 @@
+import * as React from 'react';
+import ReactOnRails from '../ReactOnRails.client';
+import RSCServerRoot from '../RSCServerRoot';
+import { ReactComponent, RenderFunction, RailsContext } from '../types';
+
+/**
+ * Registers React Server Components (RSC) with React on Rails for the server bundle.
+ *
+ * This function wraps each component with RSCServerRoot, which handles the server-side
+ * rendering of React Server Components using pre-generated RSC payloads.
+ *
+ * The RSCServerRoot component:
+ * - Uses pre-generated RSC payloads from the RSC bundle
+ * - Builds the rendering tree of the server component
+ * - Handles the integration with React's streaming SSR
+ *
+ * @param components - Object mapping component names to their implementations
+ *
+ * @example
+ * ```js
+ * registerServerComponent({
+ *   ServerComponent1: ServerComponent1Component,
+ *   ServerComponent2: ServerComponent2Component
+ * });
+ * ```
+ */
+const registerServerComponent = (
+  WrapperComponent: ReactComponent,
+  components: Record<string, ReactComponent>,
+) => {
+  const componentsWrappedInRSCServerRoot: Record<string, RenderFunction> = {};
+  for (const [componentName] of Object.entries(components)) {
+    componentsWrappedInRSCServerRoot[componentName] = (
+      componentProps?: unknown,
+      railsContext?: RailsContext,
+    ) =>
+      RSCServerRoot(
+        {
+          ServerComponentContainer: () => (
+            <WrapperComponent
+              railsContext={railsContext}
+              componentName={componentName}
+              componentProps={componentProps}
+            />
+          ),
+        },
+        railsContext,
+      );
+  }
+  ReactOnRails.register(componentsWrappedInRSCServerRoot);
+};
+
+export default registerServerComponent;
diff --git a/node_package/src/getReactServerComponent.server.ts b/node_package/src/getReactServerComponent.server.ts
index 909ec08467..cfc0c1a27c 100644
--- a/node_package/src/getReactServerComponent.server.ts
+++ b/node_package/src/getReactServerComponent.server.ts
@@ -43,7 +43,9 @@ const createSSRManifest = async (
     // It can accept options such as `prefix` and `crossOrigin` to specify the path and crossorigin attribute for the modules.
     // In our case, since the server code is bundled into a single bundle, there is no need to load additional JavaScript modules.
     // As a result, we set this property to an empty object because it will not be used.
-    moduleLoading: {},
+    moduleLoading: {
+      prefix: '/webpack/development/',
+    },
     moduleMap,
   };
 
diff --git a/node_package/src/injectRSCPayload.ts b/node_package/src/injectRSCPayload.ts
index d40a62c0dc..72d365c7b6 100644
--- a/node_package/src/injectRSCPayload.ts
+++ b/node_package/src/injectRSCPayload.ts
@@ -15,8 +15,9 @@ function escapeScript(script: string) {
 }
 
 function writeChunk(chunk: string, transform: Transform, cacheKey: string) {
+  const stringifiedKey = JSON.stringify(cacheKey);
   transform.push(
-    `<script>${escapeScript(`((self.REACT_ON_RAILS_RSC_PAYLOADS||={})[${cacheKey}]||=[]).push(${chunk})`)}</script>`,
+    `<script>${escapeScript(`((self.REACT_ON_RAILS_RSC_PAYLOADS||={})[${stringifiedKey}]||=[]).push(${chunk})`)}</script>`,
   );
 }
 
@@ -35,18 +36,32 @@ export default function injectRSCPayload(
   // Start reading RSC stream immediately
   const startRSC = async () => {
     try {
-      const { stream, props, componentName } = ReactOnRails.getRSCPayloadStreams?.(railsContext)?.[0] ?? {};
-      const cacheKey = `${componentName}-${JSON.stringify(props)}-${railsContext.componentSpecificMetadata?.renderRequestId}`;
-      for await (const chunk of stream ?? []) {
-        try {
-          const decodedChunk = typeof chunk === 'string' ? chunk : decoder.decode(chunk);
-          writeChunk(JSON.stringify(decodedChunk), resultStream, cacheKey);
-        } catch (_) {
-          const decodedChunk = typeof chunk === 'string' ? chunk : String.fromCodePoint(...chunk);
-          const base64 = JSON.stringify(btoa(decodedChunk));
-          writeChunk(`Uint8Array.from(atob(${base64}), m => m.codePointAt(0))`, resultStream, cacheKey);
+      const rscPromises: Promise<void>[] = [];
+
+      ReactOnRails.onRSCPayloadGenerated?.(railsContext, (streamInfo) => {
+        const { stream, props, componentName } = streamInfo;
+        const cacheKey = `${componentName}-${JSON.stringify(props)}-${railsContext.componentSpecificMetadata?.renderRequestId}`;
+        rscPromises.push(
+          // eslint-disable-next-line @typescript-eslint/no-misused-promises, no-async-promise-executor
+          new Promise(async (resolve) => {
+            for await (const chunk of stream ?? []) {
+              const decodedChunk = typeof chunk === 'string' ? chunk : decoder.decode(chunk);
+              writeChunk(JSON.stringify(decodedChunk), resultStream, cacheKey);
+            }
+            resolve();
+          }),
+        );
+      });
+
+      await new Promise((resolve) => {
+        if (htmlStream.readableEnded) {
+          resolve(Promise.all(rscPromises));
+        } else {
+          htmlStream.on('end', () => {
+            resolve(Promise.all(rscPromises));
+          });
         }
-      }
+      });
     } catch (err) {
       resultStream.emit('error', err);
     }
@@ -83,7 +98,12 @@ export default function injectRSCPayload(
     if (!rscPromise) {
       rscPromise = startRSC();
     }
-    rscPromise.then(() => resultStream.end()).catch((err: unknown) => resultStream.emit('error', err));
+    rscPromise
+      .then(() => {
+        resultStream.end();
+        ReactOnRails.clearRSCPayloadStreams?.(railsContext);
+      })
+      .catch((err: unknown) => resultStream.emit('error', err));
   });
 
   return resultStream;
diff --git a/node_package/src/registerRouter/client.tsx b/node_package/src/registerRouter/client.tsx
new file mode 100644
index 0000000000..b707ecff6e
--- /dev/null
+++ b/node_package/src/registerRouter/client.tsx
@@ -0,0 +1,19 @@
+import * as React from 'react';
+import baseRegisterServerComponent from '../baseRegisterServerComponent/client';
+import { ReactComponent } from '../types';
+
+const registerRouter = (routers: Record<string, ReactComponent>) => {
+  const WrapperComponent = ({
+    componentName,
+    componentProps,
+  }: {
+    componentName: keyof typeof routers;
+    componentProps: unknown;
+  }) => {
+    const RouterComponent = routers[componentName];
+    return <RouterComponent {...(typeof componentProps === 'object' ? componentProps : {})} />;
+  };
+  baseRegisterServerComponent(WrapperComponent, ...Object.keys(routers));
+};
+
+export default registerRouter;
diff --git a/node_package/src/registerRouter/server.rsc.ts b/node_package/src/registerRouter/server.rsc.ts
new file mode 100644
index 0000000000..2be90690d3
--- /dev/null
+++ b/node_package/src/registerRouter/server.rsc.ts
@@ -0,0 +1,5 @@
+const registerRouter = () => {
+  // Do nothing
+};
+
+export default registerRouter;
diff --git a/node_package/src/registerRouter/server.tsx b/node_package/src/registerRouter/server.tsx
new file mode 100644
index 0000000000..9bdaf02ceb
--- /dev/null
+++ b/node_package/src/registerRouter/server.tsx
@@ -0,0 +1,26 @@
+import * as React from 'react';
+import baseRegisterServerComponent from '../baseRegisterServerComponent/server';
+import { RailsContext, ReactComponent } from '../types';
+
+const registerRouter = (routers: Record<string, ReactComponent>) => {
+  const WrapperComponent = ({
+    componentName,
+    componentProps,
+    railsContext,
+  }: {
+    componentName: keyof typeof routers;
+    componentProps: unknown;
+    railsContext: RailsContext;
+  }) => {
+    const RouterComponent = routers[componentName];
+    return (
+      <RouterComponent
+        railsContext={railsContext}
+        {...(typeof componentProps === 'object' ? componentProps : {})}
+      />
+    );
+  };
+  baseRegisterServerComponent(WrapperComponent, routers);
+};
+
+export default registerRouter;
diff --git a/node_package/src/registerServerComponent/client.ts b/node_package/src/registerServerComponent/client.ts
index 6a1b62a61c..ffb375ceca 100644
--- a/node_package/src/registerServerComponent/client.ts
+++ b/node_package/src/registerServerComponent/client.ts
@@ -1,10 +1,6 @@
-import ReactOnRails from '../ReactOnRails.client.ts';
-import RSCClientRoot from '../RSCClientRoot.ts';
-import {
-  RegisterServerComponentOptions,
-  RailsContext,
-  ReactComponentOrRenderFunction,
-} from '../types/index.ts';
+import RSCRoute from '../RSCRoute.ts';
+import { RegisterServerComponentOptions } from '../types/index.ts';
+import baseRegisterServerComponent from '../baseRegisterServerComponent/client.tsx';
 
 /**
  * Registers React Server Components (RSC) with React on Rails.
@@ -39,24 +35,7 @@ import {
  * ```
  */
 const registerServerComponent = (options: RegisterServerComponentOptions, ...componentNames: string[]) => {
-  const componentsWrappedInRSCClientRoot: Record<string, ReactComponentOrRenderFunction> = {};
-  for (const name of componentNames) {
-    componentsWrappedInRSCClientRoot[name] = (
-      componentProps?: unknown,
-      _railsContext?: RailsContext,
-      domNodeId?: string,
-    ) =>
-      RSCClientRoot(
-        {
-          componentName: name,
-          rscPayloadGenerationUrlPath: options.rscPayloadGenerationUrlPath,
-          componentProps,
-        },
-        _railsContext,
-        domNodeId,
-      );
-  }
-  ReactOnRails.register(componentsWrappedInRSCClientRoot);
+  baseRegisterServerComponent(RSCRoute, ...componentNames);
 };
 
 export default registerServerComponent;
diff --git a/node_package/src/registerServerComponent/server.ts b/node_package/src/registerServerComponent/server.ts
index d316f89f37..41e139d844 100644
--- a/node_package/src/registerServerComponent/server.ts
+++ b/node_package/src/registerServerComponent/server.ts
@@ -1,6 +1,6 @@
-import ReactOnRails from '../ReactOnRails.client.ts';
-import RSCServerRoot from '../RSCServerRoot.tsx';
-import { ReactComponent, RenderFunction, RailsContext } from '../types/index.ts';
+import RSCRoute from '../RSCRoute.ts';
+import baseRegisterServerComponent from '../baseRegisterServerComponent/server.tsx';
+import { ReactComponent } from '../types/index.ts';
 
 /**
  * Registers React Server Components (RSC) with React on Rails for the server bundle.
@@ -24,14 +24,7 @@ import { ReactComponent, RenderFunction, RailsContext } from '../types/index.ts'
  * ```
  */
 const registerServerComponent = (components: Record<string, ReactComponent>) => {
-  const componentsWrappedInRSCServerRoot: Record<string, RenderFunction> = {};
-  for (const [componentName] of Object.entries(components)) {
-    componentsWrappedInRSCServerRoot[componentName] = (
-      componentProps?: unknown,
-      railsContext?: RailsContext,
-    ) => RSCServerRoot({ componentName, componentProps }, railsContext);
-  }
-  ReactOnRails.register(componentsWrappedInRSCServerRoot);
+  baseRegisterServerComponent(RSCRoute, components);
 };
 
 export default registerServerComponent;
diff --git a/node_package/src/types/index.ts b/node_package/src/types/index.ts
index 18d50b205e..b47f817e42 100644
--- a/node_package/src/types/index.ts
+++ b/node_package/src/types/index.ts
@@ -2,6 +2,7 @@
 
 import type { ReactElement, ReactNode, Component, ComponentType } from 'react';
 import type { Readable } from 'stream';
+import { RSCPayloadCallback } from '../RSCPayloadGenerator';
 
 /* eslint-disable @typescript-eslint/no-explicit-any */
 /**
@@ -432,6 +433,13 @@ export interface ReactOnRailsInternal extends ReactOnRails {
     stream: NodeJS.ReadableStream;
   }[];
 
+  /**
+   * Registers a callback to be called when an RSC payload stream is generated for a specific rendering request.
+   * @param railsContext - The Rails context of the current rendering request.
+   * @param callback - The callback to be called when an RSC payload stream is generated.
+   */
+  onRSCPayloadGenerated?: (railsContext: RailsContext, callback: RSCPayloadCallback) => void;
+
   /**
    * Clears all RSC payload streams generated for the rendering request of the given Rails context.
    * @param railsContext - The Rails context of the current rendering request.
diff --git a/package.json b/package.json
index f72040c0e9..9aa3e1fc02 100644
--- a/package.json
+++ b/package.json
@@ -16,7 +16,13 @@
       "react-server": "./node_package/lib/registerServerComponent/server.rsc.js",
       "default": "./node_package/lib/registerServerComponent/server.js"
     },
-    "./RSCServerRoot": "./node_package/lib/RSCServerRoot.js"
+    "./RSCServerRoot": "./node_package/lib/RSCServerRoot.js",
+    "./registerRouter/client": "./node_package/lib/registerRouter/client.js",
+    "./registerRouter/server": {
+      "react-server": "./node_package/lib/registerRouter/server.rsc.js",
+      "default": "./node_package/lib/registerRouter/server.js"
+    },
+    "./RSCRoute": "./node_package/lib/RSCRoute.js"
   },
   "directories": {
     "doc": "docs"
@@ -48,7 +54,6 @@
     "eslint-plugin-prettier": "^5.2.3",
     "eslint-plugin-react": "^7.37.4",
     "eslint-plugin-react-hooks": "^5.2.0",
-    "typescript-eslint": "^8.29.1",
     "globals": "^16.0.0",
     "jest": "^29.7.0",
     "jest-environment-jsdom": "^29.7.0",
@@ -64,7 +69,8 @@
     "react-on-rails-rsc": "git+https://github.com/shakacode/react_on_rails_rsc.git#add-support-for-generating-client-components-manifest-for-server-bundle",
     "redux": "^4.2.1",
     "ts-jest": "^29.2.5",
-    "typescript": "^5.8.3"
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.29.1"
   },
   "peerDependencies": {
     "react": ">= 16",

From 5b3d943f12c834e202b7470a23e159671e2548e1 Mon Sep 17 00:00:00 2001
From: Abanoub Ghadban <abanoub@shakacode.com>
Date: Fri, 25 Apr 2025 15:31:38 +0300
Subject: [PATCH 05/50] replace registerRouter with wrapServerComponentRenderer
 utility function

---
 lib/react_on_rails/packs_generator.rb         | 43 ++-----------
 node_package/src/RSCClientRoot.tsx            |  9 ++-
 node_package/src/RSCProvider.tsx              |  8 +--
 node_package/src/RSCServerRoot.tsx            |  4 +-
 .../baseRegisterServerComponent/client.tsx    | 59 -----------------
 .../baseRegisterServerComponent/server.tsx    | 53 ----------------
 .../src/getReactServerComponent.client.ts     | 12 ----
 node_package/src/registerRouter/client.tsx    | 19 ------
 node_package/src/registerRouter/server.rsc.ts |  5 --
 node_package/src/registerRouter/server.tsx    | 26 --------
 .../{client.ts => client.tsx}                 | 14 ++++-
 .../{server.ts => server.tsx}                 | 14 ++++-
 .../wrapServerComponentRenderer/client.tsx    | 63 +++++++++++++++++++
 .../server.rsc.tsx                            |  6 ++
 .../wrapServerComponentRenderer/server.tsx    | 44 +++++++++++++
 package.json                                  |  8 +--
 16 files changed, 152 insertions(+), 235 deletions(-)
 delete mode 100644 node_package/src/baseRegisterServerComponent/client.tsx
 delete mode 100644 node_package/src/baseRegisterServerComponent/server.tsx
 delete mode 100644 node_package/src/registerRouter/client.tsx
 delete mode 100644 node_package/src/registerRouter/server.rsc.ts
 delete mode 100644 node_package/src/registerRouter/server.tsx
 rename node_package/src/registerServerComponent/{client.ts => client.tsx} (71%)
 rename node_package/src/registerServerComponent/{server.ts => server.tsx} (58%)
 create mode 100644 node_package/src/wrapServerComponentRenderer/client.tsx
 create mode 100644 node_package/src/wrapServerComponentRenderer/server.rsc.tsx
 create mode 100644 node_package/src/wrapServerComponentRenderer/server.tsx

diff --git a/lib/react_on_rails/packs_generator.rb b/lib/react_on_rails/packs_generator.rb
index c6f18d6526..ae4169162f 100644
--- a/lib/react_on_rails/packs_generator.rb
+++ b/lib/react_on_rails/packs_generator.rb
@@ -87,30 +87,11 @@ def client_entrypoint?(file_path)
       first_js_statement_in_code(content).match?(/^["']use client["'](?:;|\s|$)/)
     end
 
-    def router_entrypoint?(file_path)
-      content = File.read(file_path)
-      # has "use router" directive. It can be "use router" or 'use router'
-      first_js_statement_in_code(content).match?(/^["']use router["'](?:;|\s|$)/)
-    end
-
     def pack_file_contents(file_path)
       registered_component_name = component_name(file_path)
       load_server_components = ReactOnRails::Utils.react_on_rails_pro? &&
                                ReactOnRailsPro.configuration.enable_rsc_support
 
-      # Check for router component first
-      if load_server_components && router_entrypoint?(file_path)
-        relative_component_path = relative_component_path_from_generated_pack(file_path)
-        return <<~FILE_CONTENT.strip
-          import registerRouter from 'react-on-rails/registerRouter/client';
-          import #{registered_component_name} from '#{relative_component_path}';
-
-          registerRouter({
-            #{registered_component_name},
-          });
-        FILE_CONTENT
-      end
-
       if load_server_components && !client_entrypoint?(file_path)
         rsc_payload_generation_url_path = ReactOnRailsPro.configuration.rsc_payload_generation_url_path
 
@@ -140,12 +121,11 @@ def create_server_pack
       puts(Rainbow("Generated Server Bundle: #{generated_server_bundle_file_path}").orange)
     end
 
-    def build_server_pack_content(component_on_server_imports, server_components, client_components, router_components)
+    def build_server_pack_content(component_on_server_imports, server_components, client_components)
       content = <<~FILE_CONTENT
         import ReactOnRails from 'react-on-rails';
 
         #{component_on_server_imports.join("\n")}\n
-        #{router_components.any? ? "import registerRouter from 'react-on-rails/registerRouter/server';" : ''}
       FILE_CONTENT
 
       if server_components.any?
@@ -155,16 +135,10 @@ def build_server_pack_content(component_on_server_imports, server_components, cl
         FILE_CONTENT
       end
 
-      if router_components.any?
-        content += <<~FILE_CONTENT
-          registerRouter({#{router_components.join(",\n")}});\n
-        FILE_CONTENT
-      end
-
       content + "ReactOnRails.register({#{client_components.join(",\n")}});"
     end
 
-    def generated_server_pack_file_content # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity
+    def generated_server_pack_file_content
       common_components_for_server_bundle = common_component_to_path.delete_if { |k| server_component_to_path.key?(k) }
       component_for_server_registration_to_path = common_components_for_server_bundle.merge(server_component_to_path)
 
@@ -174,24 +148,15 @@ def generated_server_pack_file_content # rubocop:disable Metrics/AbcSize,Metrics
 
       load_server_components = ReactOnRails::Utils.react_on_rails_pro? &&
                                ReactOnRailsPro.configuration.enable_rsc_support
-
-      # Identify router components
-      router_components = component_for_server_registration_to_path.keys.select do |name|
-        component_path = component_for_server_registration_to_path[name]
-        router_entrypoint?(component_path)
-      end
-
       server_components = component_for_server_registration_to_path.keys.delete_if do |name|
         next true unless load_server_components
-        next true if router_components.include?(name)
 
         component_path = component_for_server_registration_to_path[name]
         client_entrypoint?(component_path)
       end
+      client_components = component_for_server_registration_to_path.keys - server_components
 
-      client_components = component_for_server_registration_to_path.keys - server_components - router_components
-
-      build_server_pack_content(component_on_server_imports, server_components, client_components, router_components)
+      build_server_pack_content(component_on_server_imports, server_components, client_components)
     end
 
     def add_generated_pack_to_server_bundle
diff --git a/node_package/src/RSCClientRoot.tsx b/node_package/src/RSCClientRoot.tsx
index b80aa6b0f5..3975f0f9ed 100644
--- a/node_package/src/RSCClientRoot.tsx
+++ b/node_package/src/RSCClientRoot.tsx
@@ -2,10 +2,10 @@
 
 import * as React from 'react';
 import * as ReactDOMClient from 'react-dom/client';
-import { RailsContext, RenderFunction } from './types/index.ts';
+import { RailsContext, RenderFunction, ReactComponent } from './types/index.ts';
 import { ensureReactUseAvailable } from './reactApis.cts';
 import { createRSCProvider } from './RSCProvider.tsx';
-import { getReactServerComponent, getPreloadedReactServerComponents } from './getReactServerComponent.client.ts';
+import { getReactServerComponent } from './getReactServerComponent.client.ts';
 
 ensureReactUseAvailable();
 
@@ -24,7 +24,7 @@ export type RSCClientRootProps = { ServerComponentContainer: ReactComponent };
  * @requires React 19+
  * @requires react-on-rails-rsc
  */
-const RSCClientRoot: RenderFunction = async (
+const RSCClientRoot: RenderFunction = (
   { ServerComponentContainer }: RSCClientRootProps,
   railsContext?: RailsContext,
   domNodeId?: string,
@@ -33,10 +33,9 @@ const RSCClientRoot: RenderFunction = async (
     throw new Error('RSCClientRoot: No railsContext provided');
   }
 
-  const RSCProvider = await createRSCProvider({
+  const RSCProvider = createRSCProvider({
     railsContext,
     getServerComponent: getReactServerComponent,
-    getPreloadedComponents: getPreloadedReactServerComponents,
   });
 
   const SuspensableRSCRoute = (
diff --git a/node_package/src/RSCProvider.tsx b/node_package/src/RSCProvider.tsx
index 873b62dcb3..2b860b1c46 100644
--- a/node_package/src/RSCProvider.tsx
+++ b/node_package/src/RSCProvider.tsx
@@ -1,6 +1,6 @@
 import * as React from 'react';
 import { RailsContext } from './types';
-import { getReactServerComponent, getPreloadedReactServerComponents } from './getReactServerComponent.client';
+import { getReactServerComponent } from './getReactServerComponent.client';
 
 type RSCContextType = {
   getCachedComponent: (componentName: string, componentProps: unknown) => React.ReactNode;
@@ -10,16 +10,14 @@ type RSCContextType = {
 
 const RSCContext = React.createContext<RSCContextType | undefined>(undefined);
 
-export const createRSCProvider = async ({
+export const createRSCProvider = ({
   railsContext,
   getServerComponent,
-  getPreloadedComponents,
 }: {
   railsContext: RailsContext;
   getServerComponent: typeof getReactServerComponent;
-  getPreloadedComponents?: typeof getPreloadedReactServerComponents;
 }) => {
-  const cachedComponents = (await getPreloadedComponents?.(railsContext)) ?? {};
+  const cachedComponents: Record<string, React.ReactNode> = {};
   const fetchRSCPromises: Record<string, Promise<React.ReactNode>> = {};
 
   const generateCacheKey = (componentName: string, componentProps: unknown) => {
diff --git a/node_package/src/RSCServerRoot.tsx b/node_package/src/RSCServerRoot.tsx
index 9ce591a74f..ca6921dfe0 100644
--- a/node_package/src/RSCServerRoot.tsx
+++ b/node_package/src/RSCServerRoot.tsx
@@ -5,7 +5,7 @@ import { createRSCProvider } from './RSCProvider.tsx';
 
 type RSCServerRootProps = { ServerComponentContainer: ReactComponent };
 
-const RSCServerRoot: RenderFunction = async (
+const RSCServerRoot: RenderFunction = (
   { ServerComponentContainer }: RSCServerRootProps,
   railsContext?: RailsContext,
 ) => {
@@ -13,7 +13,7 @@ const RSCServerRoot: RenderFunction = async (
     throw new Error('RSCClientRoot: No railsContext provided');
   }
 
-  const RSCProvider = await createRSCProvider({
+  const RSCProvider = createRSCProvider({
     railsContext,
     getServerComponent: getReactServerComponent,
   });
diff --git a/node_package/src/baseRegisterServerComponent/client.tsx b/node_package/src/baseRegisterServerComponent/client.tsx
deleted file mode 100644
index 9ecd67f265..0000000000
--- a/node_package/src/baseRegisterServerComponent/client.tsx
+++ /dev/null
@@ -1,59 +0,0 @@
-import * as React from 'react';
-import ReactOnRails from '../ReactOnRails.client';
-import RSCClientRoot from '../RSCClientRoot';
-import { RailsContext, ReactComponentOrRenderFunction, ReactComponent } from '../types';
-
-/**
- * Registers React Server Components (RSC) with React on Rails.
- * This function wraps server components with RSCClientRoot to handle client-side rendering
- * and hydration of RSC payloads.
- *
- * Important: Components registered with this function are not included in the client bundle.
- * Instead, when the component needs to be rendered:
- * 1. A request is made to `${rscPayloadGenerationUrlPath}/${componentName}`
- * 2. The server returns an RSC payload containing:
- *    - Server component rendered output
- *    - References to client components that need hydration
- *    - Data props passed to client components
- * 3. The RSC payload is processed and rendered as HTML on the client
- *
- * This approach enables:
- * - Smaller client bundles (server components code stays on server)
- * - Progressive loading of components
- * - Automatic handling of data requirements
- *
- * @param options - Configuration options for RSC rendering
- * @param options.rscPayloadGenerationUrlPath - The base URL path where RSC payloads will be fetched from
- * @param componentNames - Names of server components to register
- *
- * @example
- * ```js
- * registerServerComponent({
- *   rscPayloadGenerationUrlPath: '/rsc_payload'
- * }, 'ServerComponent1', 'ServerComponent2');
- *
- * // When ServerComponent1 renders, it will fetch from: /rsc_payload/ServerComponent1
- * ```
- */
-const registerServerComponent = (WrapperComponent: ReactComponent, ...componentNames: string[]) => {
-  const componentsWrappedInRSCClientRoot: Record<string, ReactComponentOrRenderFunction> = {};
-  for (const name of componentNames) {
-    componentsWrappedInRSCClientRoot[name] = (
-      componentProps?: unknown,
-      railsContext?: RailsContext,
-      domNodeId?: string,
-    ) =>
-      RSCClientRoot(
-        {
-          ServerComponentContainer: () => (
-            <WrapperComponent componentName={name} componentProps={componentProps} />
-          ),
-        },
-        railsContext,
-        domNodeId,
-      );
-  }
-  ReactOnRails.register(componentsWrappedInRSCClientRoot);
-};
-
-export default registerServerComponent;
diff --git a/node_package/src/baseRegisterServerComponent/server.tsx b/node_package/src/baseRegisterServerComponent/server.tsx
deleted file mode 100644
index d35337a158..0000000000
--- a/node_package/src/baseRegisterServerComponent/server.tsx
+++ /dev/null
@@ -1,53 +0,0 @@
-import * as React from 'react';
-import ReactOnRails from '../ReactOnRails.client';
-import RSCServerRoot from '../RSCServerRoot';
-import { ReactComponent, RenderFunction, RailsContext } from '../types';
-
-/**
- * Registers React Server Components (RSC) with React on Rails for the server bundle.
- *
- * This function wraps each component with RSCServerRoot, which handles the server-side
- * rendering of React Server Components using pre-generated RSC payloads.
- *
- * The RSCServerRoot component:
- * - Uses pre-generated RSC payloads from the RSC bundle
- * - Builds the rendering tree of the server component
- * - Handles the integration with React's streaming SSR
- *
- * @param components - Object mapping component names to their implementations
- *
- * @example
- * ```js
- * registerServerComponent({
- *   ServerComponent1: ServerComponent1Component,
- *   ServerComponent2: ServerComponent2Component
- * });
- * ```
- */
-const registerServerComponent = (
-  WrapperComponent: ReactComponent,
-  components: Record<string, ReactComponent>,
-) => {
-  const componentsWrappedInRSCServerRoot: Record<string, RenderFunction> = {};
-  for (const [componentName] of Object.entries(components)) {
-    componentsWrappedInRSCServerRoot[componentName] = (
-      componentProps?: unknown,
-      railsContext?: RailsContext,
-    ) =>
-      RSCServerRoot(
-        {
-          ServerComponentContainer: () => (
-            <WrapperComponent
-              railsContext={railsContext}
-              componentName={componentName}
-              componentProps={componentProps}
-            />
-          ),
-        },
-        railsContext,
-      );
-  }
-  ReactOnRails.register(componentsWrappedInRSCServerRoot);
-};
-
-export default registerServerComponent;
diff --git a/node_package/src/getReactServerComponent.client.ts b/node_package/src/getReactServerComponent.client.ts
index d5f30dc692..2621f846f8 100644
--- a/node_package/src/getReactServerComponent.client.ts
+++ b/node_package/src/getReactServerComponent.client.ts
@@ -84,15 +84,3 @@ export const getReactServerComponent = ({
   }
   return fetchRSC({ componentName, componentProps, railsContext });
 };
-
-export const getPreloadedReactServerComponents = (railsContext: RailsContext) => {
-  return Promise.all(
-    Object.entries(window.REACT_ON_RAILS_RSC_PAYLOADS ?? {})
-      .filter(([cacheKey]) =>
-        cacheKey.includes(railsContext.componentSpecificMetadata?.renderRequestId ?? ''),
-      )
-      .map(async ([cacheKey, payloads]) => ({
-        [cacheKey]: await createFromPreloadedPayloads(payloads),
-      })),
-  ).then((components) => Object.assign({}, ...components) as Record<string, React.ReactNode>);
-};
diff --git a/node_package/src/registerRouter/client.tsx b/node_package/src/registerRouter/client.tsx
deleted file mode 100644
index b707ecff6e..0000000000
--- a/node_package/src/registerRouter/client.tsx
+++ /dev/null
@@ -1,19 +0,0 @@
-import * as React from 'react';
-import baseRegisterServerComponent from '../baseRegisterServerComponent/client';
-import { ReactComponent } from '../types';
-
-const registerRouter = (routers: Record<string, ReactComponent>) => {
-  const WrapperComponent = ({
-    componentName,
-    componentProps,
-  }: {
-    componentName: keyof typeof routers;
-    componentProps: unknown;
-  }) => {
-    const RouterComponent = routers[componentName];
-    return <RouterComponent {...(typeof componentProps === 'object' ? componentProps : {})} />;
-  };
-  baseRegisterServerComponent(WrapperComponent, ...Object.keys(routers));
-};
-
-export default registerRouter;
diff --git a/node_package/src/registerRouter/server.rsc.ts b/node_package/src/registerRouter/server.rsc.ts
deleted file mode 100644
index 2be90690d3..0000000000
--- a/node_package/src/registerRouter/server.rsc.ts
+++ /dev/null
@@ -1,5 +0,0 @@
-const registerRouter = () => {
-  // Do nothing
-};
-
-export default registerRouter;
diff --git a/node_package/src/registerRouter/server.tsx b/node_package/src/registerRouter/server.tsx
deleted file mode 100644
index 9bdaf02ceb..0000000000
--- a/node_package/src/registerRouter/server.tsx
+++ /dev/null
@@ -1,26 +0,0 @@
-import * as React from 'react';
-import baseRegisterServerComponent from '../baseRegisterServerComponent/server';
-import { RailsContext, ReactComponent } from '../types';
-
-const registerRouter = (routers: Record<string, ReactComponent>) => {
-  const WrapperComponent = ({
-    componentName,
-    componentProps,
-    railsContext,
-  }: {
-    componentName: keyof typeof routers;
-    componentProps: unknown;
-    railsContext: RailsContext;
-  }) => {
-    const RouterComponent = routers[componentName];
-    return (
-      <RouterComponent
-        railsContext={railsContext}
-        {...(typeof componentProps === 'object' ? componentProps : {})}
-      />
-    );
-  };
-  baseRegisterServerComponent(WrapperComponent, routers);
-};
-
-export default registerRouter;
diff --git a/node_package/src/registerServerComponent/client.ts b/node_package/src/registerServerComponent/client.tsx
similarity index 71%
rename from node_package/src/registerServerComponent/client.ts
rename to node_package/src/registerServerComponent/client.tsx
index ffb375ceca..fe7d1a4ef5 100644
--- a/node_package/src/registerServerComponent/client.ts
+++ b/node_package/src/registerServerComponent/client.tsx
@@ -1,6 +1,8 @@
+import * as React from 'react';
+import ReactOnRails from '../ReactOnRails.client.ts';
 import RSCRoute from '../RSCRoute.ts';
-import { RegisterServerComponentOptions } from '../types/index.ts';
-import baseRegisterServerComponent from '../baseRegisterServerComponent/client.tsx';
+import { ReactComponentOrRenderFunction, RegisterServerComponentOptions } from '../types/index.ts';
+import WrapServerComponentRenderer from '../wrapServerComponentRenderer/client.tsx';
 
 /**
  * Registers React Server Components (RSC) with React on Rails.
@@ -35,7 +37,13 @@ import baseRegisterServerComponent from '../baseRegisterServerComponent/client.t
  * ```
  */
 const registerServerComponent = (options: RegisterServerComponentOptions, ...componentNames: string[]) => {
-  baseRegisterServerComponent(RSCRoute, ...componentNames);
+  const componentsWrappedInRSCRoute: Record<string, ReactComponentOrRenderFunction> = {};
+  for (const name of componentNames) {
+    componentsWrappedInRSCRoute[name] = WrapServerComponentRenderer((props: unknown) => (
+      <RSCRoute componentName={name} componentProps={props} />
+    ));
+  }
+  ReactOnRails.register(componentsWrappedInRSCRoute);
 };
 
 export default registerServerComponent;
diff --git a/node_package/src/registerServerComponent/server.ts b/node_package/src/registerServerComponent/server.tsx
similarity index 58%
rename from node_package/src/registerServerComponent/server.ts
rename to node_package/src/registerServerComponent/server.tsx
index 41e139d844..71a7466e25 100644
--- a/node_package/src/registerServerComponent/server.ts
+++ b/node_package/src/registerServerComponent/server.tsx
@@ -1,6 +1,8 @@
+import * as React from 'react';
+import ReactOnRails from '../ReactOnRails.client.ts';
 import RSCRoute from '../RSCRoute.ts';
-import baseRegisterServerComponent from '../baseRegisterServerComponent/server.tsx';
-import { ReactComponent } from '../types/index.ts';
+import { ReactComponent, RenderFunction } from '../types/index.ts';
+import WrapServerComponentRenderer from '../wrapServerComponentRenderer/server.tsx';
 
 /**
  * Registers React Server Components (RSC) with React on Rails for the server bundle.
@@ -24,7 +26,13 @@ import { ReactComponent } from '../types/index.ts';
  * ```
  */
 const registerServerComponent = (components: Record<string, ReactComponent>) => {
-  baseRegisterServerComponent(RSCRoute, components);
+  const componentsWrappedInRSCRoute: Record<string, RenderFunction> = {};
+  for (const [componentName] of Object.entries(components)) {
+    componentsWrappedInRSCRoute[componentName] = WrapServerComponentRenderer((props: unknown) => (
+      <RSCRoute componentName={componentName} componentProps={props} />
+    ));
+  }
+  ReactOnRails.register(componentsWrappedInRSCRoute);
 };
 
 export default registerServerComponent;
diff --git a/node_package/src/wrapServerComponentRenderer/client.tsx b/node_package/src/wrapServerComponentRenderer/client.tsx
new file mode 100644
index 0000000000..c7cff93489
--- /dev/null
+++ b/node_package/src/wrapServerComponentRenderer/client.tsx
@@ -0,0 +1,63 @@
+import * as React from 'react';
+import * as ReactDOMClient from 'react-dom/client';
+import { ReactComponentOrRenderFunction, RenderFunction } from '../types';
+import isRenderFunction from '../isRenderFunction';
+import { ensureReactUseAvailable } from '../reactApis';
+import { createRSCProvider } from '../RSCProvider';
+import { getReactServerComponent } from '../getReactServerComponent.client';
+
+ensureReactUseAvailable();
+
+const WrapServerComponentRenderer = (componentOrRenderFunction: ReactComponentOrRenderFunction) => {
+  if (typeof componentOrRenderFunction !== 'function') {
+    throw new Error('WrapServerComponentRenderer: component is not a function');
+  }
+
+  const wrapper: RenderFunction = async (props, railsContext, domNodeId) => {
+    const Component = isRenderFunction(componentOrRenderFunction)
+      ? await componentOrRenderFunction(props, railsContext, domNodeId)
+      : componentOrRenderFunction;
+
+    if (typeof Component !== 'function') {
+      throw new Error('WrapServerComponentRenderer: component is not a function');
+    }
+
+    if (!railsContext) {
+      throw new Error('RSCClientRoot: No railsContext provided');
+    }
+
+    const RSCProvider = createRSCProvider({
+      railsContext,
+      getServerComponent: getReactServerComponent,
+    });
+
+    const SuspensableRSCRoute = (
+      <React.Suspense fallback={null}>
+        <Component {...props} />
+      </React.Suspense>
+    );
+
+    const root = <RSCProvider>{SuspensableRSCRoute}</RSCProvider>;
+
+    if (!domNodeId) {
+      throw new Error('RSCClientRoot: No domNodeId provided');
+    }
+    const domNode = document.getElementById(domNodeId);
+    if (!domNode) {
+      throw new Error(`RSCClientRoot: No DOM node found for id: ${domNodeId}`);
+    }
+    if (domNode.innerHTML) {
+      ReactDOMClient.hydrateRoot(domNode, root);
+    } else {
+      ReactDOMClient.createRoot(domNode).render(root);
+    }
+    // Added only to satisfy the return type of RenderFunction
+    // However, the returned value of renderFunction is not used in ReactOnRails
+    // TODO: fix this behavior
+    return '';
+  };
+
+  return wrapper;
+};
+
+export default WrapServerComponentRenderer;
diff --git a/node_package/src/wrapServerComponentRenderer/server.rsc.tsx b/node_package/src/wrapServerComponentRenderer/server.rsc.tsx
new file mode 100644
index 0000000000..d5d05124ce
--- /dev/null
+++ b/node_package/src/wrapServerComponentRenderer/server.rsc.tsx
@@ -0,0 +1,6 @@
+const WrapServerComponentRenderer = () => {
+  // Do nothing
+  // Server component renderers are client components and not needed in the RSC bundle
+};
+
+export default WrapServerComponentRenderer;
diff --git a/node_package/src/wrapServerComponentRenderer/server.tsx b/node_package/src/wrapServerComponentRenderer/server.tsx
new file mode 100644
index 0000000000..03bd5c4d83
--- /dev/null
+++ b/node_package/src/wrapServerComponentRenderer/server.tsx
@@ -0,0 +1,44 @@
+import * as React from 'react';
+import type { RenderFunction, ReactComponentOrRenderFunction } from '../types';
+import getReactServerComponent from '../getReactServerComponent.server';
+import { createRSCProvider } from '../RSCProvider';
+import isRenderFunction from '../isRenderFunction';
+
+const WrapServerComponentRenderer = (componentOrRenderFunction: ReactComponentOrRenderFunction) => {
+  if (typeof componentOrRenderFunction !== 'function') {
+    throw new Error('WrapServerComponentRenderer: component is not a function');
+  }
+
+  const wrapper: RenderFunction = async (props, railsContext) => {
+    if (!railsContext) {
+      throw new Error('RSCClientRoot: No railsContext provided');
+    }
+
+    const Component = isRenderFunction(componentOrRenderFunction)
+      ? await componentOrRenderFunction(props, railsContext)
+      : componentOrRenderFunction;
+
+    if (typeof Component !== 'function') {
+      throw new Error('WrapServerComponentRenderer: component is not a function');
+    }
+
+    const RSCProvider = createRSCProvider({
+      railsContext,
+      getServerComponent: getReactServerComponent,
+    });
+
+    const suspensableServerComponent = (
+      <React.Suspense fallback={null}>
+        <Component {...props} />
+      </React.Suspense>
+    );
+
+    const root = <RSCProvider>{suspensableServerComponent}</RSCProvider>;
+
+    return () => root;
+  };
+
+  return wrapper;
+};
+
+export default WrapServerComponentRenderer;
diff --git a/package.json b/package.json
index 9aa3e1fc02..6d672ac8ec 100644
--- a/package.json
+++ b/package.json
@@ -17,10 +17,10 @@
       "default": "./node_package/lib/registerServerComponent/server.js"
     },
     "./RSCServerRoot": "./node_package/lib/RSCServerRoot.js",
-    "./registerRouter/client": "./node_package/lib/registerRouter/client.js",
-    "./registerRouter/server": {
-      "react-server": "./node_package/lib/registerRouter/server.rsc.js",
-      "default": "./node_package/lib/registerRouter/server.js"
+    "./wrapServerComponentRenderer/client": "./node_package/lib/wrapServerComponentRenderer/client.js",
+    "./wrapServerComponentRenderer/server": {
+      "react-server": "./node_package/lib/wrapServerComponentRenderer/server.rsc.js",
+      "default": "./node_package/lib/wrapServerComponentRenderer/server.js"
     },
     "./RSCRoute": "./node_package/lib/RSCRoute.js"
   },

From 58943ca38cf53238fd883df7471f29d99f7124d0 Mon Sep 17 00:00:00 2001
From: Abanoub Ghadban <abanoub@shakacode.com>
Date: Sat, 26 Apr 2025 11:48:17 +0300
Subject: [PATCH 06/50] add artifical delay amd log statements

---
 node_package/src/RSCRoute.ts                           | 10 ++++++++++
 node_package/src/getReactServerComponent.server.ts     |  3 +++
 .../src/transformRSCStreamAndReplayConsoleLogs.ts      |  6 ++++++
 3 files changed, 19 insertions(+)

diff --git a/node_package/src/RSCRoute.ts b/node_package/src/RSCRoute.ts
index 188217b4d2..d52fab64a7 100644
--- a/node_package/src/RSCRoute.ts
+++ b/node_package/src/RSCRoute.ts
@@ -7,10 +7,20 @@ export type RSCRouteProps = {
 };
 
 const RSCRoute = ({ componentName, componentProps }: RSCRouteProps) => {
+  React.useEffect(() => {
+    console.log('RSCRoute mounted for', componentName, '[DEBUG RSC]');
+
+    return () => {
+      console.log('RSCRoute unmounted for', componentName, '[DEBUG RSC]');
+    };
+  }, [componentName]);
+
   const { getComponent, getCachedComponent } = useRSC();
   let component = getCachedComponent(componentName, componentProps);
   if (!component) {
+    console.log(`RSCRoute component ${componentName} not found, fetching`, '[DEBUG RSC]');
     component = React.use(getComponent(componentName, componentProps));
+    console.log(`RSCRoute component ${componentName} fetched`, '[DEBUG RSC]');
   }
   return component;
 };
diff --git a/node_package/src/getReactServerComponent.server.ts b/node_package/src/getReactServerComponent.server.ts
index cfc0c1a27c..02c024977a 100644
--- a/node_package/src/getReactServerComponent.server.ts
+++ b/node_package/src/getReactServerComponent.server.ts
@@ -80,6 +80,9 @@ const getReactServerComponent = async ({
     railsContext.reactServerClientManifestFileName,
     railsContext.reactClientManifestFileName,
   );
+  await new Promise((resolve) => {
+    setTimeout(resolve, 2000);
+  });
   const rscPayloadStream = await ReactOnRails.getRSCPayloadStream(
     componentName,
     componentProps,
diff --git a/node_package/src/transformRSCStreamAndReplayConsoleLogs.ts b/node_package/src/transformRSCStreamAndReplayConsoleLogs.ts
index 31d35c4f93..bd9d63c49a 100644
--- a/node_package/src/transformRSCStreamAndReplayConsoleLogs.ts
+++ b/node_package/src/transformRSCStreamAndReplayConsoleLogs.ts
@@ -12,6 +12,12 @@ export default function transformRSCStreamAndReplayConsoleLogs(stream: ReadableS
 
       const handleJsonChunk = (chunk: RSCPayloadChunk) => {
         const { html, consoleReplayScript = '' } = chunk;
+        if (html.includes('client7.chunk.js')) {
+          console.log('received client7.chunk.js at chunk [DEBUG RSC]', chunk);
+        }
+        if (html.includes('client6.chunk.js')) {
+          console.log('received client6.chunk.js at chunk [DEBUG RSC]', chunk);
+        }
         controller.enqueue(encoder.encode(html ?? ''));
 
         const replayConsoleCode = consoleReplayScript

From 0ded299e8db10225828a3ba6d0ee096def20a01c Mon Sep 17 00:00:00 2001
From: Abanoub Ghadban <abanoub@shakacode.com>
Date: Sat, 26 Apr 2025 11:48:27 +0300
Subject: [PATCH 07/50] Revert "add artifical delay amd log statements"

This reverts commit cd57337469aecd297d5a75ec69d6ab542a8656fd.
---
 node_package/src/RSCRoute.ts                           | 10 ----------
 node_package/src/getReactServerComponent.server.ts     |  3 ---
 .../src/transformRSCStreamAndReplayConsoleLogs.ts      |  6 ------
 3 files changed, 19 deletions(-)

diff --git a/node_package/src/RSCRoute.ts b/node_package/src/RSCRoute.ts
index d52fab64a7..188217b4d2 100644
--- a/node_package/src/RSCRoute.ts
+++ b/node_package/src/RSCRoute.ts
@@ -7,20 +7,10 @@ export type RSCRouteProps = {
 };
 
 const RSCRoute = ({ componentName, componentProps }: RSCRouteProps) => {
-  React.useEffect(() => {
-    console.log('RSCRoute mounted for', componentName, '[DEBUG RSC]');
-
-    return () => {
-      console.log('RSCRoute unmounted for', componentName, '[DEBUG RSC]');
-    };
-  }, [componentName]);
-
   const { getComponent, getCachedComponent } = useRSC();
   let component = getCachedComponent(componentName, componentProps);
   if (!component) {
-    console.log(`RSCRoute component ${componentName} not found, fetching`, '[DEBUG RSC]');
     component = React.use(getComponent(componentName, componentProps));
-    console.log(`RSCRoute component ${componentName} fetched`, '[DEBUG RSC]');
   }
   return component;
 };
diff --git a/node_package/src/getReactServerComponent.server.ts b/node_package/src/getReactServerComponent.server.ts
index 02c024977a..cfc0c1a27c 100644
--- a/node_package/src/getReactServerComponent.server.ts
+++ b/node_package/src/getReactServerComponent.server.ts
@@ -80,9 +80,6 @@ const getReactServerComponent = async ({
     railsContext.reactServerClientManifestFileName,
     railsContext.reactClientManifestFileName,
   );
-  await new Promise((resolve) => {
-    setTimeout(resolve, 2000);
-  });
   const rscPayloadStream = await ReactOnRails.getRSCPayloadStream(
     componentName,
     componentProps,
diff --git a/node_package/src/transformRSCStreamAndReplayConsoleLogs.ts b/node_package/src/transformRSCStreamAndReplayConsoleLogs.ts
index bd9d63c49a..31d35c4f93 100644
--- a/node_package/src/transformRSCStreamAndReplayConsoleLogs.ts
+++ b/node_package/src/transformRSCStreamAndReplayConsoleLogs.ts
@@ -12,12 +12,6 @@ export default function transformRSCStreamAndReplayConsoleLogs(stream: ReadableS
 
       const handleJsonChunk = (chunk: RSCPayloadChunk) => {
         const { html, consoleReplayScript = '' } = chunk;
-        if (html.includes('client7.chunk.js')) {
-          console.log('received client7.chunk.js at chunk [DEBUG RSC]', chunk);
-        }
-        if (html.includes('client6.chunk.js')) {
-          console.log('received client6.chunk.js at chunk [DEBUG RSC]', chunk);
-        }
         controller.enqueue(encoder.encode(html ?? ''));
 
         const replayConsoleCode = consoleReplayScript

From 64d43953f47438e8f92214714ecd85114e979341 Mon Sep 17 00:00:00 2001
From: Abanoub Ghadban <abanoub@shakacode.com>
Date: Sat, 26 Apr 2025 17:50:15 +0300
Subject: [PATCH 08/50] Update import statements to include file extensions

---
 node_package/src/RSCPayloadGenerator.ts            | 10 +---------
 node_package/src/RSCProvider.tsx                   |  4 ++--
 node_package/src/RSCRoute.ts                       |  2 +-
 node_package/src/RSCServerRoot.tsx                 |  2 +-
 node_package/src/getReactServerComponent.client.ts |  6 +++---
 node_package/src/getReactServerComponent.server.ts |  6 +++---
 node_package/src/injectRSCPayload.ts               |  2 +-
 node_package/src/types/index.ts                    |  9 ++++++++-
 .../src/wrapServerComponentRenderer/client.tsx     | 10 +++++-----
 .../src/wrapServerComponentRenderer/server.tsx     |  8 ++++----
 node_package/tests/RSCClientRoot.test.jsx          |  2 +-
 node_package/tests/injectRSCPayload.test.ts        | 14 +++++++-------
 12 files changed, 37 insertions(+), 38 deletions(-)

diff --git a/node_package/src/RSCPayloadGenerator.ts b/node_package/src/RSCPayloadGenerator.ts
index 57fadf1ab4..7323bcec4f 100644
--- a/node_package/src/RSCPayloadGenerator.ts
+++ b/node_package/src/RSCPayloadGenerator.ts
@@ -1,5 +1,5 @@
 import { PassThrough } from 'stream';
-import { RailsContext } from './types';
+import { RailsContext, RSCPayloadStreamInfo, RSCPayloadCallback } from './types/index.ts';
 
 declare global {
   function generateRSCPayload(
@@ -9,14 +9,6 @@ declare global {
   ): Promise<NodeJS.ReadableStream>;
 }
 
-export type RSCPayloadStreamInfo = {
-  stream: NodeJS.ReadableStream;
-  props: unknown;
-  componentName: string;
-};
-
-export type RSCPayloadCallback = (streamInfo: RSCPayloadStreamInfo) => void;
-
 const mapRailsContextToRSCPayloadStreams = new Map<RailsContext, RSCPayloadStreamInfo[]>();
 
 const rscPayloadCallbacks = new Map<RailsContext, Array<RSCPayloadCallback>>();
diff --git a/node_package/src/RSCProvider.tsx b/node_package/src/RSCProvider.tsx
index 2b860b1c46..683dd230df 100644
--- a/node_package/src/RSCProvider.tsx
+++ b/node_package/src/RSCProvider.tsx
@@ -1,6 +1,6 @@
 import * as React from 'react';
-import { RailsContext } from './types';
-import { getReactServerComponent } from './getReactServerComponent.client';
+import { RailsContext } from './types/index.ts';
+import { getReactServerComponent } from './getReactServerComponent.client.ts';
 
 type RSCContextType = {
   getCachedComponent: (componentName: string, componentProps: unknown) => React.ReactNode;
diff --git a/node_package/src/RSCRoute.ts b/node_package/src/RSCRoute.ts
index 188217b4d2..6e9e632ffd 100644
--- a/node_package/src/RSCRoute.ts
+++ b/node_package/src/RSCRoute.ts
@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { useRSC } from './RSCProvider';
+import { useRSC } from './RSCProvider.tsx';
 
 export type RSCRouteProps = {
   componentName: string;
diff --git a/node_package/src/RSCServerRoot.tsx b/node_package/src/RSCServerRoot.tsx
index ca6921dfe0..4c8359ac1b 100644
--- a/node_package/src/RSCServerRoot.tsx
+++ b/node_package/src/RSCServerRoot.tsx
@@ -1,5 +1,5 @@
 import * as React from 'react';
-import type { RenderFunction, RailsContext } from './types/index.ts';
+import type { RenderFunction, RailsContext, ReactComponent } from './types/index.ts';
 import getReactServerComponent from './getReactServerComponent.server.ts';
 import { createRSCProvider } from './RSCProvider.tsx';
 
diff --git a/node_package/src/getReactServerComponent.client.ts b/node_package/src/getReactServerComponent.client.ts
index 2621f846f8..d6a434d340 100644
--- a/node_package/src/getReactServerComponent.client.ts
+++ b/node_package/src/getReactServerComponent.client.ts
@@ -1,8 +1,8 @@
 import * as React from 'react';
 import { createFromReadableStream } from 'react-on-rails-rsc/client';
-import { fetch } from './utils';
-import transformRSCStreamAndReplayConsoleLogs from './transformRSCStreamAndReplayConsoleLogs';
-import { RailsContext } from './types';
+import { fetch } from './utils.ts';
+import transformRSCStreamAndReplayConsoleLogs from './transformRSCStreamAndReplayConsoleLogs.ts';
+import { RailsContext } from './types/index.ts';
 
 declare global {
   interface Window {
diff --git a/node_package/src/getReactServerComponent.server.ts b/node_package/src/getReactServerComponent.server.ts
index cfc0c1a27c..52ce377cf0 100644
--- a/node_package/src/getReactServerComponent.server.ts
+++ b/node_package/src/getReactServerComponent.server.ts
@@ -1,7 +1,7 @@
 import { createFromNodeStream } from 'react-on-rails-rsc/client.node';
-import transformRSCStream from './transformRSCNodeStream';
-import loadJsonFile from './loadJsonFile';
-import { RailsContext } from './types';
+import transformRSCStream from './transformRSCNodeStream.ts';
+import loadJsonFile from './loadJsonFile.ts';
+import { RailsContext } from './types/index.ts';
 
 type RSCServerRootProps = {
   componentName: string;
diff --git a/node_package/src/injectRSCPayload.ts b/node_package/src/injectRSCPayload.ts
index 72d365c7b6..cba9d8287b 100644
--- a/node_package/src/injectRSCPayload.ts
+++ b/node_package/src/injectRSCPayload.ts
@@ -1,6 +1,6 @@
 import { PipeableStream } from 'react-dom/server';
 import { PassThrough, Transform } from 'stream';
-import { RailsContext } from './types';
+import { RailsContext } from './types/index.ts';
 
 // In JavaScript, when an escape sequence with a backslash (\) is followed by a character
 // that isn't a recognized escape character, the backslash is ignored, and the character
diff --git a/node_package/src/types/index.ts b/node_package/src/types/index.ts
index b47f817e42..4eea37d89d 100644
--- a/node_package/src/types/index.ts
+++ b/node_package/src/types/index.ts
@@ -2,7 +2,6 @@
 
 import type { ReactElement, ReactNode, Component, ComponentType } from 'react';
 import type { Readable } from 'stream';
-import { RSCPayloadCallback } from '../RSCPayloadGenerator';
 
 /* eslint-disable @typescript-eslint/no-explicit-any */
 /**
@@ -298,6 +297,14 @@ export interface ReactOnRails {
   authenticityHeaders(otherHeaders: Record<string, string>): AuthenticityHeaders;
 }
 
+export type RSCPayloadStreamInfo = {
+  stream: NodeJS.ReadableStream;
+  props: unknown;
+  componentName: string;
+};
+
+export type RSCPayloadCallback = (streamInfo: RSCPayloadStreamInfo) => void;
+
 /** Contains the parts of the `ReactOnRails` API intended for internal use only. */
 export interface ReactOnRailsInternal extends ReactOnRails {
   /**
diff --git a/node_package/src/wrapServerComponentRenderer/client.tsx b/node_package/src/wrapServerComponentRenderer/client.tsx
index c7cff93489..7ada916bd7 100644
--- a/node_package/src/wrapServerComponentRenderer/client.tsx
+++ b/node_package/src/wrapServerComponentRenderer/client.tsx
@@ -1,10 +1,10 @@
 import * as React from 'react';
 import * as ReactDOMClient from 'react-dom/client';
-import { ReactComponentOrRenderFunction, RenderFunction } from '../types';
-import isRenderFunction from '../isRenderFunction';
-import { ensureReactUseAvailable } from '../reactApis';
-import { createRSCProvider } from '../RSCProvider';
-import { getReactServerComponent } from '../getReactServerComponent.client';
+import { ReactComponentOrRenderFunction, RenderFunction } from '../types/index.ts';
+import isRenderFunction from '../isRenderFunction.ts';
+import { ensureReactUseAvailable } from '../reactApis.cts';
+import { createRSCProvider } from '../RSCProvider.tsx';
+import { getReactServerComponent } from '../getReactServerComponent.client.ts';
 
 ensureReactUseAvailable();
 
diff --git a/node_package/src/wrapServerComponentRenderer/server.tsx b/node_package/src/wrapServerComponentRenderer/server.tsx
index 03bd5c4d83..467aed8ab0 100644
--- a/node_package/src/wrapServerComponentRenderer/server.tsx
+++ b/node_package/src/wrapServerComponentRenderer/server.tsx
@@ -1,8 +1,8 @@
 import * as React from 'react';
-import type { RenderFunction, ReactComponentOrRenderFunction } from '../types';
-import getReactServerComponent from '../getReactServerComponent.server';
-import { createRSCProvider } from '../RSCProvider';
-import isRenderFunction from '../isRenderFunction';
+import type { RenderFunction, ReactComponentOrRenderFunction } from '../types/index.ts';
+import getReactServerComponent from '../getReactServerComponent.server.ts';
+import { createRSCProvider } from '../RSCProvider.tsx';
+import isRenderFunction from '../isRenderFunction.ts';
 
 const WrapServerComponentRenderer = (componentOrRenderFunction: ReactComponentOrRenderFunction) => {
   if (typeof componentOrRenderFunction !== 'function') {
diff --git a/node_package/tests/RSCClientRoot.test.jsx b/node_package/tests/RSCClientRoot.test.jsx
index b09d75f456..747d4862df 100644
--- a/node_package/tests/RSCClientRoot.test.jsx
+++ b/node_package/tests/RSCClientRoot.test.jsx
@@ -11,7 +11,7 @@ import * as path from 'path';
 import * as fs from 'fs';
 import { createNodeReadableStream, getNodeVersion } from './testUtils.js';
 
-import RSCClientRoot from '../src/RSCClientRoot.ts';
+import RSCClientRoot from '../src/RSCClientRoot.tsx';
 
 enableFetchMocks();
 
diff --git a/node_package/tests/injectRSCPayload.test.ts b/node_package/tests/injectRSCPayload.test.ts
index 4a8d04bd80..cd0687b087 100644
--- a/node_package/tests/injectRSCPayload.test.ts
+++ b/node_package/tests/injectRSCPayload.test.ts
@@ -1,6 +1,6 @@
 import { Readable, PassThrough } from 'stream';
-import ReactOnRails, { RailsContext } from '../src/ReactOnRails.node';
-import injectRSCPayload from '../src/injectRSCPayload';
+import ReactOnRails, { RailsContext } from '../src/ReactOnRails.node.ts';
+import injectRSCPayload from '../src/injectRSCPayload.ts';
 
 describe('injectRSCPayload', () => {
   const createMockStream = (chunks: (string | Buffer)[] | { [key: number]: string | string[] }) => {
@@ -40,7 +40,7 @@ describe('injectRSCPayload', () => {
 
     jest
       .spyOn(ReactOnRails, 'getRSCPayloadStreams')
-      .mockReturnValue([{ stream: mockRSC, componentName: 'test' }]);
+      .mockReturnValue([{ stream: mockRSC, componentName: 'test', props: {} }]);
 
     const result = injectRSCPayload(mockHTML, {} as RailsContext);
     const resultStr = await collectStreamData(result);
@@ -56,7 +56,7 @@ describe('injectRSCPayload', () => {
 
     jest
       .spyOn(ReactOnRails, 'getRSCPayloadStreams')
-      .mockReturnValue([{ stream: mockRSC, componentName: 'test' }]);
+      .mockReturnValue([{ stream: mockRSC, componentName: 'test', props: {} }]);
 
     const result = injectRSCPayload(mockHTML, {} as RailsContext);
     const resultStr = await collectStreamData(result);
@@ -77,7 +77,7 @@ describe('injectRSCPayload', () => {
     ]);
     jest
       .spyOn(ReactOnRails, 'getRSCPayloadStreams')
-      .mockReturnValue([{ stream: mockRSC, componentName: 'test' }]);
+      .mockReturnValue([{ stream: mockRSC, componentName: 'test', props: {} }]);
 
     const result = injectRSCPayload(mockHTML, {} as RailsContext);
     const resultStr = await collectStreamData(result);
@@ -98,7 +98,7 @@ describe('injectRSCPayload', () => {
     });
     jest
       .spyOn(ReactOnRails, 'getRSCPayloadStreams')
-      .mockReturnValue([{ stream: mockRSC, componentName: 'test' }]);
+      .mockReturnValue([{ stream: mockRSC, componentName: 'test', props: {} }]);
 
     const result = injectRSCPayload(mockHTML, {} as RailsContext);
     const resultStr = await collectStreamData(result);
@@ -122,7 +122,7 @@ describe('injectRSCPayload', () => {
     });
     jest
       .spyOn(ReactOnRails, 'getRSCPayloadStreams')
-      .mockReturnValue([{ stream: mockRSC, componentName: 'test' }]);
+      .mockReturnValue([{ stream: mockRSC, componentName: 'test', props: {} }]);
 
     const result = injectRSCPayload(mockHTML, {} as RailsContext);
     const resultStr = await collectStreamData(result);

From 172bc00811116f94b36a0eafa983c5f7d8947621 Mon Sep 17 00:00:00 2001
From: Abanoub Ghadban <abanoub@shakacode.com>
Date: Sun, 27 Apr 2025 18:11:03 +0300
Subject: [PATCH 09/50] add missing docs and specs

---
 docs/guides/configuration.md              | 25 ++++++
 lib/react_on_rails/configuration.rb       |  2 -
 lib/react_on_rails/utils.rb               |  5 ++
 spec/react_on_rails/configuration_spec.rb | 97 +++++++++++++++++++++++
 spec/react_on_rails/utils_spec.rb         | 91 +++++++++++++++++++++
 5 files changed, 218 insertions(+), 2 deletions(-)

diff --git a/docs/guides/configuration.md b/docs/guides/configuration.md
index 9ae3462081..dd033382ae 100644
--- a/docs/guides/configuration.md
+++ b/docs/guides/configuration.md
@@ -104,6 +104,31 @@ ReactOnRails.configure do |config|
   # you should include a name that matches your bundle name in your Webpack config.
   config.server_bundle_js_file = "server-bundle.js"
 
+  # When using React on Rails Pro with RSC support enabled, these configuration options work together:
+  #
+  # 1. In RORP, set `config.enable_rsc_support = true` in your react_on_rails_pro.rb initializer
+  #
+  # 2. The `rsc_bundle_js_file` (typically "rsc-bundle.js") contains only server components and
+  #    references to client components. It's generated using the RSC Webpack Loader which transforms
+  #    client components into references. This bundle is specifically used for generating RSC payloads
+  #    and is configured with the `react-server` condition.
+  config.rsc_bundle_js_file = "rsc-bundle.js"
+  #
+  # 3. The `react_client_manifest_file` contains mappings for client components that need hydration.
+  #    It's generated by the React Server Components Webpack plugin and is required for client-side
+  #    hydration of components.
+  # This manifest file is automatically generated by the React Server Components Webpack plugin. Only set this if you've configured the plugin to use a different filename.
+  config.react_client_manifest_file = "react-client-manifest.json"
+  #
+  # 4. The `react_server_client_manifest_file` is used during server-side rendering with RSC to
+  #    properly resolve references between server and client components.
+  #
+  # These files are crucial when implementing React Server Components with streaming, which offers
+  # benefits like reduced JavaScript bundle sizes, faster page loading, and selective hydration
+  # of client components.
+  # This manifest file is automatically generated by the React Server Components Webpack plugin. Only set this if you've configured the plugin to use a different filename.
+  config.react_server_client_manifest_file = "react-server-client-manifest.json"
+
   # `prerender` means server-side rendering
   # default is false. This is an option for view helpers `render_component` and `render_component_hash`.
   # Set to true to change the default value to true.
diff --git a/lib/react_on_rails/configuration.rb b/lib/react_on_rails/configuration.rb
index d033b76456..347314cc17 100644
--- a/lib/react_on_rails/configuration.rb
+++ b/lib/react_on_rails/configuration.rb
@@ -312,8 +312,6 @@ def ensure_webpack_generated_files_exists
         react_client_manifest_file,
         react_server_client_manifest_file
       ].compact_blank
-
-      self.webpack_generated_files = files
     end
 
     def configure_skip_display_none_deprecation
diff --git a/lib/react_on_rails/utils.rb b/lib/react_on_rails/utils.rb
index 5e50d44785..3645daabac 100644
--- a/lib/react_on_rails/utils.rb
+++ b/lib/react_on_rails/utils.rb
@@ -128,6 +128,11 @@ def self.react_server_client_manifest_file_path
       return @react_server_manifest_path if @react_server_manifest_path && !Rails.env.development?
 
       asset_name = ReactOnRails.configuration.react_server_client_manifest_file
+      if asset_name.nil?
+        raise ReactOnRails::Error,
+              "react_server_client_manifest_file is nil, ensure to set it in your configuration"
+      end
+
       @react_server_manifest_path = File.join(generated_assets_full_path, asset_name)
     end
 
diff --git a/spec/react_on_rails/configuration_spec.rb b/spec/react_on_rails/configuration_spec.rb
index 1c53b8041d..d4d2bec7b6 100644
--- a/spec/react_on_rails/configuration_spec.rb
+++ b/spec/react_on_rails/configuration_spec.rb
@@ -224,6 +224,103 @@ module ReactOnRails
       end
     end
 
+    describe "RSC configuration options" do
+      it "has default values for RSC-related configuration options" do
+        ReactOnRails.configure {} # rubocop:disable Lint/EmptyBlock
+
+        expect(ReactOnRails.configuration.rsc_bundle_js_file).to eq("")
+        expect(ReactOnRails.configuration.react_client_manifest_file).to eq("react-client-manifest.json")
+        expect(ReactOnRails.configuration.react_server_client_manifest_file).to eq("react-server-client-manifest.json")
+      end
+
+      it "allows setting rsc_bundle_js_file" do
+        ReactOnRails.configure do |config|
+          config.rsc_bundle_js_file = "custom-rsc-bundle.js"
+        end
+
+        expect(ReactOnRails.configuration.rsc_bundle_js_file).to eq("custom-rsc-bundle.js")
+      end
+
+      it "allows setting react_client_manifest_file" do
+        ReactOnRails.configure do |config|
+          config.react_client_manifest_file = "custom-client-manifest.json"
+        end
+
+        expect(ReactOnRails.configuration.react_client_manifest_file).to eq("custom-client-manifest.json")
+      end
+
+      it "allows setting react_server_client_manifest_file" do
+        ReactOnRails.configure do |config|
+          config.react_server_client_manifest_file = "custom-server-client-manifest.json"
+        end
+
+        expect(ReactOnRails.configuration.react_server_client_manifest_file).to eq("custom-server-client-manifest.json")
+      end
+
+      it "includes rsc files in webpack_generated_files when not blank" do
+        ReactOnRails.configure do |config|
+          config.rsc_bundle_js_file = "rsc-bundle.js"
+          config.webpack_generated_files = []
+        end
+
+        expect(ReactOnRails.configuration.webpack_generated_files).to include("rsc-bundle.js")
+      end
+
+      it "includes client manifest in webpack_generated_files" do
+        ReactOnRails.configure do |config|
+          config.react_client_manifest_file = "custom-client-manifest.json"
+          config.webpack_generated_files = []
+        end
+
+        expect(ReactOnRails.configuration.webpack_generated_files).to include("custom-client-manifest.json")
+      end
+
+      it "includes server-client manifest in webpack_generated_files" do
+        ReactOnRails.configure do |config|
+          config.react_server_client_manifest_file = "custom-server-client-manifest.json"
+          config.webpack_generated_files = []
+        end
+
+        expect(ReactOnRails.configuration.webpack_generated_files).to include("custom-server-client-manifest.json")
+      end
+
+      it "configures all RSC options together for a typical RSC setup" do
+        ReactOnRails.configure do |config|
+          config.rsc_bundle_js_file = "rsc-bundle.js"
+          config.react_client_manifest_file = "client-manifest.json"
+          config.react_server_client_manifest_file = "server-client-manifest.json"
+          config.webpack_generated_files = []
+        end
+
+        expect(ReactOnRails.configuration.rsc_bundle_js_file).to eq("rsc-bundle.js")
+        expect(ReactOnRails.configuration.react_client_manifest_file).to eq("client-manifest.json")
+        expect(ReactOnRails.configuration.react_server_client_manifest_file).to eq("server-client-manifest.json")
+
+        # All RSC files should be included in webpack_generated_files
+        expect(ReactOnRails.configuration.webpack_generated_files).to include("rsc-bundle.js")
+        expect(ReactOnRails.configuration.webpack_generated_files).to include("client-manifest.json")
+        expect(ReactOnRails.configuration.webpack_generated_files).to include("server-client-manifest.json")
+      end
+
+      it "allows nil values for RSC configuration options" do
+        ReactOnRails.configure do |config|
+          config.rsc_bundle_js_file = nil
+          config.react_client_manifest_file = nil
+          config.react_server_client_manifest_file = nil
+          config.webpack_generated_files = []
+        end
+
+        expect(ReactOnRails.configuration.rsc_bundle_js_file).to be_nil
+        expect(ReactOnRails.configuration.react_client_manifest_file).to be_nil
+        expect(ReactOnRails.configuration.react_server_client_manifest_file).to be_nil
+
+        # Nil values should not be included in webpack_generated_files
+        expect(ReactOnRails.configuration.webpack_generated_files).not_to include(nil)
+        # Only manifest.json should be in the list by default
+        expect(ReactOnRails.configuration.webpack_generated_files).to eq(["manifest.json"])
+      end
+    end
+
     it "changes the configuration of the gem, such as setting the prerender option to false" do
       ReactOnRails.configure do |config|
         config.server_bundle_js_file = "server.js"
diff --git a/spec/react_on_rails/utils_spec.rb b/spec/react_on_rails/utils_spec.rb
index 98fe24a500..226bdd2fcc 100644
--- a/spec/react_on_rails/utils_spec.rb
+++ b/spec/react_on_rails/utils_spec.rb
@@ -577,6 +577,97 @@ def mock_dev_server_running
         end
       end
     end
+
+    describe ".react_server_client_manifest_file_path" do
+      before do
+        described_class.instance_variable_set(:@react_server_manifest_path, nil)
+        allow(ReactOnRails.configuration).to receive(:react_server_client_manifest_file)
+          .and_return("react-server-client-manifest.json")
+        allow(Rails.env).to receive(:development?).and_return(false)
+      end
+
+      after do
+        described_class.instance_variable_set(:@react_server_manifest_path, nil)
+      end
+
+      context "when in development environment" do
+        before do
+          allow(Rails.env).to receive(:development?).and_return(true)
+          allow(described_class).to receive(:generated_assets_full_path)
+            .and_return("/path/to/generated/assets")
+        end
+
+        it "does not use cached path" do
+          # Call once to potentially set the cached path
+          described_class.react_server_client_manifest_file_path
+
+          # Change the configuration value
+          allow(ReactOnRails.configuration).to receive(:react_server_client_manifest_file)
+            .and_return("changed-manifest.json")
+
+          # Should use the new value
+          expect(described_class.react_server_client_manifest_file_path)
+            .to eq("/path/to/generated/assets/changed-manifest.json")
+        end
+      end
+
+      context "when not in development environment" do
+        before do
+          allow(described_class).to receive(:generated_assets_full_path)
+            .and_return("/path/to/generated/assets")
+        end
+
+        it "caches the path" do
+          # Call once to set the cached path
+          expected_path = "/path/to/generated/assets/react-server-client-manifest.json"
+          expect(described_class.react_server_client_manifest_file_path).to eq(expected_path)
+
+          # Change the configuration value
+          allow(ReactOnRails.configuration).to receive(:react_server_client_manifest_file)
+            .and_return("changed-manifest.json")
+
+          # Should still use the cached path
+          expect(described_class.react_server_client_manifest_file_path).to eq(expected_path)
+        end
+      end
+
+      context "with different manifest file names" do
+        before do
+          allow(described_class).to receive(:generated_assets_full_path)
+            .and_return("/path/to/generated/assets")
+        end
+
+        it "returns the correct path for default manifest name" do
+          allow(ReactOnRails.configuration).to receive(:react_server_client_manifest_file)
+            .and_return("react-server-client-manifest.json")
+
+          expect(described_class.react_server_client_manifest_file_path)
+            .to eq("/path/to/generated/assets/react-server-client-manifest.json")
+        end
+
+        it "returns the correct path for custom manifest name" do
+          allow(ReactOnRails.configuration).to receive(:react_server_client_manifest_file)
+            .and_return("custom-server-client-manifest.json")
+
+          expect(described_class.react_server_client_manifest_file_path)
+            .to eq("/path/to/generated/assets/custom-server-client-manifest.json")
+        end
+      end
+
+      context "with nil manifest file name" do
+        before do
+          allow(ReactOnRails.configuration).to receive(:react_server_client_manifest_file)
+            .and_return(nil)
+          allow(described_class).to receive(:generated_assets_full_path)
+            .and_return("/path/to/generated/assets")
+        end
+
+        it "raises an error when the manifest file name is nil" do
+          expect { described_class.react_server_client_manifest_file_path }
+            .to raise_error(ReactOnRails::Error, /react_server_client_manifest_file is nil/)
+        end
+      end
+    end
   end
 end
 # rubocop:enable Metrics/ModuleLength, Metrics/BlockLength

From edc7b295402a20bbb1a79b3aebe903ebddb9ad87 Mon Sep 17 00:00:00 2001
From: Abanoub Ghadban <abanoub@shakacode.com>
Date: Mon, 28 Apr 2025 11:29:21 +0300
Subject: [PATCH 10/50] remove RSCRoots and replace its test with
 registerServerComponent tests

---
 node_package/src/RSCClientRoot.tsx            |  67 -----
 node_package/src/RSCServerRoot.tsx            |  32 ---
 .../src/getReactServerComponent.client.ts     |   3 +-
 node_package/tests/RSCClientRoot.test.jsx     | 152 -----------
 .../registerServerComponent.client.test.jsx   | 253 ++++++++++++++++++
 5 files changed, 254 insertions(+), 253 deletions(-)
 delete mode 100644 node_package/src/RSCClientRoot.tsx
 delete mode 100644 node_package/src/RSCServerRoot.tsx
 delete mode 100644 node_package/tests/RSCClientRoot.test.jsx
 create mode 100644 node_package/tests/registerServerComponent.client.test.jsx

diff --git a/node_package/src/RSCClientRoot.tsx b/node_package/src/RSCClientRoot.tsx
deleted file mode 100644
index 3975f0f9ed..0000000000
--- a/node_package/src/RSCClientRoot.tsx
+++ /dev/null
@@ -1,67 +0,0 @@
-'use client';
-
-import * as React from 'react';
-import * as ReactDOMClient from 'react-dom/client';
-import { RailsContext, RenderFunction, ReactComponent } from './types/index.ts';
-import { ensureReactUseAvailable } from './reactApis.cts';
-import { createRSCProvider } from './RSCProvider.tsx';
-import { getReactServerComponent } from './getReactServerComponent.client.ts';
-
-ensureReactUseAvailable();
-
-export type RSCClientRootProps = { ServerComponentContainer: ReactComponent };
-
-/**
- * RSCClientRoot is a React component that handles client-side rendering of React Server Components (RSC).
- * It manages the fetching, caching, and rendering of RSC payloads from the server.
- *
- * This component:
- * 1. Fetches RSC payloads from the server using the provided URL path
- * 2. Caches the responses to prevent duplicate requests
- * 3. Transforms the response stream to replay server-side console logs
- * 4. Uses React.use() to handle the async data fetching
- *
- * @requires React 19+
- * @requires react-on-rails-rsc
- */
-const RSCClientRoot: RenderFunction = (
-  { ServerComponentContainer }: RSCClientRootProps,
-  railsContext?: RailsContext,
-  domNodeId?: string,
-) => {
-  if (!railsContext) {
-    throw new Error('RSCClientRoot: No railsContext provided');
-  }
-
-  const RSCProvider = createRSCProvider({
-    railsContext,
-    getServerComponent: getReactServerComponent,
-  });
-
-  const SuspensableRSCRoute = (
-    <React.Suspense fallback={null}>
-      <ServerComponentContainer />
-    </React.Suspense>
-  );
-
-  const root = <RSCProvider>{SuspensableRSCRoute}</RSCProvider>;
-
-  if (!domNodeId) {
-    throw new Error('RSCClientRoot: No domNodeId provided');
-  }
-  const domNode = document.getElementById(domNodeId);
-  if (!domNode) {
-    throw new Error(`RSCClientRoot: No DOM node found for id: ${domNodeId}`);
-  }
-  if (domNode.innerHTML) {
-    ReactDOMClient.hydrateRoot(domNode, root);
-  } else {
-    ReactDOMClient.createRoot(domNode).render(root);
-  }
-  // Added only to satisfy the return type of RenderFunction
-  // However, the returned value of renderFunction is not used in ReactOnRails
-  // TODO: fix this behavior
-  return '';
-};
-
-export default RSCClientRoot;
diff --git a/node_package/src/RSCServerRoot.tsx b/node_package/src/RSCServerRoot.tsx
deleted file mode 100644
index 4c8359ac1b..0000000000
--- a/node_package/src/RSCServerRoot.tsx
+++ /dev/null
@@ -1,32 +0,0 @@
-import * as React from 'react';
-import type { RenderFunction, RailsContext, ReactComponent } from './types/index.ts';
-import getReactServerComponent from './getReactServerComponent.server.ts';
-import { createRSCProvider } from './RSCProvider.tsx';
-
-type RSCServerRootProps = { ServerComponentContainer: ReactComponent };
-
-const RSCServerRoot: RenderFunction = (
-  { ServerComponentContainer }: RSCServerRootProps,
-  railsContext?: RailsContext,
-) => {
-  if (!railsContext) {
-    throw new Error('RSCClientRoot: No railsContext provided');
-  }
-
-  const RSCProvider = createRSCProvider({
-    railsContext,
-    getServerComponent: getReactServerComponent,
-  });
-
-  const suspensableServerComponent = (
-    <React.Suspense fallback={null}>
-      <ServerComponentContainer />
-    </React.Suspense>
-  );
-
-  const root = <RSCProvider>{suspensableServerComponent}</RSCProvider>;
-
-  return () => root;
-};
-
-export default RSCServerRoot;
diff --git a/node_package/src/getReactServerComponent.client.ts b/node_package/src/getReactServerComponent.client.ts
index d6a434d340..b143af1c73 100644
--- a/node_package/src/getReactServerComponent.client.ts
+++ b/node_package/src/getReactServerComponent.client.ts
@@ -45,11 +45,10 @@ const createRSCStreamFromArray = (payloads: string[]) => {
       };
 
       payloads.forEach(handleChunk);
-      const originalPush = payloads.push;
       // eslint-disable-next-line no-param-reassign
       payloads.push = (...chunks) => {
         chunks.forEach(handleChunk);
-        return originalPush.call(payloads, ...chunks);
+        return chunks.length;
       };
       streamController = controller;
     },
diff --git a/node_package/tests/RSCClientRoot.test.jsx b/node_package/tests/RSCClientRoot.test.jsx
deleted file mode 100644
index 747d4862df..0000000000
--- a/node_package/tests/RSCClientRoot.test.jsx
+++ /dev/null
@@ -1,152 +0,0 @@
-/* eslint-disable no-underscore-dangle */
-
-// Mock webpack require system for RSC
-window.__webpack_require__ = jest.fn();
-window.__webpack_chunk_load__ = jest.fn();
-
-import { enableFetchMocks } from 'jest-fetch-mock';
-import { screen, act } from '@testing-library/react';
-import '@testing-library/jest-dom';
-import * as path from 'path';
-import * as fs from 'fs';
-import { createNodeReadableStream, getNodeVersion } from './testUtils.js';
-
-import RSCClientRoot from '../src/RSCClientRoot.tsx';
-
-enableFetchMocks();
-
-// React Server Components tests are compatible with React 19
-// That only run with node version 18 and above
-(getNodeVersion() >= 18 ? describe : describe.skip)('RSCClientRoot', () => {
-  let container;
-  const mockDomNodeId = 'test-container';
-
-  beforeEach(() => {
-    // Setup DOM element
-    container = document.createElement('div');
-    container.id = mockDomNodeId;
-    document.body.appendChild(container);
-    jest.clearAllMocks();
-
-    jest.resetModules();
-  });
-
-  afterEach(() => {
-    document.body.removeChild(container);
-  });
-
-  it('throws error when React.use is not defined', () => {
-    jest.mock('react', () => ({
-      ...jest.requireActual('react'),
-      use: undefined,
-    }));
-
-    expect(() => {
-      // Re-import to trigger the check
-      jest.requireActual('../src/RSCClientRoot.ts');
-    }).toThrow('React.use is not defined');
-  });
-
-  const mockRSCRequest = async (rscPayloadGenerationUrlPath = 'rsc-render') => {
-    const chunksDirectory = path.join(
-      __dirname,
-      'fixtures',
-      'rsc-payloads',
-      'simple-shell-with-async-component',
-    );
-    const chunk1 = JSON.parse(fs.readFileSync(path.join(chunksDirectory, 'chunk1.json'), 'utf8'));
-    const chunk2 = JSON.parse(fs.readFileSync(path.join(chunksDirectory, 'chunk2.json'), 'utf8'));
-
-    const { stream, push } = createNodeReadableStream();
-    window.fetchMock.mockResolvedValue(new Response(stream));
-
-    const props = {
-      componentName: 'TestComponent',
-      rscPayloadGenerationUrlPath,
-    };
-
-    // Execute the render
-    const render = () =>
-      act(async () => {
-        await RSCClientRoot(props, undefined, mockDomNodeId);
-      });
-
-    return {
-      render,
-      pushFirstChunk: () => push(`${JSON.stringify(chunk1)}\n`),
-      pushSecondChunk: () => push(`${JSON.stringify(chunk2)}\n`),
-      pushCustomChunk: (chunk) => push(`${chunk}\n`),
-      endStream: () => push(null),
-    };
-  };
-
-  it('renders component progressively', async () => {
-    const { render, pushFirstChunk, pushSecondChunk, endStream } = await mockRSCRequest();
-
-    expect(screen.queryByText('StaticServerComponent')).not.toBeInTheDocument();
-
-    await act(async () => {
-      pushFirstChunk();
-      render();
-    });
-    expect(window.fetch).toHaveBeenCalledWith('/rsc-render/TestComponent?props=undefined');
-    expect(window.fetch).toHaveBeenCalledTimes(1);
-    expect(screen.getByText('StaticServerComponent')).toBeInTheDocument();
-    expect(screen.getByText('Loading AsyncComponent...')).toBeInTheDocument();
-    expect(screen.queryByText('AsyncComponent')).not.toBeInTheDocument();
-
-    await act(async () => {
-      pushSecondChunk();
-      endStream();
-    });
-    expect(screen.getByText('AsyncComponent')).toBeInTheDocument();
-    expect(screen.queryByText('Loading AsyncComponent...')).not.toBeInTheDocument();
-  });
-
-  it('replays console logs', async () => {
-    const consoleSpy = jest.spyOn(console, 'log');
-    const { render, pushFirstChunk, pushSecondChunk, endStream } = await mockRSCRequest();
-
-    await act(async () => {
-      render();
-      pushFirstChunk();
-    });
-    expect(consoleSpy).toHaveBeenCalledWith(
-      expect.stringContaining('Console log at first chunk'),
-      expect.anything(),
-      expect.anything(),
-      expect.anything(),
-    );
-    expect(consoleSpy).toHaveBeenCalledTimes(1);
-
-    await act(async () => {
-      pushSecondChunk();
-    });
-    expect(consoleSpy).toHaveBeenCalledWith(
-      expect.stringContaining('Console log at second chunk'),
-      expect.anything(),
-      expect.anything(),
-      expect.anything(),
-    );
-    await act(async () => {
-      endStream();
-    });
-    expect(consoleSpy).toHaveBeenCalledTimes(2);
-  });
-
-  it('strips leading and trailing slashes from rscPayloadGenerationUrlPath', async () => {
-    const { render, pushFirstChunk, pushSecondChunk, endStream } = await mockRSCRequest('/rsc-render/');
-
-    await act(async () => {
-      render();
-      pushFirstChunk();
-      pushSecondChunk();
-      endStream();
-    });
-
-    expect(window.fetch).toHaveBeenCalledWith('/rsc-render/TestComponent?props=undefined');
-    expect(window.fetch).toHaveBeenCalledTimes(1);
-
-    expect(screen.getByText('StaticServerComponent')).toBeInTheDocument();
-  });
-});
diff --git a/node_package/tests/registerServerComponent.client.test.jsx b/node_package/tests/registerServerComponent.client.test.jsx
new file mode 100644
index 0000000000..47b6922e46
--- /dev/null
+++ b/node_package/tests/registerServerComponent.client.test.jsx
@@ -0,0 +1,253 @@
+/* eslint-disable no-underscore-dangle */
+
+// Mock webpack require system for RSC
+window.__webpack_require__ = jest.fn();
+window.__webpack_chunk_load__ = jest.fn();
+
+import { enableFetchMocks } from 'jest-fetch-mock';
+import { screen, act } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import * as path from 'path';
+import * as fs from 'fs';
+import { createNodeReadableStream, getNodeVersion } from './testUtils.js';
+import ReactOnRails from '../src/ReactOnRails.client.ts';
+import registerServerComponent from '../src/registerServerComponent/client.tsx';
+import { clear as clearComponentRegistry } from '../src/ComponentRegistry.ts';
+
+enableFetchMocks();
+
+// React Server Components tests are compatible with React 19
+// That only run with node version 18 and above
+(getNodeVersion() >= 18 ? describe : describe.skip)('RSCClientRoot', () => {
+  let container;
+  const mockDomNodeId = 'test-container';
+
+  beforeEach(() => {
+    // Setup DOM element
+    clearComponentRegistry();
+    container = document.createElement('div');
+    container.id = mockDomNodeId;
+    document.body.appendChild(container);
+    jest.clearAllMocks();
+
+    jest.resetModules();
+  });
+
+  afterEach(() => {
+    document.body.removeChild(container);
+  });
+
+  it('throws error when React.use is not defined', () => {
+    jest.mock('react', () => ({
+      ...jest.requireActual('react'),
+      use: undefined,
+    }));
+
+    expect(() => {
+      // Re-import to trigger the check
+      jest.requireActual('../src/wrapServerComponentRenderer/client.tsx');
+    }).toThrow('React.use is not defined');
+  });
+
+  const mockRSCRequest = async (rscPayloadGenerationUrlPath = 'rsc-render') => {
+    const chunksDirectory = path.join(
+      __dirname,
+      'fixtures',
+      'rsc-payloads',
+      'simple-shell-with-async-component',
+    );
+    const chunk1 = JSON.parse(fs.readFileSync(path.join(chunksDirectory, 'chunk1.json'), 'utf8'));
+    const chunk2 = JSON.parse(fs.readFileSync(path.join(chunksDirectory, 'chunk2.json'), 'utf8'));
+
+    const { stream, push } = createNodeReadableStream();
+    window.fetchMock.mockResolvedValue(new Response(stream));
+
+    registerServerComponent({}, 'TestComponent');
+    const railsContext = {
+      rscPayloadGenerationUrl: rscPayloadGenerationUrlPath,
+      componentSpecificMetadata: {
+        renderRequestId: 'test-render-request-id',
+      },
+    };
+
+    // Execute the render
+    const render = () =>
+      act(async () => {
+        const Component = ReactOnRails.getComponent('TestComponent');
+        await Component.component({}, railsContext, mockDomNodeId);
+      });
+
+    return {
+      render,
+      pushFirstChunk: () => push(`${JSON.stringify(chunk1)}\n`),
+      pushSecondChunk: () => push(`${JSON.stringify(chunk2)}\n`),
+      pushCustomChunk: (chunk) => push(`${chunk}\n`),
+      endStream: () => push(null),
+    };
+  };
+
+  it('renders component progressively', async () => {
+    const { render, pushFirstChunk, pushSecondChunk, endStream } = await mockRSCRequest();
+
+    expect(screen.queryByText('StaticServerComponent')).not.toBeInTheDocument();
+
+    await act(async () => {
+      pushFirstChunk();
+      render();
+    });
+    expect(window.fetch).toHaveBeenCalledWith('/rsc-render/TestComponent?props={}');
+    expect(window.fetch).toHaveBeenCalledTimes(1);
+    expect(screen.getByText('StaticServerComponent')).toBeInTheDocument();
+    expect(screen.getByText('Loading AsyncComponent...')).toBeInTheDocument();
+    expect(screen.queryByText('AsyncComponent')).not.toBeInTheDocument();
+
+    await act(async () => {
+      pushSecondChunk();
+      endStream();
+    });
+    expect(screen.getByText('AsyncComponent')).toBeInTheDocument();
+    expect(screen.queryByText('Loading AsyncComponent...')).not.toBeInTheDocument();
+  });
+
+  it('replays console logs', async () => {
+    const consoleSpy = jest.spyOn(console, 'log');
+    const { render, pushFirstChunk, pushSecondChunk, endStream } = await mockRSCRequest();
+
+    await act(async () => {
+      render();
+      pushFirstChunk();
+    });
+    expect(consoleSpy).toHaveBeenCalledWith(
+      expect.stringContaining('Console log at first chunk'),
+      expect.anything(),
+      expect.anything(),
+      expect.anything(),
+    );
+    expect(consoleSpy).toHaveBeenCalledTimes(1);
+
+    await act(async () => {
+      pushSecondChunk();
+    });
+    expect(consoleSpy).toHaveBeenCalledWith(
+      expect.stringContaining('Console log at second chunk'),
+      expect.anything(),
+      expect.anything(),
+      expect.anything(),
+    );
+    await act(async () => {
+      endStream();
+    });
+    expect(consoleSpy).toHaveBeenCalledTimes(2);
+  });
+
+  it('strips leading and trailing slashes from rscPayloadGenerationUrlPath', async () => {
+    const { render, pushFirstChunk, pushSecondChunk, endStream } = await mockRSCRequest('/rsc-render/');
+
+    await act(async () => {
+      render();
+      pushFirstChunk();
+      pushSecondChunk();
+      endStream();
+    });
+
+    expect(window.fetch).toHaveBeenCalledWith('/rsc-render/TestComponent?props={}');
+    expect(window.fetch).toHaveBeenCalledTimes(1);
+
+    expect(screen.getByText('StaticServerComponent')).toBeInTheDocument();
+  });
+
+  describe('preloaded RSC payloads', () => {
+    let chunk1;
+    let chunk2;
+    let railsContext;
+
+    beforeEach(() => {
+      // Setup test fixtures
+      const chunksDirectory = path.join(
+        __dirname,
+        'fixtures',
+        'rsc-payloads',
+        'simple-shell-with-async-component',
+      );
+      chunk1 = JSON.stringify(JSON.parse(fs.readFileSync(path.join(chunksDirectory, 'chunk1.json'), 'utf8')));
+      chunk2 = JSON.stringify(JSON.parse(fs.readFileSync(path.join(chunksDirectory, 'chunk2.json'), 'utf8')));
+
+      registerServerComponent({}, 'TestComponent');
+      railsContext = {
+        rscPayloadGenerationUrl: 'rsc-render',
+        componentSpecificMetadata: {
+          renderRequestId: 'test-render-request-id',
+        },
+      };
+
+      // Cleanup any previous payload data
+      delete window.REACT_ON_RAILS_RSC_PAYLOADS;
+    });
+
+    afterEach(() => {
+      // Clean up
+      delete window.REACT_ON_RAILS_RSC_PAYLOADS;
+    });
+
+    it('uses preloaded RSC payloads without making a fetch request', async () => {
+      // Mock the global window.REACT_ON_RAILS_RSC_PAYLOADS
+      window.REACT_ON_RAILS_RSC_PAYLOADS = {
+        'TestComponent-{}-test-render-request-id': [`${chunk1}\n`, `${chunk2}\n`],
+      };
+
+      await act(async () => {
+        const Component = ReactOnRails.getComponent('TestComponent');
+        await Component.component({}, railsContext, mockDomNodeId);
+      });
+
+      // Verify no fetch request was made
+      expect(window.fetch).not.toHaveBeenCalled();
+
+      // Verify the component rendered correctly
+      expect(screen.getByText('StaticServerComponent')).toBeInTheDocument();
+      expect(screen.getByText('AsyncComponent')).toBeInTheDocument();
+      expect(screen.queryByText('Loading AsyncComponent...')).not.toBeInTheDocument();
+    });
+
+    it('renders progressively when additional chunks are pushed to preloaded RSC payloads', async () => {
+      // Mock document.readyState to be 'loading'
+      const originalReadyState = document.readyState;
+      Object.defineProperty(document, 'readyState', { value: 'loading', writable: true });
+
+      // Mock the global window.REACT_ON_RAILS_RSC_PAYLOADS with only the first chunk initially
+      window.REACT_ON_RAILS_RSC_PAYLOADS = {
+        'TestComponent-{}-test-render-request-id': [`${chunk1}\n`],
+      };
+
+      await act(async () => {
+        const Component = ReactOnRails.getComponent('TestComponent');
+        await Component.component({}, railsContext, mockDomNodeId);
+      });
+
+      // Verify no fetch request was made
+      expect(window.fetch).not.toHaveBeenCalled();
+
+      // After first chunk, StaticServerComponent should be visible but AsyncComponent should be loading
+      expect(screen.getByText('StaticServerComponent')).toBeInTheDocument();
+      expect(screen.getByText('Loading AsyncComponent...')).toBeInTheDocument();
+      expect(screen.queryByText('AsyncComponent')).not.toBeInTheDocument();
+
+      // Now push the second chunk to the preloaded array and set document to complete
+      await act(async () => {
+        window.REACT_ON_RAILS_RSC_PAYLOADS['TestComponent-{}-test-render-request-id'].push(`${chunk2}\n`);
+
+        // Set document.readyState to 'complete' and dispatch readystatechange event
+        Object.defineProperty(document, 'readyState', { value: 'complete', writable: true });
+        document.dispatchEvent(new Event('readystatechange'));
+        document.dispatchEvent(new Event('DOMContentLoaded'));
+      });
+
+      // After second chunk, AsyncComponent should now be visible and loading indicator gone
+      expect(screen.getByText('AsyncComponent')).toBeInTheDocument();
+      expect(screen.queryByText('Loading AsyncComponent...')).not.toBeInTheDocument();
+
+      // Restore original readyState
+      Object.defineProperty(document, 'readyState', { value: originalReadyState });
+    });
+  });
+});

From 6977ced58342404249ede4c53fe8e5522d1a50fd Mon Sep 17 00:00:00 2001
From: Abanoub Ghadban <abanoub@shakacode.com>
Date: Mon, 28 Apr 2025 13:33:25 +0300
Subject: [PATCH 11/50] update injectRSCPayload tests to expect the new
 behavior

---
 node_package/tests/injectRSCPayload.test.ts | 126 ++++++++++----------
 1 file changed, 65 insertions(+), 61 deletions(-)

diff --git a/node_package/tests/injectRSCPayload.test.ts b/node_package/tests/injectRSCPayload.test.ts
index cd0687b087..5a47c50cf3 100644
--- a/node_package/tests/injectRSCPayload.test.ts
+++ b/node_package/tests/injectRSCPayload.test.ts
@@ -2,70 +2,80 @@ import { Readable, PassThrough } from 'stream';
 import ReactOnRails, { RailsContext } from '../src/ReactOnRails.node.ts';
 import injectRSCPayload from '../src/injectRSCPayload.ts';
 
-describe('injectRSCPayload', () => {
-  const createMockStream = (chunks: (string | Buffer)[] | { [key: number]: string | string[] }) => {
-    if (Array.isArray(chunks)) {
-      return Readable.from(
-        chunks.map((chunk) => (typeof chunk === 'string' ? new TextEncoder().encode(chunk) : chunk)),
-      );
-    }
-    const passThrough = new PassThrough();
-    const entries = Object.entries(chunks);
-    const keysLength = entries.length;
-    entries.forEach(([delay, value], index) => {
-      setTimeout(() => {
-        const chunksArray = Array.isArray(value) ? value : [value];
-        chunksArray.forEach((chunk) => {
-          passThrough.push(new TextEncoder().encode(chunk));
-        });
-        if (index === keysLength - 1) {
-          passThrough.push(null);
-        }
-      }, +delay);
-    });
-    return passThrough;
-  };
+// Shared utilities
+const createMockStream = (chunks: (string | Buffer)[] | { [key: number]: string | string[] }) => {
+  if (Array.isArray(chunks)) {
+    return Readable.from(
+      chunks.map((chunk) => (typeof chunk === 'string' ? new TextEncoder().encode(chunk) : chunk)),
+    );
+  }
+  const passThrough = new PassThrough();
+  const entries = Object.entries(chunks);
+  const keysLength = entries.length;
+  entries.forEach(([delay, value], index) => {
+    setTimeout(() => {
+      const chunksArray = Array.isArray(value) ? value : [value];
+      chunksArray.forEach((chunk) => {
+        passThrough.push(new TextEncoder().encode(chunk));
+      });
+      if (index === keysLength - 1) {
+        passThrough.push(null);
+      }
+    }, +delay);
+  });
+  return passThrough;
+};
+
+const collectStreamData = async (stream: Readable) => {
+  const chunks: string[] = [];
+  for await (const chunk of stream) {
+    chunks.push(new TextDecoder().decode(chunk as Buffer));
+  }
+  return chunks.join('');
+};
+
+// Test setup helper
+const setupTest = (mockRSC: Readable) => {
+  jest.spyOn(ReactOnRails, 'onRSCPayloadGenerated').mockImplementation((_railsContext, callback) => {
+    callback({ stream: mockRSC, componentName: 'test', props: {} });
+  });
 
-  const collectStreamData = async (stream: Readable) => {
-    const chunks: string[] = [];
-    for await (const chunk of stream) {
-      chunks.push(new TextDecoder().decode(chunk as Buffer));
-    }
-    return chunks.join('');
-  };
+  const railsContext = {
+    componentSpecificMetadata: {
+      renderRequestId: '123',
+    },
+  } as RailsContext;
 
+  return { railsContext };
+};
+
+describe('injectRSCPayload', () => {
   it('should inject RSC payload as script tags', async () => {
     const mockRSC = createMockStream(['{"test": "data"}']);
     const mockHTML = createMockStream(['<html><body><div>Hello, world!</div></body></html>']);
+    const { railsContext } = setupTest(mockRSC);
 
-    jest
-      .spyOn(ReactOnRails, 'getRSCPayloadStreams')
-      .mockReturnValue([{ stream: mockRSC, componentName: 'test', props: {} }]);
-
-    const result = injectRSCPayload(mockHTML, {} as RailsContext);
+    const result = injectRSCPayload(mockHTML, railsContext);
     const resultStr = await collectStreamData(result);
 
     expect(resultStr).toContain(
-      '<script>(self.REACT_ON_RAILS_RSC_PAYLOAD||=[]).push("{\\"test\\": \\"data\\"}")</script>',
+      `<script>((self.REACT_ON_RAILS_RSC_PAYLOADS||={})["test-{}-123"]||=[]).push("{\\"test\\": \\"data\\"}")</script>`,
     );
   });
 
   it('should handle multiple RSC payloads', async () => {
     const mockRSC = createMockStream(['{"test": "data"}', '{"test": "data2"}']);
     const mockHTML = createMockStream(['<html><body><div>Hello, world!</div></body></html>']);
+    const { railsContext } = setupTest(mockRSC);
 
-    jest
-      .spyOn(ReactOnRails, 'getRSCPayloadStreams')
-      .mockReturnValue([{ stream: mockRSC, componentName: 'test', props: {} }]);
-
-    const result = injectRSCPayload(mockHTML, {} as RailsContext);
+    const result = injectRSCPayload(mockHTML, railsContext);
     const resultStr = await collectStreamData(result);
 
     expect(resultStr).toContain(
-      '<script>(self.REACT_ON_RAILS_RSC_PAYLOAD||=[]).push("{\\"test\\": \\"data\\"}")</script>',
+      `<script>((self.REACT_ON_RAILS_RSC_PAYLOADS||={})["test-{}-123"]||=[]).push("{\\"test\\": \\"data\\"}")</script>`,
     );
     expect(resultStr).toContain(
-      '<script>(self.REACT_ON_RAILS_RSC_PAYLOAD||=[]).push("{\\"test\\": \\"data2\\"}")</script>',
+      `<script>((self.REACT_ON_RAILS_RSC_PAYLOADS||={})["test-{}-123"]||=[]).push("{\\"test\\": \\"data2\\"}")</script>`,
     );
   });
 
@@ -75,18 +85,16 @@ describe('injectRSCPayload', () => {
       '<html><body><div>Hello, world!</div></body></html>',
       '<div>Next chunk</div>',
     ]);
-    jest
-      .spyOn(ReactOnRails, 'getRSCPayloadStreams')
-      .mockReturnValue([{ stream: mockRSC, componentName: 'test', props: {} }]);
+    const { railsContext } = setupTest(mockRSC);
 
-    const result = injectRSCPayload(mockHTML, {} as RailsContext);
+    const result = injectRSCPayload(mockHTML, railsContext);
     const resultStr = await collectStreamData(result);
 
     expect(resultStr).toEqual(
       '<html><body><div>Hello, world!</div></body></html>' +
         '<div>Next chunk</div>' +
-        '<script>(self.REACT_ON_RAILS_RSC_PAYLOAD||=[]).push("{\\"test\\": \\"data\\"}")</script>' +
-        '<script>(self.REACT_ON_RAILS_RSC_PAYLOAD||=[]).push("{\\"test\\": \\"data2\\"}")</script>',
+        `<script>((self.REACT_ON_RAILS_RSC_PAYLOADS||={})["test-{}-123"]||=[]).push("{\\"test\\": \\"data\\"}")</script>` +
+        `<script>((self.REACT_ON_RAILS_RSC_PAYLOADS||={})["test-{}-123"]||=[]).push("{\\"test\\": \\"data2\\"}")</script>`,
     );
   });
 
@@ -96,17 +104,15 @@ describe('injectRSCPayload', () => {
       0: '<html><body><div>Hello, world!</div></body></html>',
       100: '<div>Next chunk</div>',
     });
-    jest
-      .spyOn(ReactOnRails, 'getRSCPayloadStreams')
-      .mockReturnValue([{ stream: mockRSC, componentName: 'test', props: {} }]);
+    const { railsContext } = setupTest(mockRSC);
 
-    const result = injectRSCPayload(mockHTML, {} as RailsContext);
+    const result = injectRSCPayload(mockHTML, railsContext);
     const resultStr = await collectStreamData(result);
 
     expect(resultStr).toEqual(
       '<html><body><div>Hello, world!</div></body></html>' +
-        '<script>(self.REACT_ON_RAILS_RSC_PAYLOAD||=[]).push("{\\"test\\": \\"data\\"}")</script>' +
-        '<script>(self.REACT_ON_RAILS_RSC_PAYLOAD||=[]).push("{\\"test\\": \\"data2\\"}")</script>' +
+        `<script>((self.REACT_ON_RAILS_RSC_PAYLOADS||={})["test-{}-123"]||=[]).push("{\\"test\\": \\"data\\"}")</script>` +
+        `<script>((self.REACT_ON_RAILS_RSC_PAYLOADS||={})["test-{}-123"]||=[]).push("{\\"test\\": \\"data2\\"}")</script>` +
         '<div>Next chunk</div>',
     );
   });
@@ -120,18 +126,16 @@ describe('injectRSCPayload', () => {
       100: ['<html><body><div>Hello, world!</div></body></html>', '<div>Next chunk</div>'],
       200: '<div>Third chunk</div>',
     });
-    jest
-      .spyOn(ReactOnRails, 'getRSCPayloadStreams')
-      .mockReturnValue([{ stream: mockRSC, componentName: 'test', props: {} }]);
+    const { railsContext } = setupTest(mockRSC);
 
-    const result = injectRSCPayload(mockHTML, {} as RailsContext);
+    const result = injectRSCPayload(mockHTML, railsContext);
     const resultStr = await collectStreamData(result);
 
     expect(resultStr).toEqual(
       '<html><body><div>Hello, world!</div></body></html>' +
         '<div>Next chunk</div>' +
-        '<script>(self.REACT_ON_RAILS_RSC_PAYLOAD||=[]).push("{\\"test\\": \\"data\\"}")</script>' +
-        '<script>(self.REACT_ON_RAILS_RSC_PAYLOAD||=[]).push("{\\"test\\": \\"data2\\"}")</script>' +
+        `<script>((self.REACT_ON_RAILS_RSC_PAYLOADS||={})["test-{}-123"]||=[]).push("{\\"test\\": \\"data\\"}")</script>` +
+        `<script>((self.REACT_ON_RAILS_RSC_PAYLOADS||={})["test-{}-123"]||=[]).push("{\\"test\\": \\"data2\\"}")</script>` +
         '<div>Third chunk</div>',
     );
   });

From 05f9cbbe32d70ef90b55224a64e712eb453ce400 Mon Sep 17 00:00:00 2001
From: Abanoub Ghadban <abanoub@shakacode.com>
Date: Mon, 28 Apr 2025 15:19:42 +0300
Subject: [PATCH 12/50] fix streamServerRenderedReactComponent and helper specs

---
 .../react_component/render_options.rb         |  6 ++-
 ...treamServerRenderedReactComponent.test.jsx | 41 +++++++++++++------
 .../helpers/react_on_rails_helper_spec.rb     | 14 ++++---
 3 files changed, 42 insertions(+), 19 deletions(-)

diff --git a/lib/react_on_rails/react_component/render_options.rb b/lib/react_on_rails/react_component/render_options.rb
index b9d128db61..29bfbb7c74 100644
--- a/lib/react_on_rails/react_component/render_options.rb
+++ b/lib/react_on_rails/react_component/render_options.rb
@@ -21,7 +21,7 @@ def initialize(react_component_name: required("react_component_name"), options:
         # Therefore, we need an additional unique identifier that can be used both on the client and server.
         # This ID can also be used to associate specific data with a particular rendered component
         # on either the server or client.
-        @render_request_id = SecureRandom.uuid
+        @render_request_id = self.class.generate_request_id
       end
 
       attr_reader :react_component_name, :render_request_id
@@ -146,6 +146,10 @@ def store_dependencies
         options[:store_dependencies]
       end
 
+      def self.generate_request_id
+        SecureRandom.uuid
+      end
+
       private
 
       attr_reader :options
diff --git a/node_package/tests/streamServerRenderedReactComponent.test.jsx b/node_package/tests/streamServerRenderedReactComponent.test.jsx
index 4384428c0a..68cbbc5852 100644
--- a/node_package/tests/streamServerRenderedReactComponent.test.jsx
+++ b/node_package/tests/streamServerRenderedReactComponent.test.jsx
@@ -6,6 +6,7 @@ import * as React from 'react';
 import * as PropTypes from 'prop-types';
 import streamServerRenderedReactComponent from '../src/streamServerRenderedReactComponent.ts';
 import * as ComponentRegistry from '../src/ComponentRegistry.ts';
+import ReactOnRails from '../src/ReactOnRails.node.ts';
 
 const AsyncContent = async ({ throwAsyncError }) => {
   await new Promise((resolve) => {
@@ -64,21 +65,21 @@ describe('streamServerRenderedReactComponent', () => {
   } = {}) => {
     switch (componentType) {
       case 'reactComponent':
-        ComponentRegistry.register({ TestComponentForStreaming });
+        ReactOnRails.register({ TestComponentForStreaming });
         break;
       case 'renderFunction':
-        ComponentRegistry.register({
+        ReactOnRails.register({
           TestComponentForStreaming: (props, _railsContext) => () => <TestComponentForStreaming {...props} />,
         });
         break;
       case 'asyncRenderFunction':
-        ComponentRegistry.register({
+        ReactOnRails.register({
           TestComponentForStreaming: (props, _railsContext) => () =>
             Promise.resolve(<TestComponentForStreaming {...props} />),
         });
         break;
       case 'erroneousRenderFunction':
-        ComponentRegistry.register({
+        ReactOnRails.register({
           TestComponentForStreaming: (_props, _railsContext) => {
             // The error happen inside the render function itself not inside the returned React component
             throw new Error('Sync Error from render function');
@@ -86,7 +87,7 @@ describe('streamServerRenderedReactComponent', () => {
         });
         break;
       case 'erroneousAsyncRenderFunction':
-        ComponentRegistry.register({
+        ReactOnRails.register({
           TestComponentForStreaming: (_props, _railsContext) =>
             // The error happen inside the render function itself not inside the returned React component
             Promise.reject(new Error('Async Error from render function')),
@@ -101,6 +102,11 @@ describe('streamServerRenderedReactComponent', () => {
       trace: false,
       props: { throwSyncError, throwAsyncError },
       throwJsErrors,
+      railsContext: {
+        componentSpecificMetadata: {
+          renderRequestId: '123',
+        },
+      },
     });
 
     const chunks = [];
@@ -173,13 +179,15 @@ describe('streamServerRenderedReactComponent', () => {
     expect(chunks.length).toBeGreaterThanOrEqual(2);
     expect(chunks[0].html).toContain('Header In The Shell');
     expect(chunks[0].consoleReplayScript).toBe('');
-    expect(chunks[0].hasErrors).toBe(false);
     expect(chunks[0].isShellReady).toBe(true);
     // Script that fallbacks the render to client side
     expect(chunks[1].html).toMatch(/the server rendering errored:\\n\\nAsync Error/);
     expect(chunks[1].consoleReplayScript).toBe('');
-    expect(chunks[1].hasErrors).toBe(true);
     expect(chunks[1].isShellReady).toBe(true);
+
+    // One of the chunks should have a hasErrors property of true
+    expect(chunks[0].hasErrors || chunks[1].hasErrors).toBe(true);
+    expect(chunks[0].hasErrors && chunks[1].hasErrors).toBe(false);
   });
 
   it("doesn't emit an error if there is an error in the async content and throwJsErrors is false", async () => {
@@ -194,13 +202,15 @@ describe('streamServerRenderedReactComponent', () => {
     expect(chunks.length).toBeGreaterThanOrEqual(2);
     expect(chunks[0].html).toContain('Header In The Shell');
     expect(chunks[0].consoleReplayScript).toBe('');
-    expect(chunks[0].hasErrors).toBe(false);
     expect(chunks[0].isShellReady).toBe(true);
     // Script that fallbacks the render to client side
     expect(chunks[1].html).toMatch(/the server rendering errored:\\n\\nAsync Error/);
     expect(chunks[1].consoleReplayScript).toBe('');
-    expect(chunks[1].hasErrors).toBe(true);
     expect(chunks[1].isShellReady).toBe(true);
+
+    // One of the chunks should have a hasErrors property of true
+    expect(chunks[0].hasErrors || chunks[1].hasErrors).toBe(true);
+    expect(chunks[0].hasErrors && chunks[1].hasErrors).toBe(false);
   });
 
   it.each(['asyncRenderFunction', 'renderFunction'])(
@@ -250,12 +260,14 @@ describe('streamServerRenderedReactComponent', () => {
       expect(chunks.length).toBeGreaterThanOrEqual(2);
       expect(chunks[0].html).toContain('Header In The Shell');
       expect(chunks[0].consoleReplayScript).toBe('');
-      expect(chunks[0].hasErrors).toBe(false);
       expect(chunks[0].isShellReady).toBe(true);
       expect(chunks[1].html).toMatch(/the server rendering errored:\\n\\nAsync Error/);
       expect(chunks[1].consoleReplayScript).toBe('');
-      expect(chunks[1].hasErrors).toBe(true);
       expect(chunks[1].isShellReady).toBe(true);
+
+      // One of the chunks should have a hasErrors property of true
+      expect(chunks[0].hasErrors || chunks[1].hasErrors).toBe(true);
+      expect(chunks[0].hasErrors && chunks[1].hasErrors).toBe(false);
     },
   );
 
@@ -308,13 +320,18 @@ describe('streamServerRenderedReactComponent', () => {
 
   it('streams a string from a Promise that resolves to a string', async () => {
     const StringPromiseComponent = () => Promise.resolve('<div>String from Promise</div>');
-    ComponentRegistry.register({ StringPromiseComponent });
+    ReactOnRails.register({ StringPromiseComponent });
 
     const renderResult = streamServerRenderedReactComponent({
       name: 'StringPromiseComponent',
       domNodeId: 'stringPromiseId',
       trace: false,
       throwJsErrors: false,
+      railsContext: {
+        componentSpecificMetadata: {
+          renderRequestId: '123',
+        },
+      },
     });
 
     const chunks = [];
diff --git a/spec/dummy/spec/helpers/react_on_rails_helper_spec.rb b/spec/dummy/spec/helpers/react_on_rails_helper_spec.rb
index b1e9f7d29b..6aa1544b26 100644
--- a/spec/dummy/spec/helpers/react_on_rails_helper_spec.rb
+++ b/spec/dummy/spec/helpers/react_on_rails_helper_spec.rb
@@ -21,6 +21,8 @@ class PlainReactOnRailsHelper
         { "HTTP_ACCEPT_LANGUAGE" => "en" }
       )
     }
+
+    allow(ReactOnRails::ReactComponent::RenderOptions).to receive(:generate_request_id).and_return("123")
   end
 
   let(:hash) do
@@ -195,7 +197,7 @@ def helper.append_javascript_pack_tag(name, **options)
         <script type="application/json" class="js-react-on-rails-component" \
         id="js-react-on-rails-component-App-react-component" \
         data-component-name="App" data-dom-id="App-react-component"
-        data-force-load="true">{"name":"My Test Name"}</script>
+        data-force-load="true" data-render-request-id="123">{"name":"My Test Name"}</script>
       SCRIPT
     end
 
@@ -204,7 +206,7 @@ def helper.append_javascript_pack_tag(name, **options)
         <script type="application/json" class="js-react-on-rails-component" \
         id="js-react-on-rails-component-App-react-component" \
         data-component-name="App" data-dom-id="App-react-component"
-        data-force-load="true">{}</script>
+        data-force-load="true" data-render-request-id="123">{}</script>
       SCRIPT
     end
 
@@ -253,7 +255,7 @@ def helper.append_javascript_pack_tag(name, **options)
           <script type="application/json" class="js-react-on-rails-component" \
           id="js-react-on-rails-component-App-react-component" \
           data-component-name="App" data-dom-id="App-react-component"
-          data-force-load="true">{"name":"My Test Name"}</script>
+          data-force-load="true" data-render-request-id="123">{"name":"My Test Name"}</script>
         SCRIPT
       end
 
@@ -269,7 +271,7 @@ def helper.append_javascript_pack_tag(name, **options)
           <script type="application/json" class="js-react-on-rails-component" \
           id="js-react-on-rails-component-App-react-component-0" \
           data-component-name="App" data-dom-id="App-react-component-0"
-          data-force-load="true">{"name":"My Test Name"}</script>
+          data-force-load="true" data-render-request-id="123">{"name":"My Test Name"}</script>
         SCRIPT
       end
 
@@ -291,7 +293,7 @@ def helper.append_javascript_pack_tag(name, **options)
           <script type="application/json" class="js-react-on-rails-component" \
           id="js-react-on-rails-component-App-react-component" \
           data-component-name="App" data-dom-id="App-react-component"
-          data-force-load="true">{"name":"My Test Name"}</script>
+          data-force-load="true" data-render-request-id="123">{"name":"My Test Name"}</script>
         SCRIPT
       end
 
@@ -309,7 +311,7 @@ def helper.append_javascript_pack_tag(name, **options)
           <script type="application/json" class="js-react-on-rails-component" \
           id="js-react-on-rails-component-shaka_div" \
           data-component-name="App" data-dom-id="shaka_div"
-          data-force-load="true">{"name":"My Test Name"}</script>
+          data-force-load="true" data-render-request-id="123">{"name":"My Test Name"}</script>
         SCRIPT
       end
 

From 1a452d7e8cabdd2d35680404645342511925da7f Mon Sep 17 00:00:00 2001
From: Abanoub Ghadban <abanoub@shakacode.com>
Date: Mon, 28 Apr 2025 15:42:03 +0300
Subject: [PATCH 13/50] Update renderContextRows to exclude
 'componentSpecificMetadata' from rendering

---
 spec/dummy/client/app/components/RailsContext.jsx | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/spec/dummy/client/app/components/RailsContext.jsx b/spec/dummy/client/app/components/RailsContext.jsx
index 68d5cec378..83568b8405 100644
--- a/spec/dummy/client/app/components/RailsContext.jsx
+++ b/spec/dummy/client/app/components/RailsContext.jsx
@@ -7,15 +7,14 @@ function renderContextRows(railsContext) {
   return _.transform(
     railsContext,
     (accum, value, key) => {
-      if (key !== 'serverSide') {
+      if (key !== 'serverSide' && key !== 'componentSpecificMetadata') {
         const className = `js-${key}`;
-        const stringifiedValue = typeof value === 'object' ? JSON.stringify(value) : value;
         accum.push(
           <tr key={className}>
             <td>
               <strong>{key}:&nbsp;</strong>
             </td>
-            <td className={className}>{`${stringifiedValue}`}</td>
+            <td className={className}>{`${value}`}</td>
           </tr>,
         );
       }

From d4c7249bfee7ae630b01d91b9e4b271d79c8efb1 Mon Sep 17 00:00:00 2001
From: Abanoub Ghadban <abanoub@shakacode.com>
Date: Mon, 28 Apr 2025 16:17:09 +0300
Subject: [PATCH 14/50] fix knip errors

---
 knip.ts                                                 | 8 +++++---
 node_package/src/RSCProvider.tsx                        | 2 +-
 node_package/src/getReactServerComponent.client.ts      | 6 ++++--
 node_package/src/wrapServerComponentRenderer/client.tsx | 2 +-
 4 files changed, 11 insertions(+), 7 deletions(-)

diff --git a/knip.ts b/knip.ts
index 9480c139de..edf406f5fa 100644
--- a/knip.ts
+++ b/knip.ts
@@ -7,10 +7,12 @@ const config: KnipConfig = {
       entry: [
         'node_package/src/ReactOnRails.node.ts!',
         'node_package/src/ReactOnRailsRSC.ts!',
-        'node_package/src/registerServerComponent/client.ts!',
-        'node_package/src/registerServerComponent/server.ts!',
+        'node_package/src/registerServerComponent/client.tsx!',
+        'node_package/src/registerServerComponent/server.tsx!',
         'node_package/src/registerServerComponent/server.rsc.ts!',
-        'node_package/src/RSCClientRoot.ts!',
+        'node_package/src/wrapServerComponentRenderer/server.tsx!',
+        'node_package/src/wrapServerComponentRenderer/server.rsc.tsx!',
+        'node_package/src/RSCRoute.ts!',
         'eslint.config.ts',
       ],
       project: ['node_package/src/**/*.[jt]s{x,}!', 'node_package/tests/**/*.[jt]s{x,}'],
diff --git a/node_package/src/RSCProvider.tsx b/node_package/src/RSCProvider.tsx
index 683dd230df..a0b3e59355 100644
--- a/node_package/src/RSCProvider.tsx
+++ b/node_package/src/RSCProvider.tsx
@@ -1,6 +1,6 @@
 import * as React from 'react';
 import { RailsContext } from './types/index.ts';
-import { getReactServerComponent } from './getReactServerComponent.client.ts';
+import getReactServerComponent from './getReactServerComponent.client.ts';
 
 type RSCContextType = {
   getCachedComponent: (componentName: string, componentProps: unknown) => React.ReactNode;
diff --git a/node_package/src/getReactServerComponent.client.ts b/node_package/src/getReactServerComponent.client.ts
index b143af1c73..7f6197b373 100644
--- a/node_package/src/getReactServerComponent.client.ts
+++ b/node_package/src/getReactServerComponent.client.ts
@@ -10,7 +10,7 @@ declare global {
   }
 }
 
-export type ClientGetReactServerComponentProps = {
+type ClientGetReactServerComponentProps = {
   componentName: string;
   componentProps: unknown;
   railsContext: RailsContext;
@@ -71,7 +71,7 @@ const createFromPreloadedPayloads = (payloads: string[]) => {
   return createFromReadableStream<React.ReactNode>(transformedStream);
 };
 
-export const getReactServerComponent = ({
+const getReactServerComponent = ({
   componentName,
   componentProps,
   railsContext,
@@ -83,3 +83,5 @@ export const getReactServerComponent = ({
   }
   return fetchRSC({ componentName, componentProps, railsContext });
 };
+
+export default getReactServerComponent;
diff --git a/node_package/src/wrapServerComponentRenderer/client.tsx b/node_package/src/wrapServerComponentRenderer/client.tsx
index 7ada916bd7..1937f7a624 100644
--- a/node_package/src/wrapServerComponentRenderer/client.tsx
+++ b/node_package/src/wrapServerComponentRenderer/client.tsx
@@ -4,7 +4,7 @@ import { ReactComponentOrRenderFunction, RenderFunction } from '../types/index.t
 import isRenderFunction from '../isRenderFunction.ts';
 import { ensureReactUseAvailable } from '../reactApis.cts';
 import { createRSCProvider } from '../RSCProvider.tsx';
-import { getReactServerComponent } from '../getReactServerComponent.client.ts';
+import getReactServerComponent from '../getReactServerComponent.client.ts';
 
 ensureReactUseAvailable();
 

From 73ce3a6ab37b9dc2f95f97e9a6219330663d45d3 Mon Sep 17 00:00:00 2001
From: Abanoub Ghadban <abanoub@shakacode.com>
Date: Mon, 28 Apr 2025 16:57:03 +0300
Subject: [PATCH 15/50] Remove RSCServerRoot entry from package.json

---
 package.json | 1 -
 1 file changed, 1 deletion(-)

diff --git a/package.json b/package.json
index 6d672ac8ec..1825679bb3 100644
--- a/package.json
+++ b/package.json
@@ -16,7 +16,6 @@
       "react-server": "./node_package/lib/registerServerComponent/server.rsc.js",
       "default": "./node_package/lib/registerServerComponent/server.js"
     },
-    "./RSCServerRoot": "./node_package/lib/RSCServerRoot.js",
     "./wrapServerComponentRenderer/client": "./node_package/lib/wrapServerComponentRenderer/client.js",
     "./wrapServerComponentRenderer/server": {
       "react-server": "./node_package/lib/wrapServerComponentRenderer/server.rsc.js",

From 0639b296a72b6edea71158217a907d957f31e578 Mon Sep 17 00:00:00 2001
From: Abanoub Ghadban <abanoub@shakacode.com>
Date: Mon, 28 Apr 2025 19:36:37 +0300
Subject: [PATCH 16/50] add test to test the behavior of hydrating Suspensable
 components

---
 eslint.config.ts                              |   4 +-
 node_package/tests/SuspenseHydration.test.tsx | 201 ++++++++++++++++++
 2 files changed, 202 insertions(+), 3 deletions(-)
 create mode 100644 node_package/tests/SuspenseHydration.test.tsx

diff --git a/eslint.config.ts b/eslint.config.ts
index c3a535b693..58da16938a 100644
--- a/eslint.config.ts
+++ b/eslint.config.ts
@@ -161,9 +161,7 @@ const config = tsEslint.config([
     languageOptions: {
       parserOptions: {
         projectService: {
-          allowDefaultProject: ['eslint.config.ts', 'knip.ts', 'node_package/tests/*.test.ts'],
-          // Needed because `import * as ... from` instead of `import ... from` doesn't work in this file
-          // for some imports.
+          allowDefaultProject: ['eslint.config.ts', 'knip.ts', 'node_package/tests/*.test.{ts,tsx}'],
           defaultProject: 'tsconfig.eslint.json',
         },
       },
diff --git a/node_package/tests/SuspenseHydration.test.tsx b/node_package/tests/SuspenseHydration.test.tsx
new file mode 100644
index 0000000000..64b4258300
--- /dev/null
+++ b/node_package/tests/SuspenseHydration.test.tsx
@@ -0,0 +1,201 @@
+import * as React from 'react';
+import { Suspense } from 'react';
+import { renderToReadableStream } from 'react-dom/server';
+import { hydrateRoot } from 'react-dom/client';
+import { screen, act, waitFor } from '@testing-library/react';
+import '@testing-library/jest-dom';
+
+/**
+ * Tests React's Suspense hydration behavior for async components
+ *
+ * This test verifies that async components are only hydrated on the client side after:
+ * 1. The component is rendered on the server
+ * 2. The rendered HTML is streamed to the client
+ *
+ * This behavior is critical for RSCRoute components, as they require their server-side
+ * RSC payload to be present in the page before client-side hydration can occur.
+ * And because the RSCRoute is rendered on the server because it's being hydrated on the client,
+ * we can sure that the RSC payload is present in the page before the RSCRoute is hydrated on the client.
+ * That's because `getRSCPayloadStream` function embeds the RSC payload immediately to the html stream even before the RSCRoute is rendered on the server.
+ * Without this guarantee, hydration would fail or produce incorrect results.
+ */
+
+const AsyncComponent = async ({
+  promise,
+  onRendered,
+}: {
+  promise: Promise<string>;
+  onRendered: () => void;
+}) => {
+  const result = await promise;
+  onRendered();
+  return <div>{result}</div>;
+};
+
+const AsyncComponentContainer = ({
+  onContainerRendered,
+  onAsyncComponentRendered,
+}: {
+  onContainerRendered: () => void;
+  onAsyncComponentRendered: () => void;
+}) => {
+  onContainerRendered();
+  const promise = new Promise<string>((resolve) => {
+    setTimeout(() => resolve('Hello World'), 0);
+  });
+  return (
+    <Suspense fallback={<div>Loading...</div>}>
+      <AsyncComponent promise={promise} onRendered={onAsyncComponentRendered} />
+    </Suspense>
+  );
+};
+
+// Function: appendHTMLWithScripts
+// ------------------------------
+// In a Jest/jsdom environment, scripts injected via innerHTML remain inert (they do not execute).
+// Even with runScripts: 'dangerously', jsdom will not auto-execute <script> tags inserted as strings.
+// This function addresses that by:
+//  1. Parsing the HTML string into a DocumentFragment via a <template> element.
+//  2. Locating each <script> node in the fragment (both inline and external).
+//  3. Re-creating a fresh <script> element for each found script, copying over all attributes
+//     (e.g., src, type, async, data-*, etc.) and inline code content.
+//  4. Replacing the inert original <script> with the new element, which the browser/jsdom will execute.
+//  5. Appending the entire fragment to the document in one operation, ensuring all non-script nodes
+//     and newly created scripts are inserted correctly.
+//
+// Use this helper whenever you need to dynamically inject HTML containing scripts in tests and
+// want to ensure those scripts run as they would in a real browser environment.
+function appendHTMLWithScripts(htmlString: string) {
+  const template = document.createElement('template');
+  template.innerHTML = htmlString;
+  const frag = template.content;
+
+  // re-create each <script> so it executes
+  frag.querySelectorAll('script').forEach((oldScript) => {
+    const newScript = document.createElement('script');
+    // copy attributes
+    for (const { name, value } of oldScript.attributes) {
+      newScript.setAttribute(name, value);
+    }
+    // copy inline code
+    newScript.textContent = oldScript.textContent;
+
+    // replace the inert one with the real one
+    oldScript.replaceWith(newScript);
+  });
+
+  // finally append everything in one go
+  document.body.appendChild(frag);
+}
+
+async function renderAndHydrate() {
+  // create container div element
+  const container = document.createElement('div');
+  container.id = 'container';
+  document.body.appendChild(container);
+
+  const onContainerRendered = jest.fn();
+  const onAsyncComponentRendered = jest.fn();
+  const stream = await renderToReadableStream(
+    <AsyncComponentContainer
+      onContainerRendered={onContainerRendered}
+      onAsyncComponentRendered={onAsyncComponentRendered}
+    />,
+  );
+
+  const onContainerHydrated = jest.fn();
+  const onAsyncComponentHydrated = jest.fn();
+  const hydrate = () =>
+    hydrateRoot(
+      container,
+      <AsyncComponentContainer
+        onContainerRendered={onContainerHydrated}
+        onAsyncComponentRendered={onAsyncComponentHydrated}
+      />,
+    );
+
+  const reader = stream.getReader();
+  const writeFirstChunk = async () => {
+    const result = await reader.read();
+    const decoded = new TextDecoder().decode(result.value as Buffer);
+    container.innerHTML = decoded;
+    return decoded;
+  };
+
+  const writeSecondChunk = async () => {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+    let { done, value } = await reader.read();
+    let decoded = '';
+    while (!done) {
+      decoded += new TextDecoder().decode(value as Buffer);
+      // eslint-disable-next-line no-await-in-loop, @typescript-eslint/no-unsafe-assignment
+      ({ done, value } = await reader.read());
+    }
+
+    appendHTMLWithScripts(decoded);
+    return decoded;
+  };
+
+  return {
+    onContainerRendered,
+    onAsyncComponentRendered,
+    onContainerHydrated,
+    onAsyncComponentHydrated,
+    writeFirstChunk,
+    writeSecondChunk,
+    hydrate,
+  };
+}
+
+beforeEach(() => {
+  jest.clearAllMocks();
+  document.body.innerHTML = '';
+});
+
+it('hydrates the container when its content is written to the document', async () => {
+  const { onContainerHydrated, onAsyncComponentHydrated, writeFirstChunk, hydrate } =
+    await renderAndHydrate();
+
+  await act(async () => {
+    hydrate();
+    await writeFirstChunk();
+  });
+  await waitFor(() => {
+    expect(screen.queryByText('Loading...')).toBeInTheDocument();
+  });
+  expect(onContainerHydrated).toHaveBeenCalled();
+
+  // The async component is not hydrated until the second chunk is written to the document
+  await new Promise((resolve) => {
+    setTimeout(resolve, 1000);
+  });
+  expect(onAsyncComponentHydrated).not.toHaveBeenCalled();
+  expect(screen.queryByText('Loading...')).toBeInTheDocument();
+  expect(screen.queryByText('Hello World')).not.toBeInTheDocument();
+});
+
+it('hydrates the container when its content is written to the document', async () => {
+  const { writeFirstChunk, writeSecondChunk, onAsyncComponentHydrated, onContainerHydrated, hydrate } =
+    await renderAndHydrate();
+
+  await act(async () => {
+    hydrate();
+    await writeFirstChunk();
+  });
+  await waitFor(() => {
+    expect(screen.queryByText('Loading...')).toBeInTheDocument();
+  });
+
+  await act(async () => {
+    const secondChunk = await writeSecondChunk();
+    expect(secondChunk).toContain('script');
+    console.log(secondChunk);
+  });
+  await waitFor(() => {
+    expect(screen.queryByText('Loading...')).not.toBeInTheDocument();
+    expect(screen.queryByText('Hello World')).toBeInTheDocument();
+  });
+
+  expect(onContainerHydrated).toHaveBeenCalled();
+  expect(onAsyncComponentHydrated).toHaveBeenCalled();
+});

From 1dca1caf82ff3b70ab559d92b8a0a8b0c2235294 Mon Sep 17 00:00:00 2001
From: Abanoub Ghadban <abanoub@shakacode.com>
Date: Fri, 2 May 2025 15:06:33 +0300
Subject: [PATCH 17/50] initialize the rsc payload array in a sync manner when
 the generate rsc function is called to avoid hydration race conditions

---
 node_package/src/RSCPayloadGenerator.ts       |  9 +++-
 node_package/src/injectRSCPayload.ts          | 52 ++++++++++++-------
 .../src/streamServerRenderedReactComponent.ts | 37 ++-----------
 .../wrapServerComponentRenderer/client.tsx    |  4 +-
 node_package/tests/SuspenseHydration.test.tsx |  1 +
 5 files changed, 50 insertions(+), 53 deletions(-)

diff --git a/node_package/src/RSCPayloadGenerator.ts b/node_package/src/RSCPayloadGenerator.ts
index 7323bcec4f..acb7733bd3 100644
--- a/node_package/src/RSCPayloadGenerator.ts
+++ b/node_package/src/RSCPayloadGenerator.ts
@@ -13,6 +13,12 @@ const mapRailsContextToRSCPayloadStreams = new Map<RailsContext, RSCPayloadStrea
 
 const rscPayloadCallbacks = new Map<RailsContext, Array<RSCPayloadCallback>>();
 
+// The RSC payload callbacks must be executed synchronously to maintain proper hydration timing.
+// This ensures that the RSC payload initialization script is injected into the HTML page
+// before the corresponding component's HTML markup appears. This timing is critical because:
+// 1. Client-side components only hydrate after their HTML is present in the page
+// 2. The RSC payload must be available before hydration begins to prevent unnecessary refetching
+// 3. Using setTimeout(callback, 0) would break this synchronization and could lead to hydration issues
 export const onRSCPayloadGenerated = (railsContext: RailsContext, callback: RSCPayloadCallback) => {
   const callbacks = rscPayloadCallbacks.get(railsContext) || [];
   callbacks.push(callback);
@@ -51,7 +57,8 @@ export const getRSCPayloadStream = async (
   streams.push(streamInfo);
   mapRailsContextToRSCPayloadStreams.set(railsContext, streams);
 
-  // Notify callbacks about the new stream
+  // Notify callbacks about the new stream in a sync manner to maintain proper hydration timing
+  // as described in the comment above onRSCPayloadGenerated
   const callbacks = rscPayloadCallbacks.get(railsContext) || [];
   callbacks.forEach((callback) => callback(streamInfo));
 
diff --git a/node_package/src/injectRSCPayload.ts b/node_package/src/injectRSCPayload.ts
index cba9d8287b..443387db1e 100644
--- a/node_package/src/injectRSCPayload.ts
+++ b/node_package/src/injectRSCPayload.ts
@@ -14,11 +14,20 @@ function escapeScript(script: string) {
   return script.replace(/<!--/g, '<\\!--').replace(/<\/(script)/gi, '</\\$1');
 }
 
+function cacheKeyJSArray(cacheKey: string) {
+  return `(self.REACT_ON_RAILS_RSC_PAYLOADS||={})[${JSON.stringify(cacheKey)}]||=[]`;
+}
+
+function writeScript(script: string, transform: Transform) {
+  transform.push(`<script>${escapeScript(script)}</script>`);
+}
+
+function initializeCacheKeyJSArray(cacheKey: string, transform: Transform) {
+  writeScript(cacheKeyJSArray(cacheKey), transform);
+}
+
 function writeChunk(chunk: string, transform: Transform, cacheKey: string) {
-  const stringifiedKey = JSON.stringify(cacheKey);
-  transform.push(
-    `<script>${escapeScript(`((self.REACT_ON_RAILS_RSC_PAYLOADS||={})[${stringifiedKey}]||=[]).push(${chunk})`)}</script>`,
-  );
+  writeScript(`(${cacheKeyJSArray(cacheKey)}).push(${chunk})`, transform);
 }
 
 export default function injectRSCPayload(
@@ -29,11 +38,10 @@ export default function injectRSCPayload(
   pipeableHtmlStream.pipe(htmlStream);
   const decoder = new TextDecoder();
   let rscPromise: Promise<void> | null = null;
-  const htmlBuffer: string[] = [];
+  const htmlBuffer: Buffer[] = [];
   let timeout: NodeJS.Timeout | null = null;
   const resultStream = new PassThrough();
 
-  // Start reading RSC stream immediately
   const startRSC = async () => {
     try {
       const rscPromises: Promise<void>[] = [];
@@ -41,14 +49,25 @@ export default function injectRSCPayload(
       ReactOnRails.onRSCPayloadGenerated?.(railsContext, (streamInfo) => {
         const { stream, props, componentName } = streamInfo;
         const cacheKey = `${componentName}-${JSON.stringify(props)}-${railsContext.componentSpecificMetadata?.renderRequestId}`;
+
+        // When a component requests an RSC payload, we initialize a global array to store it.
+        // This array is injected into the HTML before the component's HTML markup.
+        // From our tests in SuspenseHydration.test.tsx, we know that client-side components
+        // only hydrate after their HTML is present in the page. This timing ensures that
+        // the RSC payload array is available before hydration begins.
+        // As a result, the component can access its RSC payload directly from the page
+        // instead of making a separate network request.
+        // The client-side RSCProvider actively monitors the array for new chunks, processing them as they arrive and forwarding them to the RSC payload stream, regardless of whether the array is initially empty.
+        initializeCacheKeyJSArray(cacheKey, resultStream);
         rscPromises.push(
-          // eslint-disable-next-line @typescript-eslint/no-misused-promises, no-async-promise-executor
-          new Promise(async (resolve) => {
-            for await (const chunk of stream ?? []) {
-              const decodedChunk = typeof chunk === 'string' ? chunk : decoder.decode(chunk);
-              writeChunk(JSON.stringify(decodedChunk), resultStream, cacheKey);
-            }
-            resolve();
+          new Promise((resolve, reject) => {
+            (async () => {
+              for await (const chunk of stream ?? []) {
+                const decodedChunk = typeof chunk === 'string' ? chunk : decoder.decode(chunk);
+                writeChunk(JSON.stringify(decodedChunk), resultStream, cacheKey);
+              }
+              resolve();
+            })().catch(reject);
           }),
         );
       });
@@ -68,15 +87,12 @@ export default function injectRSCPayload(
   };
 
   const writeHTMLChunks = () => {
-    for (const htmlChunk of htmlBuffer) {
-      resultStream.push(htmlChunk);
-    }
+    resultStream.push(Buffer.concat(htmlBuffer));
     htmlBuffer.length = 0;
   };
 
   htmlStream.on('data', (chunk: Buffer) => {
-    const buf = decoder.decode(chunk);
-    htmlBuffer.push(buf);
+    htmlBuffer.push(chunk);
     if (timeout) {
       return;
     }
diff --git a/node_package/src/streamServerRenderedReactComponent.ts b/node_package/src/streamServerRenderedReactComponent.ts
index c681bb7999..dccfe35ea7 100644
--- a/node_package/src/streamServerRenderedReactComponent.ts
+++ b/node_package/src/streamServerRenderedReactComponent.ts
@@ -88,22 +88,12 @@ export const transformRenderStreamChunksToResultObject = (renderState: StreamRen
   const consoleHistory = console.history;
   let previouslyReplayedConsoleMessages = 0;
 
-  let consoleReplayTimeoutId: NodeJS.Timeout;
-  const buildConsoleReplayChunk = () => {
-    const consoleReplayScript = buildConsoleReplay(consoleHistory, previouslyReplayedConsoleMessages);
-    previouslyReplayedConsoleMessages = consoleHistory?.length || 0;
-    if (consoleReplayScript.length === 0) {
-      return null;
-    }
-    const consoleReplayJsonChunk = JSON.stringify(createResultObject('', consoleReplayScript, renderState));
-    return consoleReplayJsonChunk;
-  };
-
   const transformStream = new PassThrough({
-    transform(chunk, _, callback) {
-      // eslint-disable-next-line @typescript-eslint/no-unsafe-call,@typescript-eslint/no-unsafe-member-access
-      const htmlChunk = chunk.toString() as string;
-      const jsonChunk = JSON.stringify(createResultObject(htmlChunk, '', renderState));
+    transform(chunk: Buffer, _, callback) {
+      const htmlChunk = chunk.toString();
+      const consoleReplayScript = buildConsoleReplay(consoleHistory, previouslyReplayedConsoleMessages);
+      previouslyReplayedConsoleMessages = consoleHistory?.length || 0;
+      const jsonChunk = JSON.stringify(createResultObject(htmlChunk, consoleReplayScript, renderState));
       this.push(`${jsonChunk}\n`);
 
       // Reset the render state to ensure that the error is not carried over to the next chunk
@@ -112,23 +102,6 @@ export const transformRenderStreamChunksToResultObject = (renderState: StreamRen
       // eslint-disable-next-line no-param-reassign
       renderState.hasErrors = false;
 
-      clearTimeout(consoleReplayTimeoutId);
-      consoleReplayTimeoutId = setTimeout(() => {
-        const consoleReplayChunk = buildConsoleReplayChunk();
-        if (consoleReplayChunk) {
-          this.push(`${consoleReplayChunk}\n`);
-        }
-      }, 0);
-
-      callback();
-    },
-
-    flush(callback) {
-      clearTimeout(consoleReplayTimeoutId);
-      const consoleReplayChunk = buildConsoleReplayChunk();
-      if (consoleReplayChunk) {
-        this.push(`${consoleReplayChunk}\n`);
-      }
       callback();
     },
   });
diff --git a/node_package/src/wrapServerComponentRenderer/client.tsx b/node_package/src/wrapServerComponentRenderer/client.tsx
index 1937f7a624..ff8b4b9e8e 100644
--- a/node_package/src/wrapServerComponentRenderer/client.tsx
+++ b/node_package/src/wrapServerComponentRenderer/client.tsx
@@ -47,9 +47,9 @@ const WrapServerComponentRenderer = (componentOrRenderFunction: ReactComponentOr
       throw new Error(`RSCClientRoot: No DOM node found for id: ${domNodeId}`);
     }
     if (domNode.innerHTML) {
-      ReactDOMClient.hydrateRoot(domNode, root);
+      ReactDOMClient.hydrateRoot(domNode, root, { identifierPrefix: domNodeId });
     } else {
-      ReactDOMClient.createRoot(domNode).render(root);
+      ReactDOMClient.createRoot(domNode, { identifierPrefix: domNodeId }).render(root);
     }
     // Added only to satisfy the return type of RenderFunction
     // However, the returned value of renderFunction is not used in ReactOnRails
diff --git a/node_package/tests/SuspenseHydration.test.tsx b/node_package/tests/SuspenseHydration.test.tsx
index 64b4258300..a9870418cf 100644
--- a/node_package/tests/SuspenseHydration.test.tsx
+++ b/node_package/tests/SuspenseHydration.test.tsx
@@ -45,6 +45,7 @@ const AsyncComponentContainer = ({
   });
   return (
     <Suspense fallback={<div>Loading...</div>}>
+      {/* @ts-expect-error - This is a test */}
       <AsyncComponent promise={promise} onRendered={onAsyncComponentRendered} />
     </Suspense>
   );

From bbc3d8532018943120d6216bf892328639132473 Mon Sep 17 00:00:00 2001
From: Abanoub Ghadban <abanoub@shakacode.com>
Date: Sat, 3 May 2025 16:35:12 +0300
Subject: [PATCH 18/50] fix failing jest tests

---
 node_package/tests/SuspenseHydration.test.tsx     |  1 -
 node_package/tests/injectRSCPayload.test.ts       | 15 +++++++++------
 .../streamServerRenderedReactComponent.test.jsx   |  6 +++---
 3 files changed, 12 insertions(+), 10 deletions(-)

diff --git a/node_package/tests/SuspenseHydration.test.tsx b/node_package/tests/SuspenseHydration.test.tsx
index a9870418cf..64b4258300 100644
--- a/node_package/tests/SuspenseHydration.test.tsx
+++ b/node_package/tests/SuspenseHydration.test.tsx
@@ -45,7 +45,6 @@ const AsyncComponentContainer = ({
   });
   return (
     <Suspense fallback={<div>Loading...</div>}>
-      {/* @ts-expect-error - This is a test */}
       <AsyncComponent promise={promise} onRendered={onAsyncComponentRendered} />
     </Suspense>
   );
diff --git a/node_package/tests/injectRSCPayload.test.ts b/node_package/tests/injectRSCPayload.test.ts
index 5a47c50cf3..c792d03203 100644
--- a/node_package/tests/injectRSCPayload.test.ts
+++ b/node_package/tests/injectRSCPayload.test.ts
@@ -93,8 +93,9 @@ describe('injectRSCPayload', () => {
     expect(resultStr).toEqual(
       '<html><body><div>Hello, world!</div></body></html>' +
         '<div>Next chunk</div>' +
-        `<script>((self.REACT_ON_RAILS_RSC_PAYLOADS||={})["test-{}-123"]||=[]).push("{\\"test\\": \\"data\\"}")</script>` +
-        `<script>((self.REACT_ON_RAILS_RSC_PAYLOADS||={})["test-{}-123"]||=[]).push("{\\"test\\": \\"data2\\"}")</script>`,
+        '<script>(self.REACT_ON_RAILS_RSC_PAYLOADS||={})["test-{}-123"]||=[]</script>' +
+        '<script>((self.REACT_ON_RAILS_RSC_PAYLOADS||={})["test-{}-123"]||=[]).push("{\\"test\\": \\"data\\"}")</script>' +
+        '<script>((self.REACT_ON_RAILS_RSC_PAYLOADS||={})["test-{}-123"]||=[]).push("{\\"test\\": \\"data2\\"}")</script>',
     );
   });
 
@@ -111,8 +112,9 @@ describe('injectRSCPayload', () => {
 
     expect(resultStr).toEqual(
       '<html><body><div>Hello, world!</div></body></html>' +
-        `<script>((self.REACT_ON_RAILS_RSC_PAYLOADS||={})["test-{}-123"]||=[]).push("{\\"test\\": \\"data\\"}")</script>` +
-        `<script>((self.REACT_ON_RAILS_RSC_PAYLOADS||={})["test-{}-123"]||=[]).push("{\\"test\\": \\"data2\\"}")</script>` +
+        '<script>(self.REACT_ON_RAILS_RSC_PAYLOADS||={})["test-{}-123"]||=[]</script>' +
+        '<script>((self.REACT_ON_RAILS_RSC_PAYLOADS||={})["test-{}-123"]||=[]).push("{\\"test\\": \\"data\\"}")</script>' +
+        '<script>((self.REACT_ON_RAILS_RSC_PAYLOADS||={})["test-{}-123"]||=[]).push("{\\"test\\": \\"data2\\"}")</script>' +
         '<div>Next chunk</div>',
     );
   });
@@ -134,8 +136,9 @@ describe('injectRSCPayload', () => {
     expect(resultStr).toEqual(
       '<html><body><div>Hello, world!</div></body></html>' +
         '<div>Next chunk</div>' +
-        `<script>((self.REACT_ON_RAILS_RSC_PAYLOADS||={})["test-{}-123"]||=[]).push("{\\"test\\": \\"data\\"}")</script>` +
-        `<script>((self.REACT_ON_RAILS_RSC_PAYLOADS||={})["test-{}-123"]||=[]).push("{\\"test\\": \\"data2\\"}")</script>` +
+        '<script>(self.REACT_ON_RAILS_RSC_PAYLOADS||={})["test-{}-123"]||=[]</script>' +
+        '<script>((self.REACT_ON_RAILS_RSC_PAYLOADS||={})["test-{}-123"]||=[]).push("{\\"test\\": \\"data\\"}")</script>' +
+        '<script>((self.REACT_ON_RAILS_RSC_PAYLOADS||={})["test-{}-123"]||=[]).push("{\\"test\\": \\"data2\\"}")</script>' +
         '<div>Third chunk</div>',
     );
   });
diff --git a/node_package/tests/streamServerRenderedReactComponent.test.jsx b/node_package/tests/streamServerRenderedReactComponent.test.jsx
index 68cbbc5852..6a20658339 100644
--- a/node_package/tests/streamServerRenderedReactComponent.test.jsx
+++ b/node_package/tests/streamServerRenderedReactComponent.test.jsx
@@ -10,7 +10,7 @@ import ReactOnRails from '../src/ReactOnRails.node.ts';
 
 const AsyncContent = async ({ throwAsyncError }) => {
   await new Promise((resolve) => {
-    setTimeout(resolve, 0);
+    setTimeout(resolve, 10);
   });
   if (throwAsyncError) {
     throw new Error('Async Error');
@@ -176,7 +176,7 @@ describe('streamServerRenderedReactComponent', () => {
     });
 
     expect(onError).toHaveBeenCalled();
-    expect(chunks.length).toBeGreaterThanOrEqual(2);
+    expect(chunks).toHaveLength(2);
     expect(chunks[0].html).toContain('Header In The Shell');
     expect(chunks[0].consoleReplayScript).toBe('');
     expect(chunks[0].isShellReady).toBe(true);
@@ -188,7 +188,7 @@ describe('streamServerRenderedReactComponent', () => {
     // One of the chunks should have a hasErrors property of true
     expect(chunks[0].hasErrors || chunks[1].hasErrors).toBe(true);
     expect(chunks[0].hasErrors && chunks[1].hasErrors).toBe(false);
-  });
+  }, 100000);
 
   it("doesn't emit an error if there is an error in the async content and throwJsErrors is false", async () => {
     const { renderResult, chunks } = setupStreamTest({ throwAsyncError: true, throwJsErrors: false });

From 51d5c97eadd83e2aa274e287a706fee1d1ec5e64 Mon Sep 17 00:00:00 2001
From: Abanoub Ghadban <abanoub@shakacode.com>
Date: Sat, 3 May 2025 17:02:49 +0300
Subject: [PATCH 19/50] add TypeScript ignore comment in SuspenseHydration test
 for Node 18+ compatibility

---
 node_package/tests/SuspenseHydration.test.tsx | 99 ++++++++++---------
 1 file changed, 54 insertions(+), 45 deletions(-)

diff --git a/node_package/tests/SuspenseHydration.test.tsx b/node_package/tests/SuspenseHydration.test.tsx
index 64b4258300..b25a9f4b70 100644
--- a/node_package/tests/SuspenseHydration.test.tsx
+++ b/node_package/tests/SuspenseHydration.test.tsx
@@ -2,8 +2,13 @@ import * as React from 'react';
 import { Suspense } from 'react';
 import { renderToReadableStream } from 'react-dom/server';
 import { hydrateRoot } from 'react-dom/client';
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore - TypeScript error can be ignored because:
+// 1. This test file is only executed when Node version >= 18
+// 2. The package is guaranteed to be available at runtime in Node 18+ environments
 import { screen, act, waitFor } from '@testing-library/react';
 import '@testing-library/jest-dom';
+import { getNodeVersion } from './testUtils.js';
 
 /**
  * Tests React's Suspense hydration behavior for async components
@@ -147,55 +152,59 @@ async function renderAndHydrate() {
   };
 }
 
-beforeEach(() => {
-  jest.clearAllMocks();
-  document.body.innerHTML = '';
-});
-
-it('hydrates the container when its content is written to the document', async () => {
-  const { onContainerHydrated, onAsyncComponentHydrated, writeFirstChunk, hydrate } =
-    await renderAndHydrate();
-
-  await act(async () => {
-    hydrate();
-    await writeFirstChunk();
-  });
-  await waitFor(() => {
-    expect(screen.queryByText('Loading...')).toBeInTheDocument();
-  });
-  expect(onContainerHydrated).toHaveBeenCalled();
-
-  // The async component is not hydrated until the second chunk is written to the document
-  await new Promise((resolve) => {
-    setTimeout(resolve, 1000);
+// React Server Components tests are compatible with React 19
+// That only run with node version 18 and above
+(getNodeVersion() >= 18 ? describe : describe.skip)('RSCClientRoot', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    document.body.innerHTML = '';
   });
-  expect(onAsyncComponentHydrated).not.toHaveBeenCalled();
-  expect(screen.queryByText('Loading...')).toBeInTheDocument();
-  expect(screen.queryByText('Hello World')).not.toBeInTheDocument();
-});
-
-it('hydrates the container when its content is written to the document', async () => {
-  const { writeFirstChunk, writeSecondChunk, onAsyncComponentHydrated, onContainerHydrated, hydrate } =
-    await renderAndHydrate();
 
-  await act(async () => {
-    hydrate();
-    await writeFirstChunk();
-  });
-  await waitFor(() => {
+  it('hydrates the container when its content is written to the document', async () => {
+    const { onContainerHydrated, onAsyncComponentHydrated, writeFirstChunk, hydrate } =
+      await renderAndHydrate();
+
+    await act(async () => {
+      hydrate();
+      await writeFirstChunk();
+    });
+    await waitFor(() => {
+      expect(screen.queryByText('Loading...')).toBeInTheDocument();
+    });
+    expect(onContainerHydrated).toHaveBeenCalled();
+
+    // The async component is not hydrated until the second chunk is written to the document
+    await new Promise((resolve) => {
+      setTimeout(resolve, 1000);
+    });
+    expect(onAsyncComponentHydrated).not.toHaveBeenCalled();
     expect(screen.queryByText('Loading...')).toBeInTheDocument();
+    expect(screen.queryByText('Hello World')).not.toBeInTheDocument();
   });
 
-  await act(async () => {
-    const secondChunk = await writeSecondChunk();
-    expect(secondChunk).toContain('script');
-    console.log(secondChunk);
-  });
-  await waitFor(() => {
-    expect(screen.queryByText('Loading...')).not.toBeInTheDocument();
-    expect(screen.queryByText('Hello World')).toBeInTheDocument();
+  it('hydrates the container when its content is written to the document', async () => {
+    const { writeFirstChunk, writeSecondChunk, onAsyncComponentHydrated, onContainerHydrated, hydrate } =
+      await renderAndHydrate();
+
+    await act(async () => {
+      hydrate();
+      await writeFirstChunk();
+    });
+    await waitFor(() => {
+      expect(screen.queryByText('Loading...')).toBeInTheDocument();
+    });
+
+    await act(async () => {
+      const secondChunk = await writeSecondChunk();
+      expect(secondChunk).toContain('script');
+      console.log(secondChunk);
+    });
+    await waitFor(() => {
+      expect(screen.queryByText('Loading...')).not.toBeInTheDocument();
+      expect(screen.queryByText('Hello World')).toBeInTheDocument();
+    });
+
+    expect(onContainerHydrated).toHaveBeenCalled();
+    expect(onAsyncComponentHydrated).toHaveBeenCalled();
   });
-
-  expect(onContainerHydrated).toHaveBeenCalled();
-  expect(onAsyncComponentHydrated).toHaveBeenCalled();
 });

From f898d5c425ca7324f7c8e36c14523682961571c8 Mon Sep 17 00:00:00 2001
From: Abanoub Ghadban <abanoub@shakacode.com>
Date: Sun, 4 May 2025 10:38:45 +0300
Subject: [PATCH 20/50] remove options parameter from registerServerComponent
 and update related tests

---
 lib/react_on_rails/packs_generator.rb              |  6 +-----
 .../src/registerServerComponent/client.tsx         |  8 +++-----
 node_package/src/types/index.ts                    |  4 ----
 .../tests/registerServerComponent.client.test.jsx  |  4 ++--
 spec/dummy/spec/packs_generator_spec.rb            | 14 ++++----------
 5 files changed, 10 insertions(+), 26 deletions(-)

diff --git a/lib/react_on_rails/packs_generator.rb b/lib/react_on_rails/packs_generator.rb
index ae4169162f..883c860a5f 100644
--- a/lib/react_on_rails/packs_generator.rb
+++ b/lib/react_on_rails/packs_generator.rb
@@ -93,14 +93,10 @@ def pack_file_contents(file_path)
                                ReactOnRailsPro.configuration.enable_rsc_support
 
       if load_server_components && !client_entrypoint?(file_path)
-        rsc_payload_generation_url_path = ReactOnRailsPro.configuration.rsc_payload_generation_url_path
-
         return <<~FILE_CONTENT.strip
           import registerServerComponent from 'react-on-rails/registerServerComponent/client';
 
-          registerServerComponent({
-            rscPayloadGenerationUrlPath: "#{rsc_payload_generation_url_path}",
-          }, "#{registered_component_name}")
+          registerServerComponent("#{registered_component_name}");
         FILE_CONTENT
       end
 
diff --git a/node_package/src/registerServerComponent/client.tsx b/node_package/src/registerServerComponent/client.tsx
index fe7d1a4ef5..469c11fe3d 100644
--- a/node_package/src/registerServerComponent/client.tsx
+++ b/node_package/src/registerServerComponent/client.tsx
@@ -1,7 +1,7 @@
 import * as React from 'react';
 import ReactOnRails from '../ReactOnRails.client.ts';
 import RSCRoute from '../RSCRoute.ts';
-import { ReactComponentOrRenderFunction, RegisterServerComponentOptions } from '../types/index.ts';
+import { ReactComponentOrRenderFunction } from '../types/index.ts';
 import WrapServerComponentRenderer from '../wrapServerComponentRenderer/client.tsx';
 
 /**
@@ -29,14 +29,12 @@ import WrapServerComponentRenderer from '../wrapServerComponentRenderer/client.t
  *
  * @example
  * ```js
- * registerServerComponent({
- *   rscPayloadGenerationUrlPath: '/rsc_payload'
- * }, 'ServerComponent1', 'ServerComponent2');
+ * registerServerComponent('ServerComponent1', 'ServerComponent2');
  *
  * // When ServerComponent1 renders, it will fetch from: /rsc_payload/ServerComponent1
  * ```
  */
-const registerServerComponent = (options: RegisterServerComponentOptions, ...componentNames: string[]) => {
+const registerServerComponent = (...componentNames: string[]) => {
   const componentsWrappedInRSCRoute: Record<string, ReactComponentOrRenderFunction> = {};
   for (const name of componentNames) {
     componentsWrappedInRSCRoute[name] = WrapServerComponentRenderer((props: unknown) => (
diff --git a/node_package/src/types/index.ts b/node_package/src/types/index.ts
index 4eea37d89d..b755678621 100644
--- a/node_package/src/types/index.ts
+++ b/node_package/src/types/index.ts
@@ -162,10 +162,6 @@ export interface RegisteredComponent {
   isRenderer: boolean;
 }
 
-export interface RegisterServerComponentOptions {
-  rscPayloadGenerationUrlPath: string;
-}
-
 export type ItemRegistrationCallback<T> = (component: T) => void;
 
 interface Params {
diff --git a/node_package/tests/registerServerComponent.client.test.jsx b/node_package/tests/registerServerComponent.client.test.jsx
index 47b6922e46..70a209fe1f 100644
--- a/node_package/tests/registerServerComponent.client.test.jsx
+++ b/node_package/tests/registerServerComponent.client.test.jsx
@@ -62,7 +62,7 @@ enableFetchMocks();
     const { stream, push } = createNodeReadableStream();
     window.fetchMock.mockResolvedValue(new Response(stream));
 
-    registerServerComponent({}, 'TestComponent');
+    registerServerComponent('TestComponent');
     const railsContext = {
       rscPayloadGenerationUrl: rscPayloadGenerationUrlPath,
       componentSpecificMetadata: {
@@ -172,7 +172,7 @@ enableFetchMocks();
       chunk1 = JSON.stringify(JSON.parse(fs.readFileSync(path.join(chunksDirectory, 'chunk1.json'), 'utf8')));
       chunk2 = JSON.stringify(JSON.parse(fs.readFileSync(path.join(chunksDirectory, 'chunk2.json'), 'utf8')));
 
-      registerServerComponent({}, 'TestComponent');
+      registerServerComponent('TestComponent');
       railsContext = {
         rscPayloadGenerationUrl: 'rsc-render',
         componentSpecificMetadata: {
diff --git a/spec/dummy/spec/packs_generator_spec.rb b/spec/dummy/spec/packs_generator_spec.rb
index 29331470a3..6322c2d974 100644
--- a/spec/dummy/spec/packs_generator_spec.rb
+++ b/spec/dummy/spec/packs_generator_spec.rb
@@ -24,7 +24,7 @@ module ReactOnRails
     before do
       stub_const("ReactOnRailsPro", Class.new do
         def self.configuration
-          @configuration ||= Struct.new(:enable_rsc_support, :rsc_payload_generation_url_path).new(false, nil)
+          @configuration ||= Struct.new(:enable_rsc_support).new(false)
         end
       end)
       ReactOnRails.configuration.server_bundle_js_file = server_bundle_js_file
@@ -216,15 +216,13 @@ def self.configuration
 
     context "when RSC support is enabled" do
       let(:components_directory) { "ReactServerComponents" }
-      let(:rsc_payload_generation_url_path) { "/rsc" }
 
       before do
         stub_packer_source_path(component_name: components_directory,
                                 packer_source_path: packer_source_path)
         allow(ReactOnRails::Utils).to receive(:react_on_rails_pro?).and_return(true)
         allow(ReactOnRailsPro.configuration).to receive_messages(
-          enable_rsc_support: true,
-          rsc_payload_generation_url_path: rsc_payload_generation_url_path
+          enable_rsc_support: true
         )
       end
 
@@ -240,9 +238,7 @@ def self.configuration
           expected_content = <<~CONTENT.strip
             import registerServerComponent from 'react-on-rails/registerServerComponent/client';
 
-            registerServerComponent({
-              rscPayloadGenerationUrlPath: "#{rsc_payload_generation_url_path}",
-            }, "#{component_name}")
+            registerServerComponent("#{component_name}");
           CONTENT
 
           expect(pack_content).to eq(expected_content)
@@ -276,9 +272,7 @@ def self.configuration
           expected_content = <<~CONTENT.strip
             import registerServerComponent from 'react-on-rails/registerServerComponent/client';
 
-            registerServerComponent({
-              rscPayloadGenerationUrlPath: "#{rsc_payload_generation_url_path}",
-            }, "#{component_name}")
+            registerServerComponent("#{component_name}");
           CONTENT
 
           expect(pack_content).to eq(expected_content)

From d45c30e2e6962c6ae07fcf1ae1ba44d79bfaa5e1 Mon Sep 17 00:00:00 2001
From: Abanoub Ghadban <abanoub@shakacode.com>
Date: Sun, 4 May 2025 10:46:26 +0300
Subject: [PATCH 21/50] refactor: rename WrapServerComponentRenderer to
 wrapServerComponentRenderer

---
 node_package/src/registerServerComponent/client.tsx       | 4 ++--
 node_package/src/registerServerComponent/server.tsx       | 4 ++--
 node_package/src/wrapServerComponentRenderer/client.tsx   | 8 ++++----
 .../src/wrapServerComponentRenderer/server.rsc.tsx        | 4 ++--
 node_package/src/wrapServerComponentRenderer/server.tsx   | 8 ++++----
 5 files changed, 14 insertions(+), 14 deletions(-)

diff --git a/node_package/src/registerServerComponent/client.tsx b/node_package/src/registerServerComponent/client.tsx
index 469c11fe3d..1da74ca705 100644
--- a/node_package/src/registerServerComponent/client.tsx
+++ b/node_package/src/registerServerComponent/client.tsx
@@ -2,7 +2,7 @@ import * as React from 'react';
 import ReactOnRails from '../ReactOnRails.client.ts';
 import RSCRoute from '../RSCRoute.ts';
 import { ReactComponentOrRenderFunction } from '../types/index.ts';
-import WrapServerComponentRenderer from '../wrapServerComponentRenderer/client.tsx';
+import wrapServerComponentRenderer from '../wrapServerComponentRenderer/client.tsx';
 
 /**
  * Registers React Server Components (RSC) with React on Rails.
@@ -37,7 +37,7 @@ import WrapServerComponentRenderer from '../wrapServerComponentRenderer/client.t
 const registerServerComponent = (...componentNames: string[]) => {
   const componentsWrappedInRSCRoute: Record<string, ReactComponentOrRenderFunction> = {};
   for (const name of componentNames) {
-    componentsWrappedInRSCRoute[name] = WrapServerComponentRenderer((props: unknown) => (
+    componentsWrappedInRSCRoute[name] = wrapServerComponentRenderer((props: unknown) => (
       <RSCRoute componentName={name} componentProps={props} />
     ));
   }
diff --git a/node_package/src/registerServerComponent/server.tsx b/node_package/src/registerServerComponent/server.tsx
index 71a7466e25..750cc43d1b 100644
--- a/node_package/src/registerServerComponent/server.tsx
+++ b/node_package/src/registerServerComponent/server.tsx
@@ -2,7 +2,7 @@ import * as React from 'react';
 import ReactOnRails from '../ReactOnRails.client.ts';
 import RSCRoute from '../RSCRoute.ts';
 import { ReactComponent, RenderFunction } from '../types/index.ts';
-import WrapServerComponentRenderer from '../wrapServerComponentRenderer/server.tsx';
+import wrapServerComponentRenderer from '../wrapServerComponentRenderer/server.tsx';
 
 /**
  * Registers React Server Components (RSC) with React on Rails for the server bundle.
@@ -28,7 +28,7 @@ import WrapServerComponentRenderer from '../wrapServerComponentRenderer/server.t
 const registerServerComponent = (components: Record<string, ReactComponent>) => {
   const componentsWrappedInRSCRoute: Record<string, RenderFunction> = {};
   for (const [componentName] of Object.entries(components)) {
-    componentsWrappedInRSCRoute[componentName] = WrapServerComponentRenderer((props: unknown) => (
+    componentsWrappedInRSCRoute[componentName] = wrapServerComponentRenderer((props: unknown) => (
       <RSCRoute componentName={componentName} componentProps={props} />
     ));
   }
diff --git a/node_package/src/wrapServerComponentRenderer/client.tsx b/node_package/src/wrapServerComponentRenderer/client.tsx
index ff8b4b9e8e..a3a9cadf62 100644
--- a/node_package/src/wrapServerComponentRenderer/client.tsx
+++ b/node_package/src/wrapServerComponentRenderer/client.tsx
@@ -8,9 +8,9 @@ import getReactServerComponent from '../getReactServerComponent.client.ts';
 
 ensureReactUseAvailable();
 
-const WrapServerComponentRenderer = (componentOrRenderFunction: ReactComponentOrRenderFunction) => {
+const wrapServerComponentRenderer = (componentOrRenderFunction: ReactComponentOrRenderFunction) => {
   if (typeof componentOrRenderFunction !== 'function') {
-    throw new Error('WrapServerComponentRenderer: component is not a function');
+    throw new Error('wrapServerComponentRenderer: component is not a function');
   }
 
   const wrapper: RenderFunction = async (props, railsContext, domNodeId) => {
@@ -19,7 +19,7 @@ const WrapServerComponentRenderer = (componentOrRenderFunction: ReactComponentOr
       : componentOrRenderFunction;
 
     if (typeof Component !== 'function') {
-      throw new Error('WrapServerComponentRenderer: component is not a function');
+      throw new Error('wrapServerComponentRenderer: component is not a function');
     }
 
     if (!railsContext) {
@@ -60,4 +60,4 @@ const WrapServerComponentRenderer = (componentOrRenderFunction: ReactComponentOr
   return wrapper;
 };
 
-export default WrapServerComponentRenderer;
+export default wrapServerComponentRenderer;
diff --git a/node_package/src/wrapServerComponentRenderer/server.rsc.tsx b/node_package/src/wrapServerComponentRenderer/server.rsc.tsx
index d5d05124ce..2da98f23fc 100644
--- a/node_package/src/wrapServerComponentRenderer/server.rsc.tsx
+++ b/node_package/src/wrapServerComponentRenderer/server.rsc.tsx
@@ -1,6 +1,6 @@
-const WrapServerComponentRenderer = () => {
+const wrapServerComponentRenderer = () => {
   // Do nothing
   // Server component renderers are client components and not needed in the RSC bundle
 };
 
-export default WrapServerComponentRenderer;
+export default wrapServerComponentRenderer;
diff --git a/node_package/src/wrapServerComponentRenderer/server.tsx b/node_package/src/wrapServerComponentRenderer/server.tsx
index 467aed8ab0..b0fe47b25a 100644
--- a/node_package/src/wrapServerComponentRenderer/server.tsx
+++ b/node_package/src/wrapServerComponentRenderer/server.tsx
@@ -4,9 +4,9 @@ import getReactServerComponent from '../getReactServerComponent.server.ts';
 import { createRSCProvider } from '../RSCProvider.tsx';
 import isRenderFunction from '../isRenderFunction.ts';
 
-const WrapServerComponentRenderer = (componentOrRenderFunction: ReactComponentOrRenderFunction) => {
+const wrapServerComponentRenderer = (componentOrRenderFunction: ReactComponentOrRenderFunction) => {
   if (typeof componentOrRenderFunction !== 'function') {
-    throw new Error('WrapServerComponentRenderer: component is not a function');
+    throw new Error('wrapServerComponentRenderer: component is not a function');
   }
 
   const wrapper: RenderFunction = async (props, railsContext) => {
@@ -19,7 +19,7 @@ const WrapServerComponentRenderer = (componentOrRenderFunction: ReactComponentOr
       : componentOrRenderFunction;
 
     if (typeof Component !== 'function') {
-      throw new Error('WrapServerComponentRenderer: component is not a function');
+      throw new Error('wrapServerComponentRenderer: component is not a function');
     }
 
     const RSCProvider = createRSCProvider({
@@ -41,4 +41,4 @@ const WrapServerComponentRenderer = (componentOrRenderFunction: ReactComponentOr
   return wrapper;
 };
 
-export default WrapServerComponentRenderer;
+export default wrapServerComponentRenderer;

From 8d313aad3dfae94624c0b0cd83242e30171f0300 Mon Sep 17 00:00:00 2001
From: Abanoub Ghadban <abanoub@shakacode.com>
Date: Sun, 4 May 2025 15:47:51 +0300
Subject: [PATCH 22/50] docs: add detailed JSDoc comments for RSC functions and
 utilities to improve code clarity and maintainability

---
 node_package/src/RSCPayloadGenerator.ts       | 36 ++++++++++---
 node_package/src/RSCProvider.tsx              | 38 ++++++++++++++
 node_package/src/RSCRoute.ts                  | 22 ++++++++
 .../src/getReactServerComponent.client.ts     | 50 +++++++++++++++++++
 .../src/getReactServerComponent.server.ts     | 38 ++++++++++++++
 node_package/src/injectRSCPayload.ts          | 18 +++++++
 .../src/registerServerComponent/server.rsc.ts | 10 ++--
 .../src/registerServerComponent/server.tsx    | 13 ++---
 node_package/src/transformRSCNodeStream.ts    | 14 ++++++
 .../transformRSCStreamAndReplayConsoleLogs.ts | 14 ++++++
 .../wrapServerComponentRenderer/client.tsx    | 19 +++++++
 .../wrapServerComponentRenderer/server.tsx    | 19 +++++++
 12 files changed, 272 insertions(+), 19 deletions(-)

diff --git a/node_package/src/RSCPayloadGenerator.ts b/node_package/src/RSCPayloadGenerator.ts
index acb7733bd3..0b7d17983a 100644
--- a/node_package/src/RSCPayloadGenerator.ts
+++ b/node_package/src/RSCPayloadGenerator.ts
@@ -13,12 +13,20 @@ const mapRailsContextToRSCPayloadStreams = new Map<RailsContext, RSCPayloadStrea
 
 const rscPayloadCallbacks = new Map<RailsContext, Array<RSCPayloadCallback>>();
 
-// The RSC payload callbacks must be executed synchronously to maintain proper hydration timing.
-// This ensures that the RSC payload initialization script is injected into the HTML page
-// before the corresponding component's HTML markup appears. This timing is critical because:
-// 1. Client-side components only hydrate after their HTML is present in the page
-// 2. The RSC payload must be available before hydration begins to prevent unnecessary refetching
-// 3. Using setTimeout(callback, 0) would break this synchronization and could lead to hydration issues
+/**
+ * Registers a callback to be executed when RSC payloads are generated.
+ *
+ * This function:
+ * 1. Stores the callback function by railsContext
+ * 2. Immediately executes the callback for any existing streams
+ *
+ * This synchronous execution is critical for preventing hydration race conditions.
+ * It ensures payload array initialization happens before component HTML appears
+ * in the response stream.
+ *
+ * @param railsContext - Context for the current request
+ * @param callback - Function to call when an RSC payload is generated
+ */
 export const onRSCPayloadGenerated = (railsContext: RailsContext, callback: RSCPayloadCallback) => {
   const callbacks = rscPayloadCallbacks.get(railsContext) || [];
   callbacks.push(callback);
@@ -29,6 +37,22 @@ export const onRSCPayloadGenerated = (railsContext: RailsContext, callback: RSCP
   existingStreams.forEach((streamInfo) => callback(streamInfo));
 };
 
+/**
+ * Generates and tracks RSC payloads for server components.
+ *
+ * getRSCPayloadStream:
+ * 1. Calls the global generateRSCPayload function
+ * 2. Tracks streams by railsContext for later injection
+ * 3. Notifies callbacks immediately to enable early payload embedding
+ *
+ * The immediate callback notification is critical for preventing hydration race conditions,
+ * as it ensures the payload array is initialized in the HTML stream before component rendering.
+ *
+ * @param componentName - Name of the server component
+ * @param props - Props for the server component
+ * @param railsContext - Context for the current request
+ * @returns A stream of the RSC payload
+ */
 export const getRSCPayloadStream = async (
   componentName: string,
   props: unknown,
diff --git a/node_package/src/RSCProvider.tsx b/node_package/src/RSCProvider.tsx
index a0b3e59355..2e9bff34e3 100644
--- a/node_package/src/RSCProvider.tsx
+++ b/node_package/src/RSCProvider.tsx
@@ -10,6 +10,25 @@ type RSCContextType = {
 
 const RSCContext = React.createContext<RSCContextType | undefined>(undefined);
 
+/**
+ * Creates a provider context for React Server Components.
+ *
+ * RSCProvider is a foundational component that:
+ * 1. Provides caching for server components to prevent redundant requests
+ * 2. Manages the fetching of server components through getComponent
+ * 3. Offers environment-agnostic access to server components
+ *
+ * This factory function accepts an environment-specific getServerComponent implementation,
+ * allowing it to work correctly in both client and server environments.
+ *
+ * @param railsContext - Context for the current request
+ * @param getServerComponent - Environment-specific function for fetching server components
+ * @returns A provider component that wraps children with RSC context
+ *
+ * @important This is an internal function. End users should not use this directly.
+ * Instead, use wrapServerComponentRenderer from 'react-on-rails/wrapServerComponentRenderer/client'
+ * for client-side rendering or 'react-on-rails/wrapServerComponentRenderer/server' for server-side rendering.
+ */
 export const createRSCProvider = ({
   railsContext,
   getServerComponent,
@@ -53,6 +72,25 @@ export const createRSCProvider = ({
   };
 };
 
+/**
+ * Hook to access the RSC context within client components.
+ *
+ * This hook provides access to:
+ * - getCachedComponent: For retrieving already rendered server components
+ * - getComponent: For fetching and rendering server components
+ *
+ * It must be used within a component wrapped by RSCProvider (typically done
+ * automatically by wrapServerComponentRenderer).
+ *
+ * @returns The RSC context containing methods for working with server components
+ * @throws Error if used outside of an RSCProvider
+ *
+ * @example
+ * ```tsx
+ * const { getComponent } = useRSC();
+ * const serverComponent = React.use(getComponent('MyServerComponent', props));
+ * ```
+ */
 export const useRSC = () => {
   const context = React.useContext(RSCContext);
   if (!context) {
diff --git a/node_package/src/RSCRoute.ts b/node_package/src/RSCRoute.ts
index 6e9e632ffd..c82328f2b8 100644
--- a/node_package/src/RSCRoute.ts
+++ b/node_package/src/RSCRoute.ts
@@ -1,6 +1,28 @@
 import * as React from 'react';
 import { useRSC } from './RSCProvider.tsx';
 
+/**
+ * Renders a React Server Component inside a React Client Component.
+ *
+ * RSCRoute provides a bridge between client and server components, allowing server components
+ * to be directly rendered inside client components. This component:
+ *
+ * 1. During initial SSR - Uses the RSC payload to render the server component and embeds the payload in the page
+ * 2. During hydration - Uses the embedded RSC payload already in the page
+ * 3. During client navigation - Fetches the RSC payload via HTTP
+ *
+ * @example
+ * ```tsx
+ * <RSCRoute componentName="MyServerComponent" componentProps={{ user }} />
+ * ```
+ *
+ * @important Only use for server components whose props change rarely. Frequent prop changes
+ * will cause network requests for each change, impacting performance.
+ *
+ * @important This component expects that the component tree that contains it is wrapped using
+ * wrapServerComponentRenderer from 'react-on-rails/wrapServerComponentRenderer/client' for client-side
+ * rendering or 'react-on-rails/wrapServerComponentRenderer/server' for server-side rendering.
+ */
 export type RSCRouteProps = {
   componentName: string;
   componentProps: unknown;
diff --git a/node_package/src/getReactServerComponent.client.ts b/node_package/src/getReactServerComponent.client.ts
index 7f6197b373..572095994e 100644
--- a/node_package/src/getReactServerComponent.client.ts
+++ b/node_package/src/getReactServerComponent.client.ts
@@ -26,6 +26,20 @@ const createFromFetch = async (fetchPromise: Promise<Response>) => {
   return createFromReadableStream<React.ReactNode>(transformedStream);
 };
 
+/**
+ * Fetches an RSC payload via HTTP request.
+ *
+ * This function:
+ * 1. Serializes the component props
+ * 2. Makes an HTTP request to the RSC payload generation endpoint
+ * 3. Processes the response stream into React elements
+ *
+ * This is used for client-side navigation or when rendering components
+ * that weren't part of the initial server render.
+ *
+ * @param props - Object containing component name, props, and railsContext
+ * @returns A Promise resolving to the rendered React element
+ */
 const fetchRSC = ({ componentName, componentProps, railsContext }: ClientGetReactServerComponentProps) => {
   const propsString = JSON.stringify(componentProps);
   const { rscPayloadGenerationUrl } = railsContext;
@@ -65,12 +79,48 @@ const createRSCStreamFromArray = (payloads: string[]) => {
   return stream;
 };
 
+/**
+ * Creates React elements from preloaded RSC payloads in the page.
+ *
+ * This function:
+ * 1. Creates a ReadableStream from the array of payload chunks
+ * 2. Transforms the stream to handle console logs and other processing
+ * 3. Uses React's createFromReadableStream to process the payload
+ *
+ * This is used during hydration to avoid making HTTP requests when
+ * the payload is already embedded in the page.
+ *
+ * @param payloads - Array of RSC payload chunks from the global array
+ * @returns A Promise resolving to the rendered React element
+ */
 const createFromPreloadedPayloads = (payloads: string[]) => {
   const stream = createRSCStreamFromArray(payloads);
   const transformedStream = transformRSCStreamAndReplayConsoleLogs(stream);
   return createFromReadableStream<React.ReactNode>(transformedStream);
 };
 
+/**
+ * Fetches and renders a server component on the client side.
+ *
+ * This function:
+ * 1. Checks for embedded RSC payloads in window.REACT_ON_RAILS_RSC_PAYLOADS
+ * 2. If found, uses the embedded payload to avoid an HTTP request
+ * 3. If not found (during client navigation or dynamic rendering), fetches via HTTP
+ * 4. Processes the RSC payload into React elements
+ *
+ * The embedded payload approach ensures optimal performance during initial page load,
+ * while the HTTP fallback enables dynamic rendering after navigation.
+ *
+ * @param componentName - Name of the server component to render
+ * @param componentProps - Props to pass to the server component
+ * @param railsContext - Context for the current request
+ * @returns A Promise resolving to the rendered React element
+ *
+ * @important This is an internal function. End users should not use this directly.
+ * Instead, use the useRSC hook which provides getComponent and getCachedComponent functions
+ * for fetching or retrieving cached server components. For rendering server components,
+ * consider using RSCRoute component which handles the rendering logic automatically.
+ */
 const getReactServerComponent = ({
   componentName,
   componentProps,
diff --git a/node_package/src/getReactServerComponent.server.ts b/node_package/src/getReactServerComponent.server.ts
index 52ce377cf0..58d1ba1dff 100644
--- a/node_package/src/getReactServerComponent.server.ts
+++ b/node_package/src/getReactServerComponent.server.ts
@@ -17,6 +17,21 @@ const createFromReactOnRailsNodeStream = (
   return createFromNodeStream(transformedStream, ssrManifest);
 };
 
+/**
+ * Creates an SSR manifest for React's server components runtime.
+ *
+ * This function:
+ * 1. Loads the server and client component manifests
+ * 2. Creates a mapping between client and server module IDs
+ * 3. Builds a moduleMap structure required by React's SSR runtime
+ *
+ * The manifest allows React to correctly associate server components
+ * with their client counterparts during hydration.
+ *
+ * @param reactServerManifestFileName - Path to the server manifest file
+ * @param reactClientManifestFileName - Path to the client manifest file
+ * @returns A Promise resolving to the SSR manifest object
+ */
 const createSSRManifest = async (
   reactServerManifestFileName: string,
   reactClientManifestFileName: string,
@@ -52,6 +67,29 @@ const createSSRManifest = async (
   return ssrManifest;
 };
 
+/**
+ * Fetches and renders a server component on the server side.
+ *
+ * This function:
+ * 1. Validates the railsContext for required properties
+ * 2. Creates an SSR manifest mapping server and client modules
+ * 3. Gets the RSC payload stream via getRSCPayloadStream
+ * 4. Processes the stream with React's SSR runtime
+ *
+ * During SSR, this function ensures that the RSC payload is both:
+ * - Used to render the server component
+ * - Tracked so it can be embedded in the HTML response
+ *
+ * @param componentName - Name of the server component to render
+ * @param componentProps - Props to pass to the server component
+ * @param railsContext - Context for the current request
+ * @returns A Promise resolving to the rendered React element
+ *
+ * @important This is an internal function. End users should not use this directly.
+ * Instead, use the useRSC hook which provides getComponent and getCachedComponent functions
+ * for fetching or retrieving cached server components. For rendering server components,
+ * consider using RSCRoute component which handles the rendering logic automatically.
+ */
 const getReactServerComponent = async ({
   componentName,
   componentProps,
diff --git a/node_package/src/injectRSCPayload.ts b/node_package/src/injectRSCPayload.ts
index 443387db1e..155c4c79b0 100644
--- a/node_package/src/injectRSCPayload.ts
+++ b/node_package/src/injectRSCPayload.ts
@@ -30,6 +30,24 @@ function writeChunk(chunk: string, transform: Transform, cacheKey: string) {
   writeScript(`(${cacheKeyJSArray(cacheKey)}).push(${chunk})`, transform);
 }
 
+/**
+ * Embeds RSC payloads into the HTML stream for optimal hydration.
+ *
+ * This function:
+ * 1. Creates a result stream for the combined HTML + RSC payloads
+ * 2. Listens for RSC payload generation via onRSCPayloadGenerated
+ * 3. Initializes global arrays for each payload BEFORE component HTML
+ * 4. Writes each payload chunk as a script tag that pushes to the array
+ * 5. Passes HTML through to the result stream
+ *
+ * The timing of array initialization is critical - it must occur before the
+ * component's HTML to ensure the array exists when client hydration begins.
+ * This prevents unnecessary HTTP requests during hydration.
+ *
+ * @param pipeableHtmlStream - HTML stream from React's renderToPipeableStream
+ * @param railsContext - Context for the current request
+ * @returns A combined stream with embedded RSC payloads
+ */
 export default function injectRSCPayload(
   pipeableHtmlStream: NodeJS.ReadableStream | PipeableStream,
   railsContext: RailsContext,
diff --git a/node_package/src/registerServerComponent/server.rsc.ts b/node_package/src/registerServerComponent/server.rsc.ts
index 694193c443..e7dea03f00 100644
--- a/node_package/src/registerServerComponent/server.rsc.ts
+++ b/node_package/src/registerServerComponent/server.rsc.ts
@@ -2,12 +2,12 @@ import ReactOnRails from '../ReactOnRails.client.ts';
 import { ReactComponent, RenderFunction } from '../types/index.ts';
 
 /**
- * Registers React Server Components (RSC) with React on Rails for the RSC bundle.
+ * Registers React Server Components in the RSC bundle.
  *
- * This function handles the registration of components in the RSC bundle context,
- * where components are registered directly into the ComponentRegistry without any
- * additional wrapping. This is different from the server bundle registration,
- * which wraps components with RSCServerRoot.
+ * Unlike the client and server implementations, the RSC bundle registration
+ * directly registers components without any wrapping. This is because the
+ * RSC bundle is responsible for generating the actual RSC payload of server
+ * components, not for rendering or hydrating client components.
  *
  * @param components - Object mapping component names to their implementations
  *
diff --git a/node_package/src/registerServerComponent/server.tsx b/node_package/src/registerServerComponent/server.tsx
index 750cc43d1b..dc24230743 100644
--- a/node_package/src/registerServerComponent/server.tsx
+++ b/node_package/src/registerServerComponent/server.tsx
@@ -5,15 +5,12 @@ import { ReactComponent, RenderFunction } from '../types/index.ts';
 import wrapServerComponentRenderer from '../wrapServerComponentRenderer/server.tsx';
 
 /**
- * Registers React Server Components (RSC) with React on Rails for the server bundle.
+ * Registers React Server Components for use in server bundles.
  *
- * This function wraps each component with RSCServerRoot, which handles the server-side
- * rendering of React Server Components using pre-generated RSC payloads.
- *
- * The RSCServerRoot component:
- * - Uses pre-generated RSC payloads from the RSC bundle
- * - Builds the rendering tree of the server component
- * - Handles the integration with React's streaming SSR
+ * This function:
+ * 1. Takes server component implementations
+ * 2. Wraps each component with RSCRoute using WrapServerComponentRenderer
+ * 3. Registers the wrapped components with ReactOnRails
  *
  * @param components - Object mapping component names to their implementations
  *
diff --git a/node_package/src/transformRSCNodeStream.ts b/node_package/src/transformRSCNodeStream.ts
index d40e103598..e26f1a44a5 100644
--- a/node_package/src/transformRSCNodeStream.ts
+++ b/node_package/src/transformRSCNodeStream.ts
@@ -1,5 +1,19 @@
 import { Transform } from 'stream';
 
+/**
+ * Transforms an RSC Node.js stream for server-side processing.
+ *
+ * This utility:
+ * 1. Takes a Node.js ReadableStream of RSC payload chunks
+ * 2. Applies necessary transformations for server-side consumption
+ * 3. Returns a modified stream that works with React's SSR runtime
+ *
+ * This is essential for proper handling of RSC payloads in Node.js
+ * environment during server-side rendering.
+ *
+ * @param stream - The Node.js RSC payload stream
+ * @returns A transformed stream compatible with React's SSR runtime
+ */
 export default function transformRSCStream(stream: NodeJS.ReadableStream): NodeJS.ReadableStream {
   const decoder = new TextDecoder();
   let lastIncompleteChunk = '';
diff --git a/node_package/src/transformRSCStreamAndReplayConsoleLogs.ts b/node_package/src/transformRSCStreamAndReplayConsoleLogs.ts
index 31d35c4f93..56af541dd5 100644
--- a/node_package/src/transformRSCStreamAndReplayConsoleLogs.ts
+++ b/node_package/src/transformRSCStreamAndReplayConsoleLogs.ts
@@ -1,5 +1,19 @@
 import { RSCPayloadChunk } from './types/index.ts';
 
+/**
+ * Transforms an RSC stream and replays console logs on the client.
+ *
+ * This utility:
+ * 1. Takes a ReadableStream of RSC payload chunks
+ * 2. Processes each chunk to extract and replay embedded console logs
+ * 3. Passes through the actual RSC payload data
+ *
+ * This improves debugging by making server-side console logs appear in
+ * the client console, maintaining a seamless development experience.
+ *
+ * @param stream - The RSC payload stream to transform
+ * @returns A transformed stream with console logs extracted and replayed
+ */
 export default function transformRSCStreamAndReplayConsoleLogs(stream: ReadableStream<Uint8Array | string>) {
   return new ReadableStream({
     async start(controller) {
diff --git a/node_package/src/wrapServerComponentRenderer/client.tsx b/node_package/src/wrapServerComponentRenderer/client.tsx
index a3a9cadf62..1cdd0b7843 100644
--- a/node_package/src/wrapServerComponentRenderer/client.tsx
+++ b/node_package/src/wrapServerComponentRenderer/client.tsx
@@ -8,6 +8,25 @@ import getReactServerComponent from '../getReactServerComponent.client.ts';
 
 ensureReactUseAvailable();
 
+/**
+ * Wraps a client component with the necessary RSC context and handling for client-side operations.
+ *
+ * This higher-order function:
+ * 1. Creates an RSCProvider with client-specific implementation of getReactServerComponent
+ * 2. Handles DOM hydration or rendering operations
+ * 3. Ensures Suspense boundaries are properly set up for async rendering
+ *
+ * Use this version specifically for client bundle registration.
+ *
+ * @param componentOrRenderFunction - Client component or render function to wrap
+ * @returns A render function that handles client-side RSC operations and DOM hydration that should be registered with ReactOnRails.register
+ *
+ * @example
+ * ```tsx
+ * const WrappedComponent = WrapServerComponentRenderer(ClientComponent);
+ * ReactOnRails.register({ ClientComponent: WrappedComponent });
+ * ```
+ */
 const wrapServerComponentRenderer = (componentOrRenderFunction: ReactComponentOrRenderFunction) => {
   if (typeof componentOrRenderFunction !== 'function') {
     throw new Error('wrapServerComponentRenderer: component is not a function');
diff --git a/node_package/src/wrapServerComponentRenderer/server.tsx b/node_package/src/wrapServerComponentRenderer/server.tsx
index b0fe47b25a..af90849d30 100644
--- a/node_package/src/wrapServerComponentRenderer/server.tsx
+++ b/node_package/src/wrapServerComponentRenderer/server.tsx
@@ -4,6 +4,25 @@ import getReactServerComponent from '../getReactServerComponent.server.ts';
 import { createRSCProvider } from '../RSCProvider.tsx';
 import isRenderFunction from '../isRenderFunction.ts';
 
+/**
+ * Wraps a client component with the necessary RSC context and handling for server-side operations.
+ *
+ * This higher-order function:
+ * 1. Creates an RSCProvider with server-specific implementation of getReactServerComponent
+ * 2. Provides a render function that returns React elements for SSR
+ * 3. Ensures Suspense boundaries are properly set up for async rendering
+ *
+ * Use this version specifically for server bundle registration.
+ *
+ * @param componentOrRenderFunction - Client component or render function to wrap
+ * @returns A render function that produces React elements for server-side rendering that should be registered with ReactOnRails.register
+ *
+ * @example
+ * ```tsx
+ * const WrappedComponent = WrapServerComponentRenderer(ClientComponent);
+ * ReactOnRails.register({ ClientComponent: WrappedComponent });
+ * ```
+ */
 const wrapServerComponentRenderer = (componentOrRenderFunction: ReactComponentOrRenderFunction) => {
   if (typeof componentOrRenderFunction !== 'function') {
     throw new Error('wrapServerComponentRenderer: component is not a function');

From d8ea131fcfea4b1b0b89ed9ae0f9a9f71df11175 Mon Sep 17 00:00:00 2001
From: Abanoub Ghadban <abanoub@shakacode.com>
Date: Sat, 10 May 2025 14:30:24 +0300
Subject: [PATCH 23/50] feat: implement post-SSR hooks for enhanced server-side
 rendering control and update package dependencies

---
 node_package/src/ReactOnRails.client.ts       |  6 ++++++
 node_package/src/ReactOnRails.node.ts         |  2 ++
 node_package/src/ReactOnRailsRSC.ts           |  9 +++++++++
 node_package/src/loadJsonFile.ts              |  8 +++++---
 node_package/src/postSSRHooks.ts              | 20 +++++++++++++++++++
 .../src/streamServerRenderedReactComponent.ts |  6 ++++++
 node_package/src/types/index.ts               | 11 ++++++++++
 7 files changed, 59 insertions(+), 3 deletions(-)
 create mode 100644 node_package/src/postSSRHooks.ts

diff --git a/node_package/src/ReactOnRails.client.ts b/node_package/src/ReactOnRails.client.ts
index 752fba1d4c..d07a911f61 100644
--- a/node_package/src/ReactOnRails.client.ts
+++ b/node_package/src/ReactOnRails.client.ts
@@ -190,6 +190,12 @@ globalThis.ReactOnRails = {
   },
 
   isRSCBundle: false,
+
+  addPostSSRHook(): void {
+    throw new Error(
+      'addPostSSRHook is not available in "react-on-rails/client". Import "react-on-rails" server-side.',
+    );
+  },
 };
 
 globalThis.ReactOnRails.resetOptions();
diff --git a/node_package/src/ReactOnRails.node.ts b/node_package/src/ReactOnRails.node.ts
index 7c6bcbe412..62562d2db0 100644
--- a/node_package/src/ReactOnRails.node.ts
+++ b/node_package/src/ReactOnRails.node.ts
@@ -6,12 +6,14 @@ import {
   clearRSCPayloadStreams,
   onRSCPayloadGenerated,
 } from './RSCPayloadGenerator.ts';
+import { addPostSSRHook } from './postSSRHooks.ts';
 
 ReactOnRails.streamServerRenderedReactComponent = streamServerRenderedReactComponent;
 ReactOnRails.getRSCPayloadStream = getRSCPayloadStream;
 ReactOnRails.getRSCPayloadStreams = getRSCPayloadStreams;
 ReactOnRails.clearRSCPayloadStreams = clearRSCPayloadStreams;
 ReactOnRails.onRSCPayloadGenerated = onRSCPayloadGenerated;
+ReactOnRails.addPostSSRHook = addPostSSRHook;
 
 export * from './ReactOnRails.full.ts';
 // eslint-disable-next-line no-restricted-exports -- see https://github.com/eslint/eslint/issues/15617
diff --git a/node_package/src/ReactOnRailsRSC.ts b/node_package/src/ReactOnRailsRSC.ts
index 08f38eb819..02263e5fc2 100644
--- a/node_package/src/ReactOnRailsRSC.ts
+++ b/node_package/src/ReactOnRailsRSC.ts
@@ -6,6 +6,7 @@ import ReactOnRails from './ReactOnRails.full.ts';
 import buildConsoleReplay from './buildConsoleReplay.ts';
 import handleError from './handleError.ts';
 import { convertToError, createResultObject } from './serverRenderUtils.ts';
+import { notifySSREnd, addPostSSRHook } from './postSSRHooks.ts';
 
 import {
   streamServerRenderedComponent,
@@ -61,6 +62,12 @@ const streamRenderRSCComponent = (
       const jsonResult = JSON.stringify(createResultObject(htmlResult, buildConsoleReplay(), renderState));
       return stringToStream(jsonResult);
     });
+
+  readableStream.on('end', () => {
+    if (options.railsContext?.componentSpecificMetadata) {
+      notifySSREnd(options.railsContext as RailsContextWithComponentSpecificMetadata);
+    }
+  });
   return readableStream;
 };
 
@@ -72,6 +79,8 @@ ReactOnRails.serverRenderRSCReactComponent = (options: RSCRenderParams) => {
   }
 };
 
+ReactOnRails.addPostSSRHook = addPostSSRHook;
+
 ReactOnRails.isRSCBundle = true;
 
 export * from './types/index.ts';
diff --git a/node_package/src/loadJsonFile.ts b/node_package/src/loadJsonFile.ts
index 2628711f94..e503d109d4 100644
--- a/node_package/src/loadJsonFile.ts
+++ b/node_package/src/loadJsonFile.ts
@@ -4,18 +4,20 @@ import * as fs from 'fs/promises';
 type LoadedJsonFile = Record<string, unknown>;
 const loadedJsonFiles = new Map<string, LoadedJsonFile>();
 
-export default async function loadJsonFile(fileName: string) {
+export default async function loadJsonFile<T extends LoadedJsonFile = LoadedJsonFile>(
+  fileName: string,
+): Promise<T> {
   // Asset JSON files are uploaded to node renderer.
   // Renderer copies assets to the same place as the server-bundle.js and rsc-bundle.js.
   // Thus, the __dirname of this code is where we can find the manifest file.
   const filePath = path.resolve(__dirname, fileName);
   const loadedJsonFile = loadedJsonFiles.get(filePath);
   if (loadedJsonFile) {
-    return loadedJsonFile;
+    return loadedJsonFile as T;
   }
 
   try {
-    const file = JSON.parse(await fs.readFile(filePath, 'utf8')) as LoadedJsonFile;
+    const file = JSON.parse(await fs.readFile(filePath, 'utf8')) as T;
     loadedJsonFiles.set(filePath, file);
     return file;
   } catch (error) {
diff --git a/node_package/src/postSSRHooks.ts b/node_package/src/postSSRHooks.ts
new file mode 100644
index 0000000000..46031062b3
--- /dev/null
+++ b/node_package/src/postSSRHooks.ts
@@ -0,0 +1,20 @@
+import { RailsContextWithComponentSpecificMetadata } from "./types/index.ts";
+
+type PostSSRHook = () => void;
+const postSSRHooks = new Map<string, PostSSRHook[]>();
+
+export const addPostSSRHook = (
+  railsContext: RailsContextWithComponentSpecificMetadata,
+  hook: PostSSRHook,
+) => {
+  const hooks = postSSRHooks.get(railsContext.componentSpecificMetadata.renderRequestId) || [];
+  hooks.push(hook);
+  postSSRHooks.set(railsContext.componentSpecificMetadata.renderRequestId, hooks);
+};
+
+export const notifySSREnd = (railsContext: RailsContextWithComponentSpecificMetadata) => {
+  const hooks = postSSRHooks.get(railsContext.componentSpecificMetadata.renderRequestId);
+  if (hooks) {
+    hooks.forEach((hook) => hook());
+  }
+};
diff --git a/node_package/src/streamServerRenderedReactComponent.ts b/node_package/src/streamServerRenderedReactComponent.ts
index dccfe35ea7..ae51ebbd49 100644
--- a/node_package/src/streamServerRenderedReactComponent.ts
+++ b/node_package/src/streamServerRenderedReactComponent.ts
@@ -10,6 +10,7 @@ import { renderToPipeableStream, PipeableStream } from './ReactDOMServer.cts';
 import { createResultObject, convertToError, validateComponent } from './serverRenderUtils.ts';
 import type { RenderParams, StreamRenderState, StreamableComponentResult } from './types/index.ts';
 import injectRSCPayload from './injectRSCPayload.ts';
+import { notifySSREnd } from './postSSRHooks.ts';
 
 type BufferedEvent = {
   event: 'data' | 'error' | 'end';
@@ -187,6 +188,11 @@ const streamRenderReactComponent = (
         onError(e) {
           reportError(convertToError(e));
         },
+        onAllReady() {
+          if (railsContext.componentSpecificMetadata?.renderRequestId) {
+            notifySSREnd(railsContext as RailsContextWithComponentSpecificMetadata);
+          }
+        },
         identifierPrefix: domNodeId,
       });
     })
diff --git a/node_package/src/types/index.ts b/node_package/src/types/index.ts
index b755678621..d95727b741 100644
--- a/node_package/src/types/index.ts
+++ b/node_package/src/types/index.ts
@@ -62,6 +62,12 @@ export type RailsContext = {
     }
 );
 
+export type RailsContextWithComponentSpecificMetadata = RailsContext & {
+  componentSpecificMetadata: {
+    renderRequestId: string;
+  };
+};
+
 // not strictly what we want, see https://github.com/microsoft/TypeScript/issues/17867#issuecomment-323164375
 type AuthenticityHeaders = Record<string, string> & {
   'X-CSRF-Token': string | null;
@@ -291,6 +297,11 @@ export interface ReactOnRails {
    * @param otherHeaders Other headers
    */
   authenticityHeaders(otherHeaders: Record<string, string>): AuthenticityHeaders;
+  /**
+   * Adds a post SSR hook to be called after the SSR has completed.
+   * @param hook - The hook to be called after the SSR has completed.
+   */
+  addPostSSRHook(railsContext: RailsContextWithComponentSpecificMetadata, hook: () => void): void;
 }
 
 export type RSCPayloadStreamInfo = {

From dcda9b029d7069eb14be6f5554f9d0fc7f13a220 Mon Sep 17 00:00:00 2001
From: Abanoub Ghadban <abanoub@shakacode.com>
Date: Sat, 10 May 2025 15:53:54 +0300
Subject: [PATCH 24/50] refactor: improve type safety in server component
 loading and streamline import statements

---
 node_package/src/ReactOnRailsRSC.ts                    | 7 ++++++-
 node_package/src/getReactServerComponent.server.ts     | 4 ++--
 node_package/src/postSSRHooks.ts                       | 2 +-
 node_package/src/streamServerRenderedReactComponent.ts | 7 ++++++-
 4 files changed, 15 insertions(+), 5 deletions(-)

diff --git a/node_package/src/ReactOnRailsRSC.ts b/node_package/src/ReactOnRailsRSC.ts
index 02263e5fc2..e6560beb0c 100644
--- a/node_package/src/ReactOnRailsRSC.ts
+++ b/node_package/src/ReactOnRailsRSC.ts
@@ -1,7 +1,12 @@
 import { renderToPipeableStream } from 'react-on-rails-rsc/server.node';
 import { PassThrough, Readable } from 'stream';
 
-import { RSCRenderParams, StreamRenderState, StreamableComponentResult } from './types/index.ts';
+import {
+  RSCRenderParams,
+  RailsContextWithComponentSpecificMetadata,
+  StreamRenderState,
+  StreamableComponentResult,
+} from './types/index.ts';
 import ReactOnRails from './ReactOnRails.full.ts';
 import buildConsoleReplay from './buildConsoleReplay.ts';
 import handleError from './handleError.ts';
diff --git a/node_package/src/getReactServerComponent.server.ts b/node_package/src/getReactServerComponent.server.ts
index 58d1ba1dff..2cde872af2 100644
--- a/node_package/src/getReactServerComponent.server.ts
+++ b/node_package/src/getReactServerComponent.server.ts
@@ -37,8 +37,8 @@ const createSSRManifest = async (
   reactClientManifestFileName: string,
 ) => {
   const [reactServerManifest, reactClientManifest] = await Promise.all([
-    loadJsonFile(reactServerManifestFileName) as Promise<Record<string, { id: string; chunks: string[] }>>,
-    loadJsonFile(reactClientManifestFileName) as Promise<Record<string, { id: string }>>,
+    loadJsonFile<Record<string, { id: string; chunks: string[] }>>(reactServerManifestFileName),
+    loadJsonFile<Record<string, { id: string }>>(reactClientManifestFileName),
   ]);
 
   const moduleMap: Record<string, unknown> = {};
diff --git a/node_package/src/postSSRHooks.ts b/node_package/src/postSSRHooks.ts
index 46031062b3..19eccdf93e 100644
--- a/node_package/src/postSSRHooks.ts
+++ b/node_package/src/postSSRHooks.ts
@@ -1,4 +1,4 @@
-import { RailsContextWithComponentSpecificMetadata } from "./types/index.ts";
+import { RailsContextWithComponentSpecificMetadata } from './types/index.ts';
 
 type PostSSRHook = () => void;
 const postSSRHooks = new Map<string, PostSSRHook[]>();
diff --git a/node_package/src/streamServerRenderedReactComponent.ts b/node_package/src/streamServerRenderedReactComponent.ts
index ae51ebbd49..eb9042a2ce 100644
--- a/node_package/src/streamServerRenderedReactComponent.ts
+++ b/node_package/src/streamServerRenderedReactComponent.ts
@@ -8,7 +8,12 @@ import buildConsoleReplay from './buildConsoleReplay.ts';
 import handleError from './handleError.ts';
 import { renderToPipeableStream, PipeableStream } from './ReactDOMServer.cts';
 import { createResultObject, convertToError, validateComponent } from './serverRenderUtils.ts';
-import type { RenderParams, StreamRenderState, StreamableComponentResult } from './types/index.ts';
+import type {
+  RailsContextWithComponentSpecificMetadata,
+  RenderParams,
+  StreamRenderState,
+  StreamableComponentResult,
+} from './types/index.ts';
 import injectRSCPayload from './injectRSCPayload.ts';
 import { notifySSREnd } from './postSSRHooks.ts';
 

From c05db9317ab1b3388ab77c0d6f5da3ca855b58b2 Mon Sep 17 00:00:00 2001
From: Abanoub Ghadban <abanoub@shakacode.com>
Date: Sat, 10 May 2025 15:59:22 +0300
Subject: [PATCH 25/50] fix: update module loading configuration to use
 environment-specific prefix and set crossOrigin to null

---
 node_package/src/getReactServerComponent.server.ts | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/node_package/src/getReactServerComponent.server.ts b/node_package/src/getReactServerComponent.server.ts
index 2cde872af2..e478271a9f 100644
--- a/node_package/src/getReactServerComponent.server.ts
+++ b/node_package/src/getReactServerComponent.server.ts
@@ -59,7 +59,8 @@ const createSSRManifest = async (
     // In our case, since the server code is bundled into a single bundle, there is no need to load additional JavaScript modules.
     // As a result, we set this property to an empty object because it will not be used.
     moduleLoading: {
-      prefix: '/webpack/development/',
+      prefix: `/webpack/${process.env.NODE_ENV}/`,
+      crossOrigin: null,
     },
     moduleMap,
   };

From 76228499dd64a37cdfdec0b2c990e81516001257 Mon Sep 17 00:00:00 2001
From: Abanoub Ghadban <abanoub@shakacode.com>
Date: Sat, 10 May 2025 16:48:24 +0300
Subject: [PATCH 26/50] refactor: update react-on-rails-rsc dependency to use
 SSR support and streamline imports for server components

---
 node_package/src/ReactOnRailsRSC.ts           | 17 +++-
 .../src/getReactServerComponent.client.ts     |  2 +-
 .../src/getReactServerComponent.server.ts     | 78 +++++--------------
 package.json                                  |  4 +-
 yarn.lock                                     |  6 +-
 5 files changed, 39 insertions(+), 68 deletions(-)

diff --git a/node_package/src/ReactOnRailsRSC.ts b/node_package/src/ReactOnRailsRSC.ts
index e6560beb0c..78cf38dbbf 100644
--- a/node_package/src/ReactOnRailsRSC.ts
+++ b/node_package/src/ReactOnRailsRSC.ts
@@ -1,4 +1,5 @@
-import { renderToPipeableStream } from 'react-on-rails-rsc/server.node';
+import { BundleManifest } from 'react-on-rails-rsc';
+import { buildServerRenderer } from 'react-on-rails-rsc/server.node';
 import { PassThrough, Readable } from 'stream';
 
 import {
@@ -26,6 +27,8 @@ const stringToStream = (str: string) => {
   return stream;
 };
 
+let serverRenderer: ReturnType<typeof buildServerRenderer> | undefined;
+
 const streamRenderRSCComponent = (
   reactRenderingResult: StreamableComponentResult,
   options: RSCRenderParams,
@@ -44,9 +47,15 @@ const streamRenderRSCComponent = (
 
   const { pipeToTransform, readableStream, emitError } =
     transformRenderStreamChunksToResultObject(renderState);
-  Promise.all([loadJsonFile(reactClientManifestFileName), reactRenderingResult])
-    .then(([reactClientManifest, reactElement]) => {
-      const rscStream = renderToPipeableStream(reactElement, reactClientManifest, {
+  Promise.resolve(reactRenderingResult)
+    .then(async (reactElement) => {
+      if (!serverRenderer) {
+        const reactClientManifest = await loadJsonFile<BundleManifest>(reactClientManifestFileName);
+        serverRenderer = buildServerRenderer(reactClientManifest);
+      }
+
+      const { renderToPipeableStream } = serverRenderer;
+      const rscStream = renderToPipeableStream(reactElement, {
         onError: (err) => {
           const error = convertToError(err);
           console.error('Error in RSC stream', error);
diff --git a/node_package/src/getReactServerComponent.client.ts b/node_package/src/getReactServerComponent.client.ts
index 572095994e..6c5f553492 100644
--- a/node_package/src/getReactServerComponent.client.ts
+++ b/node_package/src/getReactServerComponent.client.ts
@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { createFromReadableStream } from 'react-on-rails-rsc/client';
+import { createFromReadableStream } from 'react-on-rails-rsc/client.browser';
 import { fetch } from './utils.ts';
 import transformRSCStreamAndReplayConsoleLogs from './transformRSCStreamAndReplayConsoleLogs.ts';
 import { RailsContext } from './types/index.ts';
diff --git a/node_package/src/getReactServerComponent.server.ts b/node_package/src/getReactServerComponent.server.ts
index e478271a9f..78b7122dad 100644
--- a/node_package/src/getReactServerComponent.server.ts
+++ b/node_package/src/getReactServerComponent.server.ts
@@ -1,4 +1,5 @@
-import { createFromNodeStream } from 'react-on-rails-rsc/client.node';
+import { BundleManifest } from 'react-on-rails-rsc';
+import { buildClientRenderer } from 'react-on-rails-rsc/client.node';
 import transformRSCStream from './transformRSCNodeStream.ts';
 import loadJsonFile from './loadJsonFile.ts';
 import { RailsContext } from './types/index.ts';
@@ -9,63 +10,24 @@ type RSCServerRootProps = {
   railsContext: RailsContext;
 };
 
-const createFromReactOnRailsNodeStream = (
-  stream: NodeJS.ReadableStream,
-  ssrManifest: Record<string, unknown>,
-) => {
-  const transformedStream = transformRSCStream(stream);
-  return createFromNodeStream(transformedStream, ssrManifest);
-};
+let clientRenderer: ReturnType<typeof buildClientRenderer> | undefined;
 
-/**
- * Creates an SSR manifest for React's server components runtime.
- *
- * This function:
- * 1. Loads the server and client component manifests
- * 2. Creates a mapping between client and server module IDs
- * 3. Builds a moduleMap structure required by React's SSR runtime
- *
- * The manifest allows React to correctly associate server components
- * with their client counterparts during hydration.
- *
- * @param reactServerManifestFileName - Path to the server manifest file
- * @param reactClientManifestFileName - Path to the client manifest file
- * @returns A Promise resolving to the SSR manifest object
- */
-const createSSRManifest = async (
+const createFromReactOnRailsNodeStream = async (
+  stream: NodeJS.ReadableStream,
   reactServerManifestFileName: string,
   reactClientManifestFileName: string,
 ) => {
-  const [reactServerManifest, reactClientManifest] = await Promise.all([
-    loadJsonFile<Record<string, { id: string; chunks: string[] }>>(reactServerManifestFileName),
-    loadJsonFile<Record<string, { id: string }>>(reactClientManifestFileName),
-  ]);
-
-  const moduleMap: Record<string, unknown> = {};
-  Object.entries(reactClientManifest).forEach(([aboluteFileUrl, clientFileBundlingInfo]) => {
-    const { id, chunks } = reactServerManifest[aboluteFileUrl];
-    moduleMap[clientFileBundlingInfo.id] = {
-      '*': {
-        id,
-        chunks,
-        name: '*',
-      },
-    };
-  });
-
-  const ssrManifest = {
-    // The `moduleLoading` property is utilized by the React runtime to load JavaScript modules.
-    // It can accept options such as `prefix` and `crossOrigin` to specify the path and crossorigin attribute for the modules.
-    // In our case, since the server code is bundled into a single bundle, there is no need to load additional JavaScript modules.
-    // As a result, we set this property to an empty object because it will not be used.
-    moduleLoading: {
-      prefix: `/webpack/${process.env.NODE_ENV}/`,
-      crossOrigin: null,
-    },
-    moduleMap,
-  };
+  if (!clientRenderer) {
+    const [reactServerManifest, reactClientManifest] = await Promise.all([
+      loadJsonFile<BundleManifest>(reactServerManifestFileName),
+      loadJsonFile<BundleManifest>(reactClientManifestFileName),
+    ]);
+    clientRenderer = buildClientRenderer(reactClientManifest, reactServerManifest);
+  }
 
-  return ssrManifest;
+  const { createFromNodeStream } = clientRenderer;
+  const transformedStream = transformRSCStream(stream);
+  return createFromNodeStream<React.ReactNode>(transformedStream);
 };
 
 /**
@@ -115,17 +77,17 @@ const getReactServerComponent = async ({
     );
   }
 
-  const ssrManifest = await createSSRManifest(
-    railsContext.reactServerClientManifestFileName,
-    railsContext.reactClientManifestFileName,
-  );
   const rscPayloadStream = await ReactOnRails.getRSCPayloadStream(
     componentName,
     componentProps,
     railsContext,
   );
 
-  return createFromReactOnRailsNodeStream(rscPayloadStream, ssrManifest);
+  return createFromReactOnRailsNodeStream(
+    rscPayloadStream,
+    railsContext.reactServerClientManifestFileName,
+    railsContext.reactClientManifestFileName,
+  );
 };
 
 export default getReactServerComponent;
diff --git a/package.json b/package.json
index 1825679bb3..c745e256fe 100644
--- a/package.json
+++ b/package.json
@@ -65,7 +65,7 @@
     "publint": "^0.3.8",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
-    "react-on-rails-rsc": "git+https://github.com/shakacode/react_on_rails_rsc.git#add-support-for-generating-client-components-manifest-for-server-bundle",
+    "react-on-rails-rsc": "git+https://github.com/shakacode/react_on_rails_rsc.git#ssr-support",
     "redux": "^4.2.1",
     "ts-jest": "^29.2.5",
     "typescript": "^5.8.3",
@@ -74,7 +74,7 @@
   "peerDependencies": {
     "react": ">= 16",
     "react-dom": ">= 16",
-    "react-on-rails-rsc": "git+https://github.com/shakacode/react_on_rails_rsc.git#add-support-for-generating-client-components-manifest-for-server-bundle"
+    "react-on-rails-rsc": "git+https://github.com/shakacode/react_on_rails_rsc.git#ssr-support"
   },
   "files": [
     "node_package/lib"
diff --git a/yarn.lock b/yarn.lock
index a1b9d188d9..fa78d296c7 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -5222,9 +5222,9 @@ react-is@^18.0.0:
   resolved "https://registry.yarnpkg.com/react-is/-/react-is-18.2.0.tgz#199431eeaaa2e09f86427efbb4f1473edb47609b"
   integrity sha512-xWGDIW6x921xtzPkhiULtthJHoJvBbF3q26fzloPCK0hsvxtPVelvftw3zjbHWSkR2km9Z+4uxbDDK/6Zw9B8w==
 
-"react-on-rails-rsc@git+https://github.com/shakacode/react_on_rails_rsc.git#add-support-for-generating-client-components-manifest-for-server-bundle":
-  version "19.0.0-rc.2"
-  resolved "git+https://github.com/shakacode/react_on_rails_rsc.git#f49dc3fd94629ff23c1c6a397b19b6feff437b2f"
+"react-on-rails-rsc@git+https://github.com/shakacode/react_on_rails_rsc.git#ssr-support":
+  version "19.0.0"
+  resolved "git+https://github.com/shakacode/react_on_rails_rsc.git#f71fabc8eb62b08cb4d590da85d2b519d9f8d451"
   dependencies:
     acorn-loose "^8.3.0"
     neo-async "^2.6.1"

From fbbc8fe4190ed1bea2fcb342e57f0fea802b668c Mon Sep 17 00:00:00 2001
From: Abanoub Ghadban <abanoub@shakacode.com>
Date: Sat, 10 May 2025 17:01:24 +0300
Subject: [PATCH 27/50] chore: update acorn and acorn-loose dependencies in
 yarn.lock to latest versions for improved compatibility

---
 yarn.lock | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/yarn.lock b/yarn.lock
index fa78d296c7..c7b0f84ce7 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -1795,18 +1795,18 @@ acorn-jsx@^5.3.2:
   integrity sha512-rq9s+JNhf0IChjtDXxllJ7g41oZk5SlXtp0LHwyA5cejwn7vKmKp4pPri6YEePv2PU65sAsegbXtIinmDFDXgQ==
 
 acorn-loose@^8.3.0:
-  version "8.4.0"
-  resolved "https://registry.yarnpkg.com/acorn-loose/-/acorn-loose-8.4.0.tgz#26d3e219756d1e180d006f5bcc8d261a28530f55"
-  integrity sha512-M0EUka6rb+QC4l9Z3T0nJEzNOO7JcoJlYMrBlyBCiFSXRyxjLKayd4TbQs2FDRWQU1h9FR7QVNHt+PEaoNL5rQ==
+  version "8.5.0"
+  resolved "https://registry.yarnpkg.com/acorn-loose/-/acorn-loose-8.5.0.tgz#11fbd555827d551dd16ca812c078e382400b1bc7"
+  integrity sha512-ppga7pybjwX2HSJv5ayHe6QG4wmNS1RQ2wjBMFTVnOj0h8Rxsmtc6fnVzINqHSSRz23sTe9IL3UAt/PU9gc4FA==
   dependencies:
-    acorn "^8.11.0"
+    acorn "^8.14.0"
 
 acorn-walk@^8.0.2:
   version "8.3.1"
   resolved "https://registry.yarnpkg.com/acorn-walk/-/acorn-walk-8.3.1.tgz#2f10f5b69329d90ae18c58bf1fa8fccd8b959a43"
   integrity sha512-TgUZgYvqZprrl7YldZNoa9OciCAyZR+Ejm9eXzKCmjsF5IKp/wgQ7Z/ZpjpGTIUPwrHQIcYeI8qDh4PsEwxMbw==
 
-acorn@^8.1.0, acorn@^8.11.0, acorn@^8.14.0, acorn@^8.8.1:
+acorn@^8.1.0, acorn@^8.14.0, acorn@^8.8.1:
   version "8.14.1"
   resolved "https://registry.yarnpkg.com/acorn/-/acorn-8.14.1.tgz#721d5dc10f7d5b5609a891773d47731796935dfb"
   integrity sha512-OvQ/2pUDKmgfCg++xsTX1wGxfTaszcHVcTctW4UJB4hibJx2HXxxO5UmVgyjMa+ZDsiaf5wWLXYpRWMmBI0QHg==

From 33fd8a0aad174b485c5074444651ff7080c93f31 Mon Sep 17 00:00:00 2001
From: Abanoub Ghadban <abanoub@shakacode.com>
Date: Sat, 10 May 2025 18:36:33 +0300
Subject: [PATCH 28/50] refactor: clarify test description for child async
 component hydration in SuspenseHydration test

---
 node_package/tests/SuspenseHydration.test.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/node_package/tests/SuspenseHydration.test.tsx b/node_package/tests/SuspenseHydration.test.tsx
index b25a9f4b70..d779d427f6 100644
--- a/node_package/tests/SuspenseHydration.test.tsx
+++ b/node_package/tests/SuspenseHydration.test.tsx
@@ -182,7 +182,7 @@ async function renderAndHydrate() {
     expect(screen.queryByText('Hello World')).not.toBeInTheDocument();
   });
 
-  it('hydrates the container when its content is written to the document', async () => {
+  it('hydrates the child async component when its content is written to the document', async () => {
     const { writeFirstChunk, writeSecondChunk, onAsyncComponentHydrated, onContainerHydrated, hydrate } =
       await renderAndHydrate();
 

From b69bb79220e9056cd4f322302fcdb1dfe7fa52bc Mon Sep 17 00:00:00 2001
From: Abanoub Ghadban <abanoub@shakacode.com>
Date: Sun, 11 May 2025 15:37:45 +0300
Subject: [PATCH 29/50] fix problem of returning the wrong stream

---
 node_package/src/RSCPayloadGenerator.ts | 2 +-
 yarn.lock                               | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/node_package/src/RSCPayloadGenerator.ts b/node_package/src/RSCPayloadGenerator.ts
index 0b7d17983a..1f8a159439 100644
--- a/node_package/src/RSCPayloadGenerator.ts
+++ b/node_package/src/RSCPayloadGenerator.ts
@@ -71,7 +71,7 @@ export const getRSCPayloadStream = async (
   const stream1 = new PassThrough();
   stream.pipe(stream1);
   const stream2 = new PassThrough();
-  stream1.pipe(stream2);
+  stream.pipe(stream2);
 
   const streamInfo: RSCPayloadStreamInfo = {
     componentName,
diff --git a/yarn.lock b/yarn.lock
index c7b0f84ce7..e3c6148874 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -5224,7 +5224,7 @@ react-is@^18.0.0:
 
 "react-on-rails-rsc@git+https://github.com/shakacode/react_on_rails_rsc.git#ssr-support":
   version "19.0.0"
-  resolved "git+https://github.com/shakacode/react_on_rails_rsc.git#f71fabc8eb62b08cb4d590da85d2b519d9f8d451"
+  resolved "git+https://github.com/shakacode/react_on_rails_rsc.git#c95a692b493e2dfc650e38d4378d61bd3194e8c8"
   dependencies:
     acorn-loose "^8.3.0"
     neo-async "^2.6.1"

From e1949c4e26d897e5f6868a6c82a837f7c63623ec Mon Sep 17 00:00:00 2001
From: Abanoub Ghadban <abanoub@shakacode.com>
Date: Sun, 18 May 2025 15:56:32 +0300
Subject: [PATCH 30/50] refactor: update RailsContext types to include server
 component capabilities and streamline related functions

---
 eslint.config.ts                              |  2 +
 node_package/src/RSCPayloadGenerator.ts       | 47 ++++++++++++-------
 node_package/src/ReactOnRailsRSC.ts           | 13 ++---
 .../src/getReactServerComponent.server.ts     | 15 +-----
 node_package/src/injectRSCPayload.ts          |  4 +-
 node_package/src/postSSRHooks.ts              |  6 +--
 .../src/streamServerRenderedReactComponent.ts | 13 ++---
 node_package/src/types/index.ts               | 44 ++++++++++++++---
 8 files changed, 86 insertions(+), 58 deletions(-)

diff --git a/eslint.config.ts b/eslint.config.ts
index 58da16938a..d8f523101c 100644
--- a/eslint.config.ts
+++ b/eslint.config.ts
@@ -162,6 +162,8 @@ const config = tsEslint.config([
       parserOptions: {
         projectService: {
           allowDefaultProject: ['eslint.config.ts', 'knip.ts', 'node_package/tests/*.test.{ts,tsx}'],
+          // Needed because `import * as ... from` instead of `import ... from` doesn't work in this file
+          // for some imports.
           defaultProject: 'tsconfig.eslint.json',
         },
       },
diff --git a/node_package/src/RSCPayloadGenerator.ts b/node_package/src/RSCPayloadGenerator.ts
index 1f8a159439..afc202284e 100644
--- a/node_package/src/RSCPayloadGenerator.ts
+++ b/node_package/src/RSCPayloadGenerator.ts
@@ -1,17 +1,21 @@
 import { PassThrough } from 'stream';
-import { RailsContext, RSCPayloadStreamInfo, RSCPayloadCallback } from './types/index.ts';
+import {
+  RailsContextWithServerComponentCapabilities,
+  RSCPayloadStreamInfo,
+  RSCPayloadCallback,
+} from './types/index.ts';
 
 declare global {
   function generateRSCPayload(
     componentName: string,
     props: unknown,
-    railsContext: RailsContext,
+    railsContext: RailsContextWithServerComponentCapabilities,
   ): Promise<NodeJS.ReadableStream>;
 }
 
-const mapRailsContextToRSCPayloadStreams = new Map<RailsContext, RSCPayloadStreamInfo[]>();
+const mapRailsContextToRSCPayloadStreams = new Map<string, RSCPayloadStreamInfo[]>();
 
-const rscPayloadCallbacks = new Map<RailsContext, Array<RSCPayloadCallback>>();
+const rscPayloadCallbacks = new Map<string, Array<RSCPayloadCallback>>();
 
 /**
  * Registers a callback to be executed when RSC payloads are generated.
@@ -27,13 +31,17 @@ const rscPayloadCallbacks = new Map<RailsContext, Array<RSCPayloadCallback>>();
  * @param railsContext - Context for the current request
  * @param callback - Function to call when an RSC payload is generated
  */
-export const onRSCPayloadGenerated = (railsContext: RailsContext, callback: RSCPayloadCallback) => {
-  const callbacks = rscPayloadCallbacks.get(railsContext) || [];
+export const onRSCPayloadGenerated = (
+  railsContext: RailsContextWithServerComponentCapabilities,
+  callback: RSCPayloadCallback,
+) => {
+  const { renderRequestId } = railsContext.componentSpecificMetadata;
+  const callbacks = rscPayloadCallbacks.get(renderRequestId) || [];
   callbacks.push(callback);
-  rscPayloadCallbacks.set(railsContext, callbacks);
+  rscPayloadCallbacks.set(renderRequestId, callbacks);
 
   // Call callback for any existing streams for this context
-  const existingStreams = mapRailsContextToRSCPayloadStreams.get(railsContext) || [];
+  const existingStreams = mapRailsContextToRSCPayloadStreams.get(renderRequestId) || [];
   existingStreams.forEach((streamInfo) => callback(streamInfo));
 };
 
@@ -56,7 +64,7 @@ export const onRSCPayloadGenerated = (railsContext: RailsContext, callback: RSCP
 export const getRSCPayloadStream = async (
   componentName: string,
   props: unknown,
-  railsContext: RailsContext,
+  railsContext: RailsContextWithServerComponentCapabilities,
 ): Promise<NodeJS.ReadableStream> => {
   if (typeof generateRSCPayload !== 'function') {
     throw new Error(
@@ -66,8 +74,9 @@ export const getRSCPayloadStream = async (
     );
   }
 
+  const { renderRequestId } = railsContext.componentSpecificMetadata;
   const stream = await generateRSCPayload(componentName, props, railsContext);
-  const streams = mapRailsContextToRSCPayloadStreams.get(railsContext) ?? [];
+  const streams = mapRailsContextToRSCPayloadStreams.get(renderRequestId) ?? [];
   const stream1 = new PassThrough();
   stream.pipe(stream1);
   const stream2 = new PassThrough();
@@ -79,25 +88,29 @@ export const getRSCPayloadStream = async (
     stream: stream2,
   };
   streams.push(streamInfo);
-  mapRailsContextToRSCPayloadStreams.set(railsContext, streams);
+  mapRailsContextToRSCPayloadStreams.set(renderRequestId, streams);
 
   // Notify callbacks about the new stream in a sync manner to maintain proper hydration timing
   // as described in the comment above onRSCPayloadGenerated
-  const callbacks = rscPayloadCallbacks.get(railsContext) || [];
+  const callbacks = rscPayloadCallbacks.get(renderRequestId) || [];
   callbacks.forEach((callback) => callback(streamInfo));
 
   return stream1;
 };
 
 export const getRSCPayloadStreams = (
-  railsContext: RailsContext,
+  railsContext: RailsContextWithServerComponentCapabilities,
 ): {
   componentName: string;
   props: unknown;
   stream: NodeJS.ReadableStream;
-}[] => mapRailsContextToRSCPayloadStreams.get(railsContext) ?? [];
+}[] => {
+  const { renderRequestId } = railsContext.componentSpecificMetadata;
+  return mapRailsContextToRSCPayloadStreams.get(renderRequestId) ?? [];
+};
 
-export const clearRSCPayloadStreams = (railsContext: RailsContext) => {
-  mapRailsContextToRSCPayloadStreams.delete(railsContext);
-  rscPayloadCallbacks.delete(railsContext);
+export const clearRSCPayloadStreams = (railsContext: RailsContextWithServerComponentCapabilities) => {
+  const { renderRequestId } = railsContext.componentSpecificMetadata;
+  mapRailsContextToRSCPayloadStreams.delete(renderRequestId);
+  rscPayloadCallbacks.delete(renderRequestId);
 };
diff --git a/node_package/src/ReactOnRailsRSC.ts b/node_package/src/ReactOnRailsRSC.ts
index 78cf38dbbf..cbe59af665 100644
--- a/node_package/src/ReactOnRailsRSC.ts
+++ b/node_package/src/ReactOnRailsRSC.ts
@@ -4,7 +4,7 @@ import { PassThrough, Readable } from 'stream';
 
 import {
   RSCRenderParams,
-  RailsContextWithComponentSpecificMetadata,
+  assertRailsContextWithServerComponentCapabilities,
   StreamRenderState,
   StreamableComponentResult,
 } from './types/index.ts';
@@ -34,11 +34,10 @@ const streamRenderRSCComponent = (
   options: RSCRenderParams,
 ): Readable => {
   const { throwJsErrors } = options;
-  if (!options.railsContext?.serverSide || !options.railsContext.reactClientManifestFileName) {
-    throw new Error('Rails context is not available');
-  }
+  const { railsContext } = options;
+  assertRailsContextWithServerComponentCapabilities(railsContext);
 
-  const { reactClientManifestFileName } = options.railsContext;
+  const { reactClientManifestFileName } = railsContext;
   const renderState: StreamRenderState = {
     result: null,
     hasErrors: false,
@@ -78,9 +77,7 @@ const streamRenderRSCComponent = (
     });
 
   readableStream.on('end', () => {
-    if (options.railsContext?.componentSpecificMetadata) {
-      notifySSREnd(options.railsContext as RailsContextWithComponentSpecificMetadata);
-    }
+    notifySSREnd(railsContext);
   });
   return readableStream;
 };
diff --git a/node_package/src/getReactServerComponent.server.ts b/node_package/src/getReactServerComponent.server.ts
index 78b7122dad..7d3fb18d7b 100644
--- a/node_package/src/getReactServerComponent.server.ts
+++ b/node_package/src/getReactServerComponent.server.ts
@@ -2,7 +2,7 @@ import { BundleManifest } from 'react-on-rails-rsc';
 import { buildClientRenderer } from 'react-on-rails-rsc/client.node';
 import transformRSCStream from './transformRSCNodeStream.ts';
 import loadJsonFile from './loadJsonFile.ts';
-import { RailsContext } from './types/index.ts';
+import { assertRailsContextWithServerComponentCapabilities, RailsContext } from './types/index.ts';
 
 type RSCServerRootProps = {
   componentName: string;
@@ -58,18 +58,7 @@ const getReactServerComponent = async ({
   componentProps,
   railsContext,
 }: RSCServerRootProps) => {
-  if (
-    !railsContext?.serverSide ||
-    !railsContext?.reactClientManifestFileName ||
-    !railsContext?.reactServerClientManifestFileName
-  ) {
-    throw new Error(
-      'serverClientManifestFileName and reactServerClientManifestFileName are required. ' +
-        'Please ensure that React Server Component webpack configurations are properly set ' +
-        'as stated in the React Server Component tutorial. ' +
-        'Make sure to use "stream_react_component" instead of "react_component" to SSR a server component.',
-    );
-  }
+  assertRailsContextWithServerComponentCapabilities(railsContext);
 
   if (typeof ReactOnRails.getRSCPayloadStream !== 'function') {
     throw new Error(
diff --git a/node_package/src/injectRSCPayload.ts b/node_package/src/injectRSCPayload.ts
index 155c4c79b0..066a922ed8 100644
--- a/node_package/src/injectRSCPayload.ts
+++ b/node_package/src/injectRSCPayload.ts
@@ -1,6 +1,6 @@
 import { PipeableStream } from 'react-dom/server';
 import { PassThrough, Transform } from 'stream';
-import { RailsContext } from './types/index.ts';
+import { RailsContextWithServerComponentCapabilities } from './types/index.ts';
 
 // In JavaScript, when an escape sequence with a backslash (\) is followed by a character
 // that isn't a recognized escape character, the backslash is ignored, and the character
@@ -50,7 +50,7 @@ function writeChunk(chunk: string, transform: Transform, cacheKey: string) {
  */
 export default function injectRSCPayload(
   pipeableHtmlStream: NodeJS.ReadableStream | PipeableStream,
-  railsContext: RailsContext,
+  railsContext: RailsContextWithServerComponentCapabilities,
 ) {
   const htmlStream = new PassThrough();
   pipeableHtmlStream.pipe(htmlStream);
diff --git a/node_package/src/postSSRHooks.ts b/node_package/src/postSSRHooks.ts
index 19eccdf93e..5421b1894b 100644
--- a/node_package/src/postSSRHooks.ts
+++ b/node_package/src/postSSRHooks.ts
@@ -1,10 +1,10 @@
-import { RailsContextWithComponentSpecificMetadata } from './types/index.ts';
+import { RailsContextWithServerComponentCapabilities } from './types/index.ts';
 
 type PostSSRHook = () => void;
 const postSSRHooks = new Map<string, PostSSRHook[]>();
 
 export const addPostSSRHook = (
-  railsContext: RailsContextWithComponentSpecificMetadata,
+  railsContext: RailsContextWithServerComponentCapabilities,
   hook: PostSSRHook,
 ) => {
   const hooks = postSSRHooks.get(railsContext.componentSpecificMetadata.renderRequestId) || [];
@@ -12,7 +12,7 @@ export const addPostSSRHook = (
   postSSRHooks.set(railsContext.componentSpecificMetadata.renderRequestId, hooks);
 };
 
-export const notifySSREnd = (railsContext: RailsContextWithComponentSpecificMetadata) => {
+export const notifySSREnd = (railsContext: RailsContextWithServerComponentCapabilities) => {
   const hooks = postSSRHooks.get(railsContext.componentSpecificMetadata.renderRequestId);
   if (hooks) {
     hooks.forEach((hook) => hook());
diff --git a/node_package/src/streamServerRenderedReactComponent.ts b/node_package/src/streamServerRenderedReactComponent.ts
index eb9042a2ce..0b97a89103 100644
--- a/node_package/src/streamServerRenderedReactComponent.ts
+++ b/node_package/src/streamServerRenderedReactComponent.ts
@@ -8,8 +8,8 @@ import buildConsoleReplay from './buildConsoleReplay.ts';
 import handleError from './handleError.ts';
 import { renderToPipeableStream, PipeableStream } from './ReactDOMServer.cts';
 import { createResultObject, convertToError, validateComponent } from './serverRenderUtils.ts';
-import type {
-  RailsContextWithComponentSpecificMetadata,
+import {
+  assertRailsContextWithServerComponentCapabilities,
   RenderParams,
   StreamRenderState,
   StreamableComponentResult,
@@ -138,7 +138,7 @@ const streamRenderReactComponent = (
   reactRenderingResult: StreamableComponentResult,
   options: RenderParams,
 ) => {
-  const { name: componentName, throwJsErrors, domNodeId } = options;
+  const { name: componentName, throwJsErrors, domNodeId, railsContext } = options;
   const renderState: StreamRenderState = {
     result: null,
     hasErrors: false,
@@ -163,10 +163,7 @@ const streamRenderReactComponent = (
     endStream();
   };
 
-  const { railsContext } = options;
-  if (!railsContext) {
-    throw new Error('railsContext is required to stream a React component');
-  }
+  assertRailsContextWithServerComponentCapabilities(railsContext);
 
   Promise.resolve(reactRenderingResult)
     .then((reactRenderedElement) => {
@@ -195,7 +192,7 @@ const streamRenderReactComponent = (
         },
         onAllReady() {
           if (railsContext.componentSpecificMetadata?.renderRequestId) {
-            notifySSREnd(railsContext as RailsContextWithComponentSpecificMetadata);
+            notifySSREnd(railsContext);
           }
         },
         identifierPrefix: domNodeId,
diff --git a/node_package/src/types/index.ts b/node_package/src/types/index.ts
index d95727b741..a524eee8f4 100644
--- a/node_package/src/types/index.ts
+++ b/node_package/src/types/index.ts
@@ -62,12 +62,38 @@ export type RailsContext = {
     }
 );
 
-export type RailsContextWithComponentSpecificMetadata = RailsContext & {
+export type RailsContextWithServerComponentCapabilities = RailsContext & {
+  serverSide: true;
+  serverSideRSCPayloadParameters: unknown;
+  reactClientManifestFileName: string;
+  reactServerClientManifestFileName: string;
   componentSpecificMetadata: {
     renderRequestId: string;
   };
 };
 
+export const assertRailsContextWithServerComponentCapabilities: (
+  context: RailsContext | undefined,
+) => asserts context is RailsContextWithServerComponentCapabilities = (
+  context: RailsContext | undefined,
+): asserts context is RailsContextWithServerComponentCapabilities => {
+  if (
+    !context ||
+    !('serverSideRSCPayloadParameters' in context) ||
+    !('reactClientManifestFileName' in context) ||
+    !('reactServerClientManifestFileName' in context) ||
+    !('componentSpecificMetadata' in context)
+  ) {
+    throw new Error(
+      'Rails context does not have server side RSC payload parameters.\n\n' +
+        'Please ensure:\n' +
+        '1. You are using a compatible version of react_on_rails_pro\n' +
+        '2. Server components support is enabled by setting:\n' +
+        '   ReactOnRailsPro.configuration.enable_rsc_support = true',
+    );
+  }
+};
+
 // not strictly what we want, see https://github.com/microsoft/TypeScript/issues/17867#issuecomment-323164375
 type AuthenticityHeaders = Record<string, string> & {
   'X-CSRF-Token': string | null;
@@ -183,7 +209,8 @@ export interface RenderParams extends Params {
   renderingReturnsPromises: boolean;
 }
 
-export interface RSCRenderParams extends RenderParams {
+export interface RSCRenderParams extends Omit<RenderParams, 'railsContext'> {
+  railsContext: RailsContextWithServerComponentCapabilities;
   reactClientManifestFileName: string;
 }
 
@@ -301,7 +328,7 @@ export interface ReactOnRails {
    * Adds a post SSR hook to be called after the SSR has completed.
    * @param hook - The hook to be called after the SSR has completed.
    */
-  addPostSSRHook(railsContext: RailsContextWithComponentSpecificMetadata, hook: () => void): void;
+  addPostSSRHook(railsContext: RailsContextWithServerComponentCapabilities, hook: () => void): void;
 }
 
 export type RSCPayloadStreamInfo = {
@@ -432,7 +459,7 @@ export interface ReactOnRailsInternal extends ReactOnRails {
   getRSCPayloadStream?: (
     componentName: string,
     props: unknown,
-    railsContext: RailsContext,
+    railsContext: RailsContextWithServerComponentCapabilities,
   ) => Promise<NodeJS.ReadableStream>;
 
   /**
@@ -441,7 +468,7 @@ export interface ReactOnRailsInternal extends ReactOnRails {
     * @param railsContext - The Rails context of the current rendering request.
     * @returns An array of objects, each containing the component name and its corresponding NodeJS.ReadableStream.
     */
-  getRSCPayloadStreams?: (railsContext: RailsContext) => {
+  getRSCPayloadStreams?: (railsContext: RailsContextWithServerComponentCapabilities) => {
     componentName: string;
     props: unknown;
     stream: NodeJS.ReadableStream;
@@ -452,13 +479,16 @@ export interface ReactOnRailsInternal extends ReactOnRails {
    * @param railsContext - The Rails context of the current rendering request.
    * @param callback - The callback to be called when an RSC payload stream is generated.
    */
-  onRSCPayloadGenerated?: (railsContext: RailsContext, callback: RSCPayloadCallback) => void;
+  onRSCPayloadGenerated?: (
+    railsContext: RailsContextWithServerComponentCapabilities,
+    callback: RSCPayloadCallback,
+  ) => void;
 
   /**
    * Clears all RSC payload streams generated for the rendering request of the given Rails context.
    * @param railsContext - The Rails context of the current rendering request.
    */
-  clearRSCPayloadStreams?: (railsContext: RailsContext) => void;
+  clearRSCPayloadStreams?: (railsContext: RailsContextWithServerComponentCapabilities) => void;
 }
 
 export type RenderStateHtml = FinalHtmlResult | Promise<FinalHtmlResult>;

From 0e4b561f84cf8fd503dfea94102ae40aa799e18d Mon Sep 17 00:00:00 2001
From: Abanoub Ghadban <abanoub@shakacode.com>
Date: Sun, 18 May 2025 19:02:19 +0300
Subject: [PATCH 31/50] refactor: rename rscPayloadGenerationUrl to
 rscPayloadGenerationUrlPath and enhance type safety in RailsContext

---
 lib/react_on_rails/helper.rb                  |  2 +-
 lib/react_on_rails/utils.rb                   |  2 +-
 node_package/src/ClientSideRenderer.ts        |  2 +-
 node_package/src/RSCPayloadGenerator.ts       | 36 +++++++++++++------
 node_package/src/RSCProvider.tsx              | 18 +++++-----
 node_package/src/RSCRoute.ts                  |  7 ++--
 .../src/getReactServerComponent.client.ts     | 11 +++---
 node_package/src/types/index.ts               | 25 ++++++++++---
 node_package/src/utils.ts                     | 11 +++++-
 .../wrapServerComponentRenderer/client.tsx    | 10 +++---
 .../wrapServerComponentRenderer/server.tsx    |  5 ++-
 11 files changed, 83 insertions(+), 46 deletions(-)

diff --git a/lib/react_on_rails/helper.rb b/lib/react_on_rails/helper.rb
index 52844ab6d7..6ae565f93c 100644
--- a/lib/react_on_rails/helper.rb
+++ b/lib/react_on_rails/helper.rb
@@ -381,7 +381,7 @@ def rails_context(server_side: true)
         if ReactOnRails::Utils.react_on_rails_pro?
           result[:rorProVersion] = ReactOnRails::Utils.react_on_rails_pro_version
 
-          result[:rscPayloadGenerationUrl] = rsc_url if ReactOnRailsPro.configuration.enable_rsc_support
+          result[:rscPayloadGenerationUrlPath] = rsc_url if ReactOnRailsPro.configuration.enable_rsc_support
         end
 
         if defined?(request) && request.present?
diff --git a/lib/react_on_rails/utils.rb b/lib/react_on_rails/utils.rb
index 3645daabac..669e3ba457 100644
--- a/lib/react_on_rails/utils.rb
+++ b/lib/react_on_rails/utils.rb
@@ -130,7 +130,7 @@ def self.react_server_client_manifest_file_path
       asset_name = ReactOnRails.configuration.react_server_client_manifest_file
       if asset_name.nil?
         raise ReactOnRails::Error,
-              "react_server_client_manifest_file is nil, ensure to set it in your configuration"
+              "react_server_client_manifest_file is nil, ensure it is set in your configuration"
       end
 
       @react_server_manifest_path = File.join(generated_assets_full_path, asset_name)
diff --git a/node_package/src/ClientSideRenderer.ts b/node_package/src/ClientSideRenderer.ts
index e1b5239dd0..ea8e527d14 100644
--- a/node_package/src/ClientSideRenderer.ts
+++ b/node_package/src/ClientSideRenderer.ts
@@ -86,7 +86,7 @@ class ComponentRenderer {
     const renderRequestId = el.getAttribute('data-render-request-id');
 
     if (!renderRequestId) {
-      console.error(`renderRequestId is missing for ${name} in dom node with id: ${domNodeId}`);
+      console.error(`renderRequestId is missing for component ${name} in the DOM node with id ${domNodeId}`);
     }
 
     const componentSpecificRailsContext = {
diff --git a/node_package/src/RSCPayloadGenerator.ts b/node_package/src/RSCPayloadGenerator.ts
index afc202284e..21fa5cc6fb 100644
--- a/node_package/src/RSCPayloadGenerator.ts
+++ b/node_package/src/RSCPayloadGenerator.ts
@@ -15,7 +15,7 @@ declare global {
 
 const mapRailsContextToRSCPayloadStreams = new Map<string, RSCPayloadStreamInfo[]>();
 
-const rscPayloadCallbacks = new Map<string, Array<RSCPayloadCallback>>();
+const rscPayloadCallbacks = new Map<string, RSCPayloadCallback[]>();
 
 /**
  * Registers a callback to be executed when RSC payloads are generated.
@@ -36,13 +36,18 @@ export const onRSCPayloadGenerated = (
   callback: RSCPayloadCallback,
 ) => {
   const { renderRequestId } = railsContext.componentSpecificMetadata;
-  const callbacks = rscPayloadCallbacks.get(renderRequestId) || [];
-  callbacks.push(callback);
-  rscPayloadCallbacks.set(renderRequestId, callbacks);
+  const callbacks = rscPayloadCallbacks.get(renderRequestId);
+  if (callbacks) {
+    callbacks.push(callback);
+  } else {
+    rscPayloadCallbacks.set(renderRequestId, [callback]);
+  }
 
   // Call callback for any existing streams for this context
-  const existingStreams = mapRailsContextToRSCPayloadStreams.get(renderRequestId) || [];
-  existingStreams.forEach((streamInfo) => callback(streamInfo));
+  const existingStreams = mapRailsContextToRSCPayloadStreams.get(renderRequestId);
+  if (existingStreams) {
+    existingStreams.forEach((streamInfo) => callback(streamInfo));
+  }
 };
 
 /**
@@ -76,7 +81,10 @@ export const getRSCPayloadStream = async (
 
   const { renderRequestId } = railsContext.componentSpecificMetadata;
   const stream = await generateRSCPayload(componentName, props, railsContext);
-  const streams = mapRailsContextToRSCPayloadStreams.get(renderRequestId) ?? [];
+  // Tee stream to allow for multiple consumers:
+  //   1. stream1 - Used by React's runtime to perform server-side rendering
+  //   2. stream2 - Used by react-on-rails to embed the RSC payloads
+  //      into the HTML stream for client-side hydration
   const stream1 = new PassThrough();
   stream.pipe(stream1);
   const stream2 = new PassThrough();
@@ -87,13 +95,19 @@ export const getRSCPayloadStream = async (
     props,
     stream: stream2,
   };
-  streams.push(streamInfo);
-  mapRailsContextToRSCPayloadStreams.set(renderRequestId, streams);
+  const streams = mapRailsContextToRSCPayloadStreams.get(renderRequestId);
+  if (streams) {
+    streams.push(streamInfo);
+  } else {
+    mapRailsContextToRSCPayloadStreams.set(renderRequestId, [streamInfo]);
+  }
 
   // Notify callbacks about the new stream in a sync manner to maintain proper hydration timing
   // as described in the comment above onRSCPayloadGenerated
-  const callbacks = rscPayloadCallbacks.get(renderRequestId) || [];
-  callbacks.forEach((callback) => callback(streamInfo));
+  const callbacks = rscPayloadCallbacks.get(renderRequestId);
+  if (callbacks) {
+    callbacks.forEach((callback) => callback(streamInfo));
+  }
 
   return stream1;
 };
diff --git a/node_package/src/RSCProvider.tsx b/node_package/src/RSCProvider.tsx
index 2e9bff34e3..ad96dfc0ee 100644
--- a/node_package/src/RSCProvider.tsx
+++ b/node_package/src/RSCProvider.tsx
@@ -1,6 +1,7 @@
 import * as React from 'react';
-import { RailsContext } from './types/index.ts';
+import { RailsContextWithComponentSpecificMetadata } from './types/index.ts';
 import getReactServerComponent from './getReactServerComponent.client.ts';
+import { createRSCPayloadKey } from './utils.ts';
 
 type RSCContextType = {
   getCachedComponent: (componentName: string, componentProps: unknown) => React.ReactNode;
@@ -33,18 +34,14 @@ export const createRSCProvider = ({
   railsContext,
   getServerComponent,
 }: {
-  railsContext: RailsContext;
+  railsContext: RailsContextWithComponentSpecificMetadata;
   getServerComponent: typeof getReactServerComponent;
 }) => {
   const cachedComponents: Record<string, React.ReactNode> = {};
   const fetchRSCPromises: Record<string, Promise<React.ReactNode>> = {};
 
-  const generateCacheKey = (componentName: string, componentProps: unknown) => {
-    return `${componentName}-${JSON.stringify(componentProps)}-${railsContext.componentSpecificMetadata?.renderRequestId}`;
-  };
-
   const getCachedComponent = (componentName: string, componentProps: unknown) => {
-    const key = generateCacheKey(componentName, componentProps);
+    const key = createRSCPayloadKey(componentName, componentProps, railsContext);
     return cachedComponents[key];
   };
 
@@ -53,7 +50,7 @@ export const createRSCProvider = ({
     if (cachedComponent) {
       return cachedComponent;
     }
-    const key = generateCacheKey(componentName, componentProps);
+    const key = createRSCPayloadKey(componentName, componentProps, railsContext);
     if (key in fetchRSCPromises) {
       return fetchRSCPromises[key];
     }
@@ -66,9 +63,10 @@ export const createRSCProvider = ({
     return promise;
   };
 
+  const contextValue = { getCachedComponent, getComponent };
+
   return ({ children }: { children: React.ReactNode }) => {
-    // eslint-disable-next-line react/jsx-no-constructed-context-values
-    return <RSCContext.Provider value={{ getCachedComponent, getComponent }}>{children}</RSCContext.Provider>;
+    return <RSCContext.Provider value={contextValue}>{children}</RSCContext.Provider>;
   };
 };
 
diff --git a/node_package/src/RSCRoute.ts b/node_package/src/RSCRoute.ts
index c82328f2b8..a6d8df58ef 100644
--- a/node_package/src/RSCRoute.ts
+++ b/node_package/src/RSCRoute.ts
@@ -30,10 +30,9 @@ export type RSCRouteProps = {
 
 const RSCRoute = ({ componentName, componentProps }: RSCRouteProps) => {
   const { getComponent, getCachedComponent } = useRSC();
-  let component = getCachedComponent(componentName, componentProps);
-  if (!component) {
-    component = React.use(getComponent(componentName, componentProps));
-  }
+  const component =
+    getCachedComponent(componentName, componentProps) ??
+    React.use(getComponent(componentName, componentProps));
   return component;
 };
 
diff --git a/node_package/src/getReactServerComponent.client.ts b/node_package/src/getReactServerComponent.client.ts
index 6c5f553492..24da7bc3d3 100644
--- a/node_package/src/getReactServerComponent.client.ts
+++ b/node_package/src/getReactServerComponent.client.ts
@@ -1,8 +1,8 @@
 import * as React from 'react';
 import { createFromReadableStream } from 'react-on-rails-rsc/client.browser';
-import { fetch } from './utils.ts';
+import { createRSCPayloadKey, fetch } from './utils.ts';
 import transformRSCStreamAndReplayConsoleLogs from './transformRSCStreamAndReplayConsoleLogs.ts';
-import { RailsContext } from './types/index.ts';
+import { assertRailsContextWithComponentSpecificMetadata, RailsContext } from './types/index.ts';
 
 declare global {
   interface Window {
@@ -42,8 +42,8 @@ const createFromFetch = async (fetchPromise: Promise<Response>) => {
  */
 const fetchRSC = ({ componentName, componentProps, railsContext }: ClientGetReactServerComponentProps) => {
   const propsString = JSON.stringify(componentProps);
-  const { rscPayloadGenerationUrl } = railsContext;
-  const strippedUrlPath = rscPayloadGenerationUrl?.replace(/^\/|\/$/g, '');
+  const { rscPayloadGenerationUrlPath } = railsContext;
+  const strippedUrlPath = rscPayloadGenerationUrlPath?.replace(/^\/|\/$/g, '');
   return createFromFetch(fetch(`/${strippedUrlPath}/${componentName}?props=${propsString}`));
 };
 
@@ -126,7 +126,8 @@ const getReactServerComponent = ({
   componentProps,
   railsContext,
 }: ClientGetReactServerComponentProps) => {
-  const componentKey = `${componentName}-${JSON.stringify(componentProps)}-${railsContext.componentSpecificMetadata?.renderRequestId}`;
+  assertRailsContextWithComponentSpecificMetadata(railsContext);
+  const componentKey = createRSCPayloadKey(componentName, componentProps, railsContext);
   const payloads = window.REACT_ON_RAILS_RSC_PAYLOADS?.[componentKey];
   if (payloads) {
     return createFromPreloadedPayloads(payloads);
diff --git a/node_package/src/types/index.ts b/node_package/src/types/index.ts
index a524eee8f4..12c7014684 100644
--- a/node_package/src/types/index.ts
+++ b/node_package/src/types/index.ts
@@ -34,7 +34,7 @@ export type RailsContext = {
   pathname: string;
   search: string | null;
   httpAcceptLanguage: string;
-  rscPayloadGenerationUrl?: string;
+  rscPayloadGenerationUrlPath?: string;
   componentSpecificMetadata?: {
     // The renderRequestId serves as a unique identifier for each render request.
     // We cannot rely solely on nodeDomId, as it should be unique for each component on the page,
@@ -62,14 +62,29 @@ export type RailsContext = {
     }
 );
 
-export type RailsContextWithServerComponentCapabilities = RailsContext & {
+export type RailsContextWithComponentSpecificMetadata = RailsContext & {
+  componentSpecificMetadata: {
+    renderRequestId: string;
+  };
+};
+
+export type RailsContextWithServerComponentCapabilities = RailsContextWithComponentSpecificMetadata & {
   serverSide: true;
   serverSideRSCPayloadParameters: unknown;
   reactClientManifestFileName: string;
   reactServerClientManifestFileName: string;
-  componentSpecificMetadata: {
-    renderRequestId: string;
-  };
+};
+
+export const assertRailsContextWithComponentSpecificMetadata: (
+  context: RailsContext | undefined,
+) => asserts context is RailsContextWithComponentSpecificMetadata = (
+  context: RailsContext | undefined,
+): asserts context is RailsContextWithComponentSpecificMetadata => {
+  if (!context || !('componentSpecificMetadata' in context)) {
+    throw new Error(
+      'Rails context does not have component specific metadata. Please ensure you are using a compatible version of react_on_rails_pro',
+    );
+  }
 };
 
 export const assertRailsContextWithServerComponentCapabilities: (
diff --git a/node_package/src/utils.ts b/node_package/src/utils.ts
index 87118a8c03..3d633d7c8f 100644
--- a/node_package/src/utils.ts
+++ b/node_package/src/utils.ts
@@ -1,3 +1,5 @@
+import { RailsContextWithComponentSpecificMetadata } from './types/index.ts';
+
 // Override the fetch function to make it easier to test
 // The default fetch implementation in jest returns Node's Readable stream
 // In jest.setup.js, we configure this fetch to return a web-standard ReadableStream instead,
@@ -8,5 +10,12 @@ const customFetch = (...args: Parameters<typeof fetch>) => {
   return res;
 };
 
-// eslint-disable-next-line import/prefer-default-export
 export { customFetch as fetch };
+
+export const createRSCPayloadKey = (
+  componentName: string,
+  componentProps: unknown,
+  railsContext: RailsContextWithComponentSpecificMetadata,
+) => {
+  return `${componentName}-${JSON.stringify(componentProps)}-${railsContext.componentSpecificMetadata.renderRequestId}`;
+};
diff --git a/node_package/src/wrapServerComponentRenderer/client.tsx b/node_package/src/wrapServerComponentRenderer/client.tsx
index 1cdd0b7843..6143887571 100644
--- a/node_package/src/wrapServerComponentRenderer/client.tsx
+++ b/node_package/src/wrapServerComponentRenderer/client.tsx
@@ -1,6 +1,10 @@
 import * as React from 'react';
 import * as ReactDOMClient from 'react-dom/client';
-import { ReactComponentOrRenderFunction, RenderFunction } from '../types/index.ts';
+import {
+  ReactComponentOrRenderFunction,
+  RenderFunction,
+  assertRailsContextWithComponentSpecificMetadata,
+} from '../types/index.ts';
 import isRenderFunction from '../isRenderFunction.ts';
 import { ensureReactUseAvailable } from '../reactApis.cts';
 import { createRSCProvider } from '../RSCProvider.tsx';
@@ -41,9 +45,7 @@ const wrapServerComponentRenderer = (componentOrRenderFunction: ReactComponentOr
       throw new Error('wrapServerComponentRenderer: component is not a function');
     }
 
-    if (!railsContext) {
-      throw new Error('RSCClientRoot: No railsContext provided');
-    }
+    assertRailsContextWithComponentSpecificMetadata(railsContext);
 
     const RSCProvider = createRSCProvider({
       railsContext,
diff --git a/node_package/src/wrapServerComponentRenderer/server.tsx b/node_package/src/wrapServerComponentRenderer/server.tsx
index af90849d30..47e70bda86 100644
--- a/node_package/src/wrapServerComponentRenderer/server.tsx
+++ b/node_package/src/wrapServerComponentRenderer/server.tsx
@@ -3,6 +3,7 @@ import type { RenderFunction, ReactComponentOrRenderFunction } from '../types/in
 import getReactServerComponent from '../getReactServerComponent.server.ts';
 import { createRSCProvider } from '../RSCProvider.tsx';
 import isRenderFunction from '../isRenderFunction.ts';
+import { assertRailsContextWithServerComponentCapabilities } from '../types/index.ts';
 
 /**
  * Wraps a client component with the necessary RSC context and handling for server-side operations.
@@ -29,9 +30,7 @@ const wrapServerComponentRenderer = (componentOrRenderFunction: ReactComponentOr
   }
 
   const wrapper: RenderFunction = async (props, railsContext) => {
-    if (!railsContext) {
-      throw new Error('RSCClientRoot: No railsContext provided');
-    }
+    assertRailsContextWithServerComponentCapabilities(railsContext);
 
     const Component = isRenderFunction(componentOrRenderFunction)
       ? await componentOrRenderFunction(props, railsContext)

From eb262de2d111545fbd6f811bcc9b9a30a2f3b1de Mon Sep 17 00:00:00 2001
From: Abanoub Ghadban <abanoub@shakacode.com>
Date: Sun, 18 May 2025 19:38:20 +0300
Subject: [PATCH 32/50] refactor: enhance error handling and improve code
 clarity in server component rendering and tests

---
 jest.config.js                                |  3 +--
 node_package/src/injectRSCPayload.ts          | 11 ++------
 .../src/registerServerComponent/server.rsc.ts |  4 +--
 .../wrapServerComponentRenderer/client.tsx    | 27 ++++++++++---------
 .../wrapServerComponentRenderer/server.tsx    | 14 +++++-----
 node_package/tests/SuspenseHydration.test.tsx |  5 ++--
 .../registerServerComponent.client.test.jsx   |  5 ++--
 7 files changed, 29 insertions(+), 40 deletions(-)

diff --git a/jest.config.js b/jest.config.js
index 25e9afd1e8..fcf1d7d372 100644
--- a/jest.config.js
+++ b/jest.config.js
@@ -14,8 +14,7 @@ export default {
   }),
   testEnvironment: 'jsdom',
   setupFiles: ['<rootDir>/node_package/tests/jest.setup.js'],
-  // React Server Components tests are compatible with React 19
-  // That only run with node version 18 and above
+  // React Server Components tests require React 19 and only run with Node version 18 (`newest` in our CI matrix)
   moduleNameMapper:
     nodeVersion < 18
       ? {
diff --git a/node_package/src/injectRSCPayload.ts b/node_package/src/injectRSCPayload.ts
index 066a922ed8..ad958ea331 100644
--- a/node_package/src/injectRSCPayload.ts
+++ b/node_package/src/injectRSCPayload.ts
@@ -1,5 +1,6 @@
 import { PipeableStream } from 'react-dom/server';
 import { PassThrough, Transform } from 'stream';
+import { finished } from 'stream/promises';
 import { RailsContextWithServerComponentCapabilities } from './types/index.ts';
 
 // In JavaScript, when an escape sequence with a backslash (\) is followed by a character
@@ -90,15 +91,7 @@ export default function injectRSCPayload(
         );
       });
 
-      await new Promise((resolve) => {
-        if (htmlStream.readableEnded) {
-          resolve(Promise.all(rscPromises));
-        } else {
-          htmlStream.on('end', () => {
-            resolve(Promise.all(rscPromises));
-          });
-        }
-      });
+      await finished(htmlStream).then(() => Promise.all(rscPromises));
     } catch (err) {
       resultStream.emit('error', err);
     }
diff --git a/node_package/src/registerServerComponent/server.rsc.ts b/node_package/src/registerServerComponent/server.rsc.ts
index e7dea03f00..c5ee59c0be 100644
--- a/node_package/src/registerServerComponent/server.rsc.ts
+++ b/node_package/src/registerServerComponent/server.rsc.ts
@@ -14,8 +14,8 @@ import { ReactComponent, RenderFunction } from '../types/index.ts';
  * @example
  * ```js
  * registerServerComponent({
- *   ServerComponent1: ServerComponent1Component,
- *   ServerComponent2: ServerComponent2Component
+ *   ServerComponent1,
+ *   ServerComponent2,
  * });
  * ```
  */
diff --git a/node_package/src/wrapServerComponentRenderer/client.tsx b/node_package/src/wrapServerComponentRenderer/client.tsx
index 6143887571..e7feb97bca 100644
--- a/node_package/src/wrapServerComponentRenderer/client.tsx
+++ b/node_package/src/wrapServerComponentRenderer/client.tsx
@@ -45,6 +45,14 @@ const wrapServerComponentRenderer = (componentOrRenderFunction: ReactComponentOr
       throw new Error('wrapServerComponentRenderer: component is not a function');
     }
 
+    if (!domNodeId) {
+      throw new Error('RSCClientRoot: No domNodeId provided');
+    }
+    const domNode = document.getElementById(domNodeId);
+    if (!domNode) {
+      throw new Error(`RSCClientRoot: No DOM node found for id: ${domNodeId}`);
+    }
+
     assertRailsContextWithComponentSpecificMetadata(railsContext);
 
     const RSCProvider = createRSCProvider({
@@ -52,21 +60,14 @@ const wrapServerComponentRenderer = (componentOrRenderFunction: ReactComponentOr
       getServerComponent: getReactServerComponent,
     });
 
-    const SuspensableRSCRoute = (
-      <React.Suspense fallback={null}>
-        <Component {...props} />
-      </React.Suspense>
+    const root = (
+      <RSCProvider>
+        <React.Suspense fallback={null}>
+          <Component {...props} />
+        </React.Suspense>
+      </RSCProvider>
     );
 
-    const root = <RSCProvider>{SuspensableRSCRoute}</RSCProvider>;
-
-    if (!domNodeId) {
-      throw new Error('RSCClientRoot: No domNodeId provided');
-    }
-    const domNode = document.getElementById(domNodeId);
-    if (!domNode) {
-      throw new Error(`RSCClientRoot: No DOM node found for id: ${domNodeId}`);
-    }
     if (domNode.innerHTML) {
       ReactDOMClient.hydrateRoot(domNode, root, { identifierPrefix: domNodeId });
     } else {
diff --git a/node_package/src/wrapServerComponentRenderer/server.tsx b/node_package/src/wrapServerComponentRenderer/server.tsx
index 47e70bda86..d92cc04a3a 100644
--- a/node_package/src/wrapServerComponentRenderer/server.tsx
+++ b/node_package/src/wrapServerComponentRenderer/server.tsx
@@ -45,15 +45,13 @@ const wrapServerComponentRenderer = (componentOrRenderFunction: ReactComponentOr
       getServerComponent: getReactServerComponent,
     });
 
-    const suspensableServerComponent = (
-      <React.Suspense fallback={null}>
-        <Component {...props} />
-      </React.Suspense>
+    return () => (
+      <RSCProvider>
+        <React.Suspense fallback={null}>
+          <Component {...props} />
+        </React.Suspense>
+      </RSCProvider>
     );
-
-    const root = <RSCProvider>{suspensableServerComponent}</RSCProvider>;
-
-    return () => root;
   };
 
   return wrapper;
diff --git a/node_package/tests/SuspenseHydration.test.tsx b/node_package/tests/SuspenseHydration.test.tsx
index d779d427f6..b7cfcca6be 100644
--- a/node_package/tests/SuspenseHydration.test.tsx
+++ b/node_package/tests/SuspenseHydration.test.tsx
@@ -21,7 +21,7 @@ import { getNodeVersion } from './testUtils.js';
  * RSC payload to be present in the page before client-side hydration can occur.
  * And because the RSCRoute is rendered on the server because it's being hydrated on the client,
  * we can sure that the RSC payload is present in the page before the RSCRoute is hydrated on the client.
- * That's because `getRSCPayloadStream` function embeds the RSC payload immediately to the html stream even before the RSCRoute is rendered on the server.
+ * That's because `getRSCPayloadStream` function embeds the RSC payload immediately to the HTML stream even before the RSCRoute is rendered on the server.
  * Without this guarantee, hydration would fail or produce incorrect results.
  */
 
@@ -152,8 +152,7 @@ async function renderAndHydrate() {
   };
 }
 
-// React Server Components tests are compatible with React 19
-// That only run with node version 18 and above
+// React Server Components tests require React 19 and only run with Node version 18 (`newest` in our CI matrix)
 (getNodeVersion() >= 18 ? describe : describe.skip)('RSCClientRoot', () => {
   beforeEach(() => {
     jest.clearAllMocks();
diff --git a/node_package/tests/registerServerComponent.client.test.jsx b/node_package/tests/registerServerComponent.client.test.jsx
index 70a209fe1f..7e57d27749 100644
--- a/node_package/tests/registerServerComponent.client.test.jsx
+++ b/node_package/tests/registerServerComponent.client.test.jsx
@@ -16,8 +16,7 @@ import { clear as clearComponentRegistry } from '../src/ComponentRegistry.ts';
 
 enableFetchMocks();
 
-// React Server Components tests are compatible with React 19
-// That only run with node version 18 and above
+// React Server Components tests require React 19 and only run with Node version 18 (`newest` in our CI matrix)
 (getNodeVersion() >= 18 ? describe : describe.skip)('RSCClientRoot', () => {
   let container;
   const mockDomNodeId = 'test-container';
@@ -242,7 +241,7 @@ enableFetchMocks();
         document.dispatchEvent(new Event('DOMContentLoaded'));
       });
 
-      // After second chunk, AsyncComponent should now be visible and loading indicator gone
+      // After the second chunk, AsyncComponent should now be visible and loading indicator gone
       expect(screen.getByText('AsyncComponent')).toBeInTheDocument();
       expect(screen.queryByText('Loading AsyncComponent...')).not.toBeInTheDocument();
 

From 382cbb9d6970d1fd7bf50ccdcb1dfab9bd5f6951 Mon Sep 17 00:00:00 2001
From: Abanoub Ghadban <abanoub@shakacode.com>
Date: Mon, 19 May 2025 15:50:59 +0300
Subject: [PATCH 33/50] handle trailing commas while removing packages from at
 CI "oldest" tests

---
 script/convert | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/script/convert b/script/convert
index 1be440499a..7e500701d1 100755
--- a/script/convert
+++ b/script/convert
@@ -26,12 +26,15 @@ gsub_file_content("../package.json", /"eslint-plugin-jest": "[^"]*",/, "")
 gsub_file_content("../package.json", /"globals": "[^"]*",/, "")
 gsub_file_content("../package.json", /"knip": "[^"]*",/, "")
 gsub_file_content("../package.json", /"publint": "[^"]*",/, "")
-gsub_file_content("../package.json", /"typescript-eslint": "[^"]*",/, "")
+gsub_file_content("../package.json", /"typescript-eslint": "[^"]*",?/, "")
 gsub_file_content("../package.json", %r{"@arethetypeswrong/cli": "[^"]*",}, "")
 gsub_file_content("../package.json", %r{"@eslint/compat": "[^"]*",}, "")
 gsub_file_content("../package.json", %r{"@testing-library/dom": "[^"]*",}, "")
 gsub_file_content("../package.json", %r{"@testing-library/react": "[^"]*",}, "")
 
+# Clean up any trailing commas before closing braces
+gsub_file_content("../package.json", /,(\s*})/, "\\1")
+
 # Switch to the oldest supported React version
 gsub_file_content("../package.json", /"react": "[^"]*",/, '"react": "16.14.0",')
 gsub_file_content("../package.json", /"react-dom": "[^"]*",/, '"react-dom": "16.14.0",')

From 99a018b60c7f731b3f4afdbb4f594127b00a0a38 Mon Sep 17 00:00:00 2001
From: Abanoub Ghadban <abanoub@shakacode.com>
Date: Mon, 19 May 2025 15:54:15 +0300
Subject: [PATCH 34/50] don't run SuspenseHydration tests with CI oldest tests

---
 script/convert | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/script/convert b/script/convert
index 7e500701d1..35b28737fe 100755
--- a/script/convert
+++ b/script/convert
@@ -43,7 +43,7 @@ gsub_file_content("../spec/dummy/package.json", /"react-dom": "[^"]*",/, '"react
 gsub_file_content(
   "../package.json",
   "jest node_package/tests",
-  'jest node_package/tests --testPathIgnorePatterns=\".*(RSC|stream|serverRenderReactComponent).*\"'
+  'jest node_package/tests --testPathIgnorePatterns=\".*(RSC|stream|serverRenderReactComponent|SuspenseHydration).*\"'
 )
 gsub_file_content("../tsconfig.json", "react-jsx", "react")
 gsub_file_content("../spec/dummy/babel.config.js", "runtime: 'automatic'", "runtime: 'classic'")

From 58f5a9aeffe1a6f5837a8c0f24d6dac141e76e28 Mon Sep 17 00:00:00 2001
From: Abanoub Ghadban <abanoub@shakacode.com>
Date: Mon, 19 May 2025 15:57:46 +0300
Subject: [PATCH 35/50] chore: update testPathIgnorePatterns to exclude
 additional test cases in CI

---
 script/convert | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/script/convert b/script/convert
index 35b28737fe..a733777434 100755
--- a/script/convert
+++ b/script/convert
@@ -43,7 +43,8 @@ gsub_file_content("../spec/dummy/package.json", /"react-dom": "[^"]*",/, '"react
 gsub_file_content(
   "../package.json",
   "jest node_package/tests",
-  'jest node_package/tests --testPathIgnorePatterns=\".*(RSC|stream|serverRenderReactComponent|SuspenseHydration).*\"'
+  'jest node_package/tests --testPathIgnorePatterns=".*(RSC|stream|' \
+  'registerServerComponent|serverRenderReactComponent|SuspenseHydration).*"'
 )
 gsub_file_content("../tsconfig.json", "react-jsx", "react")
 gsub_file_content("../spec/dummy/babel.config.js", "runtime: 'automatic'", "runtime: 'classic'")

From 711d33367bc3ab51b7f391a2b3597408916936e9 Mon Sep 17 00:00:00 2001
From: Abanoub Ghadban <abanoub@shakacode.com>
Date: Mon, 19 May 2025 16:04:49 +0300
Subject: [PATCH 36/50] chore: escape quotes in testPathIgnorePatterns for
 proper parsing in CI

---
 script/convert | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/script/convert b/script/convert
index a733777434..b900a4844d 100755
--- a/script/convert
+++ b/script/convert
@@ -43,8 +43,8 @@ gsub_file_content("../spec/dummy/package.json", /"react-dom": "[^"]*",/, '"react
 gsub_file_content(
   "../package.json",
   "jest node_package/tests",
-  'jest node_package/tests --testPathIgnorePatterns=".*(RSC|stream|' \
-  'registerServerComponent|serverRenderReactComponent|SuspenseHydration).*"'
+  'jest node_package/tests --testPathIgnorePatterns=\".*(RSC|stream|' \
+  'registerServerComponent|serverRenderReactComponent|SuspenseHydration).*\"'
 )
 gsub_file_content("../tsconfig.json", "react-jsx", "react")
 gsub_file_content("../spec/dummy/babel.config.js", "runtime: 'automatic'", "runtime: 'classic'")

From 432cad1d339e12edaa67c6ef44ac1a0319120788 Mon Sep 17 00:00:00 2001
From: Abanoub Ghadban <abanoub@shakacode.com>
Date: Mon, 19 May 2025 16:22:38 +0300
Subject: [PATCH 37/50] refactor: update RailsContext usage in tests to utilize
 RailsContextWithServerComponentCapabilities for improved type safety

---
 node_package/tests/injectRSCPayload.test.ts   |  4 ++--
 ...treamServerRenderedReactComponent.test.jsx | 21 ++++++++++---------
 2 files changed, 13 insertions(+), 12 deletions(-)

diff --git a/node_package/tests/injectRSCPayload.test.ts b/node_package/tests/injectRSCPayload.test.ts
index c792d03203..e00b864d3f 100644
--- a/node_package/tests/injectRSCPayload.test.ts
+++ b/node_package/tests/injectRSCPayload.test.ts
@@ -1,5 +1,5 @@
 import { Readable, PassThrough } from 'stream';
-import ReactOnRails, { RailsContext } from '../src/ReactOnRails.node.ts';
+import ReactOnRails, { RailsContextWithServerComponentCapabilities } from '../src/ReactOnRails.node.ts';
 import injectRSCPayload from '../src/injectRSCPayload.ts';
 
 // Shared utilities
@@ -44,7 +44,7 @@ const setupTest = (mockRSC: Readable) => {
     componentSpecificMetadata: {
       renderRequestId: '123',
     },
-  } as RailsContext;
+  } as RailsContextWithServerComponentCapabilities;
 
   return { railsContext };
 };
diff --git a/node_package/tests/streamServerRenderedReactComponent.test.jsx b/node_package/tests/streamServerRenderedReactComponent.test.jsx
index 6a20658339..ff850fd795 100644
--- a/node_package/tests/streamServerRenderedReactComponent.test.jsx
+++ b/node_package/tests/streamServerRenderedReactComponent.test.jsx
@@ -43,6 +43,15 @@ TestComponentForStreaming.propTypes = {
 };
 
 describe('streamServerRenderedReactComponent', () => {
+  const testingRailsContext = {
+    serverSideRSCPayloadParameters: {},
+    reactClientManifestFileName: 'clientManifest.json',
+    reactServerClientManifestFileName: 'serverClientManifest.json',
+    componentSpecificMetadata: {
+      renderRequestId: '123',
+    },
+  };
+
   beforeEach(() => {
     ComponentRegistry.components().clear();
   });
@@ -102,11 +111,7 @@ describe('streamServerRenderedReactComponent', () => {
       trace: false,
       props: { throwSyncError, throwAsyncError },
       throwJsErrors,
-      railsContext: {
-        componentSpecificMetadata: {
-          renderRequestId: '123',
-        },
-      },
+      railsContext: testingRailsContext,
     });
 
     const chunks = [];
@@ -327,11 +332,7 @@ describe('streamServerRenderedReactComponent', () => {
       domNodeId: 'stringPromiseId',
       trace: false,
       throwJsErrors: false,
-      railsContext: {
-        componentSpecificMetadata: {
-          renderRequestId: '123',
-        },
-      },
+      railsContext: testingRailsContext,
     });
 
     const chunks = [];

From ad4dbe184025551b36fa730160d65dbe663ea362 Mon Sep 17 00:00:00 2001
From: Abanoub Ghadban <abanoub@shakacode.com>
Date: Mon, 19 May 2025 16:28:16 +0300
Subject: [PATCH 38/50] refactor: update test cases to use
 rscPayloadGenerationUrlPath for consistency in RailsContext

---
 node_package/tests/registerServerComponent.client.test.jsx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/node_package/tests/registerServerComponent.client.test.jsx b/node_package/tests/registerServerComponent.client.test.jsx
index 7e57d27749..6af36892c8 100644
--- a/node_package/tests/registerServerComponent.client.test.jsx
+++ b/node_package/tests/registerServerComponent.client.test.jsx
@@ -63,7 +63,7 @@ enableFetchMocks();
 
     registerServerComponent('TestComponent');
     const railsContext = {
-      rscPayloadGenerationUrl: rscPayloadGenerationUrlPath,
+      rscPayloadGenerationUrlPath,
       componentSpecificMetadata: {
         renderRequestId: 'test-render-request-id',
       },
@@ -173,7 +173,7 @@ enableFetchMocks();
 
       registerServerComponent('TestComponent');
       railsContext = {
-        rscPayloadGenerationUrl: 'rsc-render',
+        rscPayloadGenerationUrlPath: 'rsc-render',
         componentSpecificMetadata: {
           renderRequestId: 'test-render-request-id',
         },

From 251b90c2a3006b0a7e1f09b78edf8d50a8338b27 Mon Sep 17 00:00:00 2001
From: Abanoub Ghadban <abanoub@shakacode.com>
Date: Mon, 19 May 2025 16:37:22 +0300
Subject: [PATCH 39/50] refactor: unify stream types by introducing
 PipeableOrReadableStream

---
 node_package/src/injectRSCPayload.ts                   | 5 ++---
 node_package/src/streamServerRenderedReactComponent.ts | 7 ++++---
 node_package/src/types/index.ts                        | 4 ++++
 3 files changed, 10 insertions(+), 6 deletions(-)

diff --git a/node_package/src/injectRSCPayload.ts b/node_package/src/injectRSCPayload.ts
index ad958ea331..4835fa1995 100644
--- a/node_package/src/injectRSCPayload.ts
+++ b/node_package/src/injectRSCPayload.ts
@@ -1,7 +1,6 @@
-import { PipeableStream } from 'react-dom/server';
 import { PassThrough, Transform } from 'stream';
 import { finished } from 'stream/promises';
-import { RailsContextWithServerComponentCapabilities } from './types/index.ts';
+import { RailsContextWithServerComponentCapabilities, PipeableOrReadableStream } from './types/index.ts';
 
 // In JavaScript, when an escape sequence with a backslash (\) is followed by a character
 // that isn't a recognized escape character, the backslash is ignored, and the character
@@ -50,7 +49,7 @@ function writeChunk(chunk: string, transform: Transform, cacheKey: string) {
  * @returns A combined stream with embedded RSC payloads
  */
 export default function injectRSCPayload(
-  pipeableHtmlStream: NodeJS.ReadableStream | PipeableStream,
+  pipeableHtmlStream: PipeableOrReadableStream,
   railsContext: RailsContextWithServerComponentCapabilities,
 ) {
   const htmlStream = new PassThrough();
diff --git a/node_package/src/streamServerRenderedReactComponent.ts b/node_package/src/streamServerRenderedReactComponent.ts
index 0b97a89103..71f9fe075e 100644
--- a/node_package/src/streamServerRenderedReactComponent.ts
+++ b/node_package/src/streamServerRenderedReactComponent.ts
@@ -6,13 +6,14 @@ import createReactOutput from './createReactOutput.ts';
 import { isPromise, isServerRenderHash } from './isServerRenderResult.ts';
 import buildConsoleReplay from './buildConsoleReplay.ts';
 import handleError from './handleError.ts';
-import { renderToPipeableStream, PipeableStream } from './ReactDOMServer.cts';
+import { renderToPipeableStream } from './ReactDOMServer.cts';
 import { createResultObject, convertToError, validateComponent } from './serverRenderUtils.ts';
 import {
   assertRailsContextWithServerComponentCapabilities,
   RenderParams,
   StreamRenderState,
   StreamableComponentResult,
+  PipeableOrReadableStream,
 } from './types/index.ts';
 import injectRSCPayload from './injectRSCPayload.ts';
 import { notifySSREnd } from './postSSRHooks.ts';
@@ -112,8 +113,8 @@ export const transformRenderStreamChunksToResultObject = (renderState: StreamRen
     },
   });
 
-  let pipedStream: PipeableStream | NodeJS.ReadableStream | null = null;
-  const pipeToTransform = (pipeableStream: PipeableStream | NodeJS.ReadableStream) => {
+  let pipedStream: PipeableOrReadableStream | null = null;
+  const pipeToTransform = (pipeableStream: PipeableOrReadableStream) => {
     pipeableStream.pipe(transformStream);
     pipedStream = pipeableStream;
   };
diff --git a/node_package/src/types/index.ts b/node_package/src/types/index.ts
index 12c7014684..95c6ef54e9 100644
--- a/node_package/src/types/index.ts
+++ b/node_package/src/types/index.ts
@@ -1,6 +1,7 @@
 /// <reference types="react/experimental" />
 
 import type { ReactElement, ReactNode, Component, ComponentType } from 'react';
+import type { PipeableStream } from 'react-dom/server';
 import type { Readable } from 'stream';
 
 /* eslint-disable @typescript-eslint/no-explicit-any */
@@ -176,6 +177,8 @@ interface RenderFunction {
 
 type ReactComponentOrRenderFunction = ReactComponent | RenderFunction;
 
+type PipeableOrReadableStream = PipeableStream | NodeJS.ReadableStream;
+
 export type {
   ReactComponentOrRenderFunction,
   ReactComponent,
@@ -192,6 +195,7 @@ export type {
   RenderFunctionSyncResult,
   RenderFunctionAsyncResult,
   StreamableComponentResult,
+  PipeableOrReadableStream,
 };
 
 export interface RegisteredComponent {

From 448e696b76717787d4ed24fac23f81e06748442b Mon Sep 17 00:00:00 2001
From: Abanoub Ghadban <abanoub@shakacode.com>
Date: Mon, 19 May 2025 16:54:31 +0300
Subject: [PATCH 40/50] refactor: replace direct checks for RSC support with a
 utility method for improved clarity and maintainability

---
 lib/react_on_rails/helper.rb            | 2 +-
 lib/react_on_rails/packs_generator.rb   | 6 ++----
 lib/react_on_rails/utils.rb             | 7 +++++++
 spec/dummy/spec/packs_generator_spec.rb | 5 +----
 4 files changed, 11 insertions(+), 9 deletions(-)

diff --git a/lib/react_on_rails/helper.rb b/lib/react_on_rails/helper.rb
index 6ae565f93c..22daeee233 100644
--- a/lib/react_on_rails/helper.rb
+++ b/lib/react_on_rails/helper.rb
@@ -381,7 +381,7 @@ def rails_context(server_side: true)
         if ReactOnRails::Utils.react_on_rails_pro?
           result[:rorProVersion] = ReactOnRails::Utils.react_on_rails_pro_version
 
-          result[:rscPayloadGenerationUrlPath] = rsc_url if ReactOnRailsPro.configuration.enable_rsc_support
+          result[:rscPayloadGenerationUrlPath] = rsc_url if ReactOnRails::Utils.rsc_support_enabled?
         end
 
         if defined?(request) && request.present?
diff --git a/lib/react_on_rails/packs_generator.rb b/lib/react_on_rails/packs_generator.rb
index 883c860a5f..3f6e510feb 100644
--- a/lib/react_on_rails/packs_generator.rb
+++ b/lib/react_on_rails/packs_generator.rb
@@ -89,8 +89,7 @@ def client_entrypoint?(file_path)
 
     def pack_file_contents(file_path)
       registered_component_name = component_name(file_path)
-      load_server_components = ReactOnRails::Utils.react_on_rails_pro? &&
-                               ReactOnRailsPro.configuration.enable_rsc_support
+      load_server_components = ReactOnRails::Utils.rsc_support_enabled?
 
       if load_server_components && !client_entrypoint?(file_path)
         return <<~FILE_CONTENT.strip
@@ -142,8 +141,7 @@ def generated_server_pack_file_content
         "import #{name} from '#{relative_path(generated_server_bundle_file_path, component_path)}';"
       end
 
-      load_server_components = ReactOnRails::Utils.react_on_rails_pro? &&
-                               ReactOnRailsPro.configuration.enable_rsc_support
+      load_server_components = ReactOnRails::Utils.rsc_support_enabled?
       server_components = component_for_server_registration_to_path.keys.delete_if do |name|
         next true unless load_server_components
 
diff --git a/lib/react_on_rails/utils.rb b/lib/react_on_rails/utils.rb
index 669e3ba457..fb8c41ffc1 100644
--- a/lib/react_on_rails/utils.rb
+++ b/lib/react_on_rails/utils.rb
@@ -213,6 +213,13 @@ def self.react_on_rails_pro_version
                                     end
     end
 
+    def self.rsc_support_enabled?
+      return false unless react_on_rails_pro?
+
+      rorp_config = ReactOnRailsPro.configuration
+      rorp_config.respond_to?(:enable_rsc_support) && rorp_config.enable_rsc_support
+    end
+
     def self.full_text_errors_enabled?
       ENV["FULL_TEXT_ERRORS"] == "true"
     end
diff --git a/spec/dummy/spec/packs_generator_spec.rb b/spec/dummy/spec/packs_generator_spec.rb
index 6322c2d974..dcb69b7a11 100644
--- a/spec/dummy/spec/packs_generator_spec.rb
+++ b/spec/dummy/spec/packs_generator_spec.rb
@@ -220,10 +220,7 @@ def self.configuration
       before do
         stub_packer_source_path(component_name: components_directory,
                                 packer_source_path: packer_source_path)
-        allow(ReactOnRails::Utils).to receive(:react_on_rails_pro?).and_return(true)
-        allow(ReactOnRailsPro.configuration).to receive_messages(
-          enable_rsc_support: true
-        )
+        allow(ReactOnRails::Utils).to receive_messages(react_on_rails_pro?: true, rsc_support_enabled?: true)
       end
 
       context "when common component is not a client entrypoint" do

From a8d2d1fde1ca84b464c382e4b70a75cc26ccff68 Mon Sep 17 00:00:00 2001
From: Abanoub Ghadban <abanoub@shakacode.com>
Date: Mon, 19 May 2025 17:47:48 +0300
Subject: [PATCH 41/50] refactor: update stubbing in packs_generator_spec to
 improve clarity and maintainability

---
 spec/dummy/spec/packs_generator_spec.rb | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/spec/dummy/spec/packs_generator_spec.rb b/spec/dummy/spec/packs_generator_spec.rb
index dcb69b7a11..6322c2d974 100644
--- a/spec/dummy/spec/packs_generator_spec.rb
+++ b/spec/dummy/spec/packs_generator_spec.rb
@@ -220,7 +220,10 @@ def self.configuration
       before do
         stub_packer_source_path(component_name: components_directory,
                                 packer_source_path: packer_source_path)
-        allow(ReactOnRails::Utils).to receive_messages(react_on_rails_pro?: true, rsc_support_enabled?: true)
+        allow(ReactOnRails::Utils).to receive(:react_on_rails_pro?).and_return(true)
+        allow(ReactOnRailsPro.configuration).to receive_messages(
+          enable_rsc_support: true
+        )
       end
 
       context "when common component is not a client entrypoint" do

From 441c901d091cdbe87382a7fdd18d839c8f48f044 Mon Sep 17 00:00:00 2001
From: Abanoub Ghadban <abanoub@shakacode.com>
Date: Mon, 19 May 2025 18:27:42 +0300
Subject: [PATCH 42/50] refactor: make renderRequestId optional in server
 component rendering for improved flexibility and clarity

---
 .../react_component/render_options.rb         |  3 ++-
 .../server_rendering_js_code.rb               |  1 -
 node_package/src/ClientSideRenderer.ts        | 20 +++++++++----------
 3 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/lib/react_on_rails/react_component/render_options.rb b/lib/react_on_rails/react_component/render_options.rb
index 29bfbb7c74..e0a0303ae8 100644
--- a/lib/react_on_rails/react_component/render_options.rb
+++ b/lib/react_on_rails/react_component/render_options.rb
@@ -21,7 +21,8 @@ def initialize(react_component_name: required("react_component_name"), options:
         # Therefore, we need an additional unique identifier that can be used both on the client and server.
         # This ID can also be used to associate specific data with a particular rendered component
         # on either the server or client.
-        @render_request_id = self.class.generate_request_id
+        # This ID is only present if RSC support is enabled because it's only used in that case.
+        @render_request_id = self.class.generate_request_id if ReactOnRails::Utils.rsc_support_enabled?
       end
 
       attr_reader :react_component_name, :render_request_id
diff --git a/lib/react_on_rails/server_rendering_js_code.rb b/lib/react_on_rails/server_rendering_js_code.rb
index cd0b8b6773..dc807b7a28 100644
--- a/lib/react_on_rails/server_rendering_js_code.rb
+++ b/lib/react_on_rails/server_rendering_js_code.rb
@@ -38,7 +38,6 @@ def render(props_string, rails_context, redux_stores, react_component_name, rend
         <<-JS
         (function() {
           var railsContext = #{rails_context};
-          railsContext.componentSpecificMetadata = {renderRequestId: '#{render_options.render_request_id}'};
         #{redux_stores}
           var props = #{props_string};
           return ReactOnRails.serverRenderReactComponent({
diff --git a/node_package/src/ClientSideRenderer.ts b/node_package/src/ClientSideRenderer.ts
index ea8e527d14..51ca5460dd 100644
--- a/node_package/src/ClientSideRenderer.ts
+++ b/node_package/src/ClientSideRenderer.ts
@@ -85,16 +85,16 @@ class ComponentRenderer {
     const trace = el.getAttribute('data-trace') === 'true';
     const renderRequestId = el.getAttribute('data-render-request-id');
 
-    if (!renderRequestId) {
-      console.error(`renderRequestId is missing for component ${name} in the DOM node with id ${domNodeId}`);
-    }
-
-    const componentSpecificRailsContext = {
-      ...railsContext,
-      componentSpecificMetadata: {
-        renderRequestId: renderRequestId || '',
-      },
-    };
+    // The renderRequestId is optional and only present when React Server Components (RSC) support is enabled.
+    // When RSC is enabled, this ID helps track and associate server-rendered components with their client-side hydration.
+    const componentSpecificRailsContext = renderRequestId
+      ? {
+          ...railsContext,
+          componentSpecificMetadata: {
+            renderRequestId,
+          },
+        }
+      : railsContext;
 
     try {
       const domNode = document.getElementById(domNodeId);

From 8520d4efb46d78b226a0e44f0518c75fc7a2a2c8 Mon Sep 17 00:00:00 2001
From: Abanoub Ghadban <abanoub@shakacode.com>
Date: Mon, 19 May 2025 18:36:54 +0300
Subject: [PATCH 43/50] refactor: remove renderRequestId from script tags in
 ReactOnRailsHelper specs for improved clarity

---
 .../spec/helpers/react_on_rails_helper_spec.rb     | 14 ++++++--------
 1 file changed, 6 insertions(+), 8 deletions(-)

diff --git a/spec/dummy/spec/helpers/react_on_rails_helper_spec.rb b/spec/dummy/spec/helpers/react_on_rails_helper_spec.rb
index 6aa1544b26..b1e9f7d29b 100644
--- a/spec/dummy/spec/helpers/react_on_rails_helper_spec.rb
+++ b/spec/dummy/spec/helpers/react_on_rails_helper_spec.rb
@@ -21,8 +21,6 @@ class PlainReactOnRailsHelper
         { "HTTP_ACCEPT_LANGUAGE" => "en" }
       )
     }
-
-    allow(ReactOnRails::ReactComponent::RenderOptions).to receive(:generate_request_id).and_return("123")
   end
 
   let(:hash) do
@@ -197,7 +195,7 @@ def helper.append_javascript_pack_tag(name, **options)
         <script type="application/json" class="js-react-on-rails-component" \
         id="js-react-on-rails-component-App-react-component" \
         data-component-name="App" data-dom-id="App-react-component"
-        data-force-load="true" data-render-request-id="123">{"name":"My Test Name"}</script>
+        data-force-load="true">{"name":"My Test Name"}</script>
       SCRIPT
     end
 
@@ -206,7 +204,7 @@ def helper.append_javascript_pack_tag(name, **options)
         <script type="application/json" class="js-react-on-rails-component" \
         id="js-react-on-rails-component-App-react-component" \
         data-component-name="App" data-dom-id="App-react-component"
-        data-force-load="true" data-render-request-id="123">{}</script>
+        data-force-load="true">{}</script>
       SCRIPT
     end
 
@@ -255,7 +253,7 @@ def helper.append_javascript_pack_tag(name, **options)
           <script type="application/json" class="js-react-on-rails-component" \
           id="js-react-on-rails-component-App-react-component" \
           data-component-name="App" data-dom-id="App-react-component"
-          data-force-load="true" data-render-request-id="123">{"name":"My Test Name"}</script>
+          data-force-load="true">{"name":"My Test Name"}</script>
         SCRIPT
       end
 
@@ -271,7 +269,7 @@ def helper.append_javascript_pack_tag(name, **options)
           <script type="application/json" class="js-react-on-rails-component" \
           id="js-react-on-rails-component-App-react-component-0" \
           data-component-name="App" data-dom-id="App-react-component-0"
-          data-force-load="true" data-render-request-id="123">{"name":"My Test Name"}</script>
+          data-force-load="true">{"name":"My Test Name"}</script>
         SCRIPT
       end
 
@@ -293,7 +291,7 @@ def helper.append_javascript_pack_tag(name, **options)
           <script type="application/json" class="js-react-on-rails-component" \
           id="js-react-on-rails-component-App-react-component" \
           data-component-name="App" data-dom-id="App-react-component"
-          data-force-load="true" data-render-request-id="123">{"name":"My Test Name"}</script>
+          data-force-load="true">{"name":"My Test Name"}</script>
         SCRIPT
       end
 
@@ -311,7 +309,7 @@ def helper.append_javascript_pack_tag(name, **options)
           <script type="application/json" class="js-react-on-rails-component" \
           id="js-react-on-rails-component-shaka_div" \
           data-component-name="App" data-dom-id="shaka_div"
-          data-force-load="true" data-render-request-id="123">{"name":"My Test Name"}</script>
+          data-force-load="true">{"name":"My Test Name"}</script>
         SCRIPT
       end
 

From cb6ef7984a9cd0f3df6ac20ab0ffe75f0dba528c Mon Sep 17 00:00:00 2001
From: Abanoub Ghadban <abanoub@shakacode.com>
Date: Wed, 21 May 2025 17:59:21 +0300
Subject: [PATCH 44/50] refactor: optimize RSC payload handling and improve
 hook management for better performance and clarity

---
 lib/react_on_rails/utils.rb             |  4 +++-
 node_package/src/RSCPayloadGenerator.ts | 12 ++++++------
 node_package/src/injectRSCPayload.ts    | 15 ++++++---------
 node_package/src/postSSRHooks.ts        | 10 +++++++---
 4 files changed, 22 insertions(+), 19 deletions(-)

diff --git a/lib/react_on_rails/utils.rb b/lib/react_on_rails/utils.rb
index fb8c41ffc1..bca6b39a9f 100644
--- a/lib/react_on_rails/utils.rb
+++ b/lib/react_on_rails/utils.rb
@@ -216,8 +216,10 @@ def self.react_on_rails_pro_version
     def self.rsc_support_enabled?
       return false unless react_on_rails_pro?
 
+      return @rsc_support_enabled if defined?(@rsc_support_enabled)
+
       rorp_config = ReactOnRailsPro.configuration
-      rorp_config.respond_to?(:enable_rsc_support) && rorp_config.enable_rsc_support
+      @rsc_support_enabled = rorp_config.respond_to?(:enable_rsc_support) && rorp_config.enable_rsc_support
     end
 
     def self.full_text_errors_enabled?
diff --git a/node_package/src/RSCPayloadGenerator.ts b/node_package/src/RSCPayloadGenerator.ts
index 21fa5cc6fb..6b49673b62 100644
--- a/node_package/src/RSCPayloadGenerator.ts
+++ b/node_package/src/RSCPayloadGenerator.ts
@@ -13,7 +13,7 @@ declare global {
   ): Promise<NodeJS.ReadableStream>;
 }
 
-const mapRailsContextToRSCPayloadStreams = new Map<string, RSCPayloadStreamInfo[]>();
+const rscPayloadStreams = new Map<string, RSCPayloadStreamInfo[]>();
 
 const rscPayloadCallbacks = new Map<string, RSCPayloadCallback[]>();
 
@@ -44,7 +44,7 @@ export const onRSCPayloadGenerated = (
   }
 
   // Call callback for any existing streams for this context
-  const existingStreams = mapRailsContextToRSCPayloadStreams.get(renderRequestId);
+  const existingStreams = rscPayloadStreams.get(renderRequestId);
   if (existingStreams) {
     existingStreams.forEach((streamInfo) => callback(streamInfo));
   }
@@ -95,11 +95,11 @@ export const getRSCPayloadStream = async (
     props,
     stream: stream2,
   };
-  const streams = mapRailsContextToRSCPayloadStreams.get(renderRequestId);
+  const streams = rscPayloadStreams.get(renderRequestId);
   if (streams) {
     streams.push(streamInfo);
   } else {
-    mapRailsContextToRSCPayloadStreams.set(renderRequestId, [streamInfo]);
+    rscPayloadStreams.set(renderRequestId, [streamInfo]);
   }
 
   // Notify callbacks about the new stream in a sync manner to maintain proper hydration timing
@@ -120,11 +120,11 @@ export const getRSCPayloadStreams = (
   stream: NodeJS.ReadableStream;
 }[] => {
   const { renderRequestId } = railsContext.componentSpecificMetadata;
-  return mapRailsContextToRSCPayloadStreams.get(renderRequestId) ?? [];
+  return rscPayloadStreams.get(renderRequestId) ?? [];
 };
 
 export const clearRSCPayloadStreams = (railsContext: RailsContextWithServerComponentCapabilities) => {
   const { renderRequestId } = railsContext.componentSpecificMetadata;
-  mapRailsContextToRSCPayloadStreams.delete(renderRequestId);
+  rscPayloadStreams.delete(renderRequestId);
   rscPayloadCallbacks.delete(renderRequestId);
 };
diff --git a/node_package/src/injectRSCPayload.ts b/node_package/src/injectRSCPayload.ts
index 4835fa1995..6bec64cd00 100644
--- a/node_package/src/injectRSCPayload.ts
+++ b/node_package/src/injectRSCPayload.ts
@@ -78,15 +78,12 @@ export default function injectRSCPayload(
         // The client-side RSCProvider actively monitors the array for new chunks, processing them as they arrive and forwarding them to the RSC payload stream, regardless of whether the array is initially empty.
         initializeCacheKeyJSArray(cacheKey, resultStream);
         rscPromises.push(
-          new Promise((resolve, reject) => {
-            (async () => {
-              for await (const chunk of stream ?? []) {
-                const decodedChunk = typeof chunk === 'string' ? chunk : decoder.decode(chunk);
-                writeChunk(JSON.stringify(decodedChunk), resultStream, cacheKey);
-              }
-              resolve();
-            })().catch(reject);
-          }),
+          (async () => {
+            for await (const chunk of stream ?? []) {
+              const decodedChunk = typeof chunk === 'string' ? chunk : decoder.decode(chunk);
+              writeChunk(JSON.stringify(decodedChunk), resultStream, cacheKey);
+            }
+          })(),
         );
       });
 
diff --git a/node_package/src/postSSRHooks.ts b/node_package/src/postSSRHooks.ts
index 5421b1894b..ce5ebee7ad 100644
--- a/node_package/src/postSSRHooks.ts
+++ b/node_package/src/postSSRHooks.ts
@@ -7,9 +7,12 @@ export const addPostSSRHook = (
   railsContext: RailsContextWithServerComponentCapabilities,
   hook: PostSSRHook,
 ) => {
-  const hooks = postSSRHooks.get(railsContext.componentSpecificMetadata.renderRequestId) || [];
-  hooks.push(hook);
-  postSSRHooks.set(railsContext.componentSpecificMetadata.renderRequestId, hooks);
+  const hooks = postSSRHooks.get(railsContext.componentSpecificMetadata.renderRequestId);
+  if (hooks) {
+    hooks.push(hook);
+  } else {
+    postSSRHooks.set(railsContext.componentSpecificMetadata.renderRequestId, [hook]);
+  }
 };
 
 export const notifySSREnd = (railsContext: RailsContextWithServerComponentCapabilities) => {
@@ -17,4 +20,5 @@ export const notifySSREnd = (railsContext: RailsContextWithServerComponentCapabi
   if (hooks) {
     hooks.forEach((hook) => hook());
   }
+  postSSRHooks.delete(railsContext.componentSpecificMetadata.renderRequestId);
 };

From f961a3baef0fdf3025242a7e90e855b2440915d4 Mon Sep 17 00:00:00 2001
From: Abanoub Ghadban <abanoub@shakacode.com>
Date: Thu, 22 May 2025 12:28:25 +0300
Subject: [PATCH 45/50] refactor: ensure RSC support variable is reset in
 packs_generator_spec for improved test isolation

---
 spec/dummy/spec/packs_generator_spec.rb | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/spec/dummy/spec/packs_generator_spec.rb b/spec/dummy/spec/packs_generator_spec.rb
index 6322c2d974..1a431e8d98 100644
--- a/spec/dummy/spec/packs_generator_spec.rb
+++ b/spec/dummy/spec/packs_generator_spec.rb
@@ -37,6 +37,9 @@ def self.configuration
       )
       allow(ReactOnRails::Utils).to receive_messages(generated_assets_full_path: packer_source_entry_path,
                                                      server_bundle_js_file_path: server_bundle_js_file_path)
+      if ReactOnRails::Utils.instance_variable_defined?(:@rsc_support_enabled)
+        ReactOnRails::Utils.remove_instance_variable(:@rsc_support_enabled)
+      end
     end
 
     after do

From 2b1517c718157f49d9fd664af745593c1837e1c6 Mon Sep 17 00:00:00 2001
From: Abanoub Ghadban <abanoub@shakacode.com>
Date: Sat, 24 May 2025 19:27:39 +0300
Subject: [PATCH 46/50] refactor: enhance RSC component handling by introducing
 promise wrapper and improving stream processing for better error management

---
 node_package/src/RSCProvider.tsx              |  6 +--
 node_package/src/RSCRoute.ts                  | 11 +++--
 .../src/getReactServerComponent.client.ts     |  8 ++--
 .../transformRSCStreamAndReplayConsoleLogs.ts | 48 +++++++++++--------
 node_package/src/utils.ts                     | 16 +++++++
 5 files changed, 56 insertions(+), 33 deletions(-)

diff --git a/node_package/src/RSCProvider.tsx b/node_package/src/RSCProvider.tsx
index ad96dfc0ee..1e7f2329ce 100644
--- a/node_package/src/RSCProvider.tsx
+++ b/node_package/src/RSCProvider.tsx
@@ -45,11 +45,7 @@ export const createRSCProvider = ({
     return cachedComponents[key];
   };
 
-  const getComponent = async (componentName: string, componentProps: unknown) => {
-    const cachedComponent = getCachedComponent(componentName, componentProps);
-    if (cachedComponent) {
-      return cachedComponent;
-    }
+  const getComponent = (componentName: string, componentProps: unknown) => {
     const key = createRSCPayloadKey(componentName, componentProps, railsContext);
     if (key in fetchRSCPromises) {
       return fetchRSCPromises[key];
diff --git a/node_package/src/RSCRoute.ts b/node_package/src/RSCRoute.ts
index a6d8df58ef..69785d1ec3 100644
--- a/node_package/src/RSCRoute.ts
+++ b/node_package/src/RSCRoute.ts
@@ -30,10 +30,13 @@ export type RSCRouteProps = {
 
 const RSCRoute = ({ componentName, componentProps }: RSCRouteProps) => {
   const { getComponent, getCachedComponent } = useRSC();
-  const component =
-    getCachedComponent(componentName, componentProps) ??
-    React.use(getComponent(componentName, componentProps));
-  return component;
+  const cachedComponent = getCachedComponent(componentName, componentProps);
+  if (cachedComponent) {
+    return cachedComponent;
+  }
+
+  const componentPromise = getComponent(componentName, componentProps);
+  return React.use(componentPromise);
 };
 
 export default RSCRoute;
diff --git a/node_package/src/getReactServerComponent.client.ts b/node_package/src/getReactServerComponent.client.ts
index 24da7bc3d3..c2015db3d4 100644
--- a/node_package/src/getReactServerComponent.client.ts
+++ b/node_package/src/getReactServerComponent.client.ts
@@ -1,6 +1,6 @@
 import * as React from 'react';
 import { createFromReadableStream } from 'react-on-rails-rsc/client.browser';
-import { createRSCPayloadKey, fetch } from './utils.ts';
+import { createRSCPayloadKey, fetch, wrapInNewPromise } from './utils.ts';
 import transformRSCStreamAndReplayConsoleLogs from './transformRSCStreamAndReplayConsoleLogs.ts';
 import { assertRailsContextWithComponentSpecificMetadata, RailsContext } from './types/index.ts';
 
@@ -23,7 +23,8 @@ const createFromFetch = async (fetchPromise: Promise<Response>) => {
     throw new Error('No stream found in response');
   }
   const transformedStream = transformRSCStreamAndReplayConsoleLogs(stream);
-  return createFromReadableStream<React.ReactNode>(transformedStream);
+  const renderPromise = createFromReadableStream<React.ReactNode>(transformedStream);
+  return wrapInNewPromise(renderPromise);
 };
 
 /**
@@ -96,7 +97,8 @@ const createRSCStreamFromArray = (payloads: string[]) => {
 const createFromPreloadedPayloads = (payloads: string[]) => {
   const stream = createRSCStreamFromArray(payloads);
   const transformedStream = transformRSCStreamAndReplayConsoleLogs(stream);
-  return createFromReadableStream<React.ReactNode>(transformedStream);
+  const renderPromise = createFromReadableStream<React.ReactNode>(transformedStream);
+  return wrapInNewPromise(renderPromise);
 };
 
 /**
diff --git a/node_package/src/transformRSCStreamAndReplayConsoleLogs.ts b/node_package/src/transformRSCStreamAndReplayConsoleLogs.ts
index 56af541dd5..724706e552 100644
--- a/node_package/src/transformRSCStreamAndReplayConsoleLogs.ts
+++ b/node_package/src/transformRSCStreamAndReplayConsoleLogs.ts
@@ -39,31 +39,37 @@ export default function transformRSCStreamAndReplayConsoleLogs(stream: ReadableS
         }
       };
 
-      while (!done) {
-        const decodedValue = typeof value === 'string' ? value : decoder.decode(value);
-        const decodedChunks = lastIncompleteChunk + decodedValue;
-        const chunks = decodedChunks.split('\n');
-        lastIncompleteChunk = chunks.pop() ?? '';
+      try {
+        while (!done) {
+          const decodedValue = typeof value === 'string' ? value : decoder.decode(value);
+          const decodedChunks = lastIncompleteChunk + decodedValue;
+          const chunks = decodedChunks.split('\n');
+          lastIncompleteChunk = chunks.pop() ?? '';
 
-        const jsonChunks = chunks
-          .filter((line) => line.trim() !== '')
-          .map((line) => {
-            try {
-              return JSON.parse(line) as RSCPayloadChunk;
-            } catch (error) {
-              console.error('Error parsing JSON:', line, error);
-              throw error;
-            }
-          });
+          const jsonChunks = chunks
+            .filter((line) => line.trim() !== '')
+            .map((line) => {
+              try {
+                return JSON.parse(line) as RSCPayloadChunk;
+              } catch (error) {
+                console.error('Error parsing JSON:', line, error);
+                throw error;
+              }
+            });
 
-        for (const jsonChunk of jsonChunks) {
-          handleJsonChunk(jsonChunk);
-        }
+          for (const jsonChunk of jsonChunks) {
+            handleJsonChunk(jsonChunk);
+          }
 
-        // eslint-disable-next-line no-await-in-loop
-        ({ value, done } = await reader.read());
+          // eslint-disable-next-line no-await-in-loop
+          ({ value, done } = await reader.read());
+        }
+      } catch (error) {
+        console.error('Error transforming RSC stream:', error);
+        controller.error(error);
+      } finally {
+        controller.close();
       }
-      controller.close();
     },
   });
 }
diff --git a/node_package/src/utils.ts b/node_package/src/utils.ts
index 3d633d7c8f..09855a3c3d 100644
--- a/node_package/src/utils.ts
+++ b/node_package/src/utils.ts
@@ -19,3 +19,19 @@ export const createRSCPayloadKey = (
 ) => {
   return `${componentName}-${JSON.stringify(componentProps)}-${railsContext.componentSpecificMetadata.renderRequestId}`;
 };
+
+/**
+ * Wraps a promise from react-server-dom-webpack in a standard JavaScript Promise.
+ *
+ * This is necessary because promises returned by react-server-dom-webpack's methods
+ * (like `createFromReadableStream` and `createFromNodeStream`) have non-standard behavior:
+ * their `then()` method returns `null` instead of the promise itself, which breaks
+ * promise chaining. This wrapper creates a new standard Promise that properly
+ * forwards the resolution/rejection of the original promise.
+ */
+export const wrapInNewPromise = <T>(promise: Promise<T>) => {
+  return new Promise<T>((resolve, reject) => {
+    void promise.then(resolve);
+    void promise.catch(reject);
+  });
+};

From 11e4a54cbe581aa6d8d5291b6bddd54683437b95 Mon Sep 17 00:00:00 2001
From: Abanoub Ghadban <abanoub@shakacode.com>
Date: Sat, 24 May 2025 19:42:45 +0300
Subject: [PATCH 47/50] refactor: make serverSideRSCPayloadParameters optional
 in RailsContextWithServerComponentCapabilities for improved flexibility

---
 node_package/src/types/index.ts | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/node_package/src/types/index.ts b/node_package/src/types/index.ts
index 95c6ef54e9..10a10b44ee 100644
--- a/node_package/src/types/index.ts
+++ b/node_package/src/types/index.ts
@@ -71,7 +71,7 @@ export type RailsContextWithComponentSpecificMetadata = RailsContext & {
 
 export type RailsContextWithServerComponentCapabilities = RailsContextWithComponentSpecificMetadata & {
   serverSide: true;
-  serverSideRSCPayloadParameters: unknown;
+  serverSideRSCPayloadParameters?: unknown;
   reactClientManifestFileName: string;
   reactServerClientManifestFileName: string;
 };
@@ -95,7 +95,6 @@ export const assertRailsContextWithServerComponentCapabilities: (
 ): asserts context is RailsContextWithServerComponentCapabilities => {
   if (
     !context ||
-    !('serverSideRSCPayloadParameters' in context) ||
     !('reactClientManifestFileName' in context) ||
     !('reactServerClientManifestFileName' in context) ||
     !('componentSpecificMetadata' in context)

From bc4b9dabb6eb08206fb84021485cf12b22d5bf73 Mon Sep 17 00:00:00 2001
From: Abanoub Ghadban <abanoub@shakacode.com>
Date: Wed, 28 May 2025 13:08:23 +0300
Subject: [PATCH 48/50] handle error happen during rsc payload generation

---
 node_package/src/ReactOnRailsRSC.ts  | 72 +++++++++++++---------------
 node_package/src/handleError.ts      |  4 +-
 node_package/src/injectRSCPayload.ts |  3 +-
 3 files changed, 39 insertions(+), 40 deletions(-)

diff --git a/node_package/src/ReactOnRailsRSC.ts b/node_package/src/ReactOnRailsRSC.ts
index cbe59af665..4d06b92286 100644
--- a/node_package/src/ReactOnRailsRSC.ts
+++ b/node_package/src/ReactOnRailsRSC.ts
@@ -1,6 +1,6 @@
 import { BundleManifest } from 'react-on-rails-rsc';
 import { buildServerRenderer } from 'react-on-rails-rsc/server.node';
-import { PassThrough, Readable } from 'stream';
+import { Readable } from 'stream';
 
 import {
   RSCRenderParams,
@@ -9,9 +9,8 @@ import {
   StreamableComponentResult,
 } from './types/index.ts';
 import ReactOnRails from './ReactOnRails.full.ts';
-import buildConsoleReplay from './buildConsoleReplay.ts';
 import handleError from './handleError.ts';
-import { convertToError, createResultObject } from './serverRenderUtils.ts';
+import { convertToError } from './serverRenderUtils.ts';
 import { notifySSREnd, addPostSSRHook } from './postSSRHooks.ts';
 
 import {
@@ -20,13 +19,6 @@ import {
 } from './streamServerRenderedReactComponent.ts';
 import loadJsonFile from './loadJsonFile.ts';
 
-const stringToStream = (str: string) => {
-  const stream = new PassThrough();
-  stream.push(str);
-  stream.push(null);
-  return stream;
-};
-
 let serverRenderer: ReturnType<typeof buildServerRenderer> | undefined;
 
 const streamRenderRSCComponent = (
@@ -44,37 +36,41 @@ const streamRenderRSCComponent = (
     isShellReady: true,
   };
 
-  const { pipeToTransform, readableStream, emitError } =
+  const { pipeToTransform, readableStream, emitError, writeChunk, endStream } =
     transformRenderStreamChunksToResultObject(renderState);
-  Promise.resolve(reactRenderingResult)
-    .then(async (reactElement) => {
-      if (!serverRenderer) {
-        const reactClientManifest = await loadJsonFile<BundleManifest>(reactClientManifestFileName);
-        serverRenderer = buildServerRenderer(reactClientManifest);
-      }
 
-      const { renderToPipeableStream } = serverRenderer;
-      const rscStream = renderToPipeableStream(reactElement, {
-        onError: (err) => {
-          const error = convertToError(err);
-          console.error('Error in RSC stream', error);
-          if (throwJsErrors) {
-            emitError(error);
-          }
-          renderState.hasErrors = true;
-          renderState.error = error;
-        },
-      });
-      pipeToTransform(rscStream);
-    })
-    .catch((e: unknown) => {
-      const error = convertToError(e);
-      renderState.hasErrors = true;
-      renderState.error = error;
-      const htmlResult = handleError({ e: error, name: options.name, serverSide: true });
-      const jsonResult = JSON.stringify(createResultObject(htmlResult, buildConsoleReplay(), renderState));
-      return stringToStream(jsonResult);
+  const reportError = (error: Error) => {
+    console.error('Error in RSC stream', error);
+    if (throwJsErrors) {
+      emitError(error);
+    }
+    renderState.hasErrors = true;
+    renderState.error = error;
+  };
+
+  const initializeAndRender = async () => {
+    if (!serverRenderer) {
+      const reactClientManifest = await loadJsonFile<BundleManifest>(reactClientManifestFileName);
+      serverRenderer = buildServerRenderer(reactClientManifest);
+    }
+
+    const { renderToPipeableStream } = serverRenderer;
+    const rscStream = renderToPipeableStream(await reactRenderingResult, {
+      onError: (err) => {
+        const error = convertToError(err);
+        reportError(error);
+      },
     });
+    pipeToTransform(rscStream);
+  };
+
+  initializeAndRender().catch((e: unknown) => {
+    const error = convertToError(e);
+    reportError(error);
+    const errorHtml = handleError({ e: error, name: options.name, serverSide: true });
+    writeChunk(errorHtml);
+    endStream();
+  });
 
   readableStream.on('end', () => {
     notifySSREnd(railsContext);
diff --git a/node_package/src/handleError.ts b/node_package/src/handleError.ts
index 4884f6d394..eb9c3b12c9 100644
--- a/node_package/src/handleError.ts
+++ b/node_package/src/handleError.ts
@@ -59,8 +59,10 @@ Message: ${e.message}
 
 ${e.stack}`;
 
-    const reactElement = React.createElement('pre', null, msg);
+    // In RSC (React Server Components) bundles, renderToString is not available.
+    // Therefore, we return the raw error message as a string instead of converting it to HTML.
     if (typeof renderToString === 'function') {
+      const reactElement = React.createElement('pre', null, msg);
       return renderToString(reactElement);
     }
     return msg;
diff --git a/node_package/src/injectRSCPayload.ts b/node_package/src/injectRSCPayload.ts
index 6bec64cd00..b2f43e8919 100644
--- a/node_package/src/injectRSCPayload.ts
+++ b/node_package/src/injectRSCPayload.ts
@@ -1,5 +1,6 @@
 import { PassThrough, Transform } from 'stream';
 import { finished } from 'stream/promises';
+import { createRSCPayloadKey } from './utils.ts';
 import { RailsContextWithServerComponentCapabilities, PipeableOrReadableStream } from './types/index.ts';
 
 // In JavaScript, when an escape sequence with a backslash (\) is followed by a character
@@ -66,7 +67,7 @@ export default function injectRSCPayload(
 
       ReactOnRails.onRSCPayloadGenerated?.(railsContext, (streamInfo) => {
         const { stream, props, componentName } = streamInfo;
-        const cacheKey = `${componentName}-${JSON.stringify(props)}-${railsContext.componentSpecificMetadata?.renderRequestId}`;
+        const cacheKey = createRSCPayloadKey(componentName, props, railsContext);
 
         // When a component requests an RSC payload, we initialize a global array to store it.
         // This array is injected into the HTML before the component's HTML markup.

From 3f5fb26f02951bcc6d75e885a56de5924a1d39eb Mon Sep 17 00:00:00 2001
From: Abanoub Ghadban <abanoub@shakacode.com>
Date: Sat, 7 Jun 2025 14:18:59 +0300
Subject: [PATCH 49/50] add rsc payload url to context only if rsc support
 enabled

---
 lib/react_on_rails/helper.rb | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)

diff --git a/lib/react_on_rails/helper.rb b/lib/react_on_rails/helper.rb
index 22daeee233..4be2a48ed5 100644
--- a/lib/react_on_rails/helper.rb
+++ b/lib/react_on_rails/helper.rb
@@ -362,10 +362,6 @@ def json_safe_and_pretty(hash_or_string)
     def rails_context(server_side: true)
       # ALERT: Keep in sync with node_package/src/types/index.ts for the properties of RailsContext
       @rails_context ||= begin
-        rsc_url = if ReactOnRails::Utils.react_on_rails_pro?
-                    ReactOnRailsPro.configuration.rsc_payload_generation_url_path
-                  end
-
         result = {
           componentRegistryTimeout: ReactOnRails.configuration.component_registry_timeout,
           railsEnv: Rails.env,
@@ -381,7 +377,10 @@ def rails_context(server_side: true)
         if ReactOnRails::Utils.react_on_rails_pro?
           result[:rorProVersion] = ReactOnRails::Utils.react_on_rails_pro_version
 
-          result[:rscPayloadGenerationUrlPath] = rsc_url if ReactOnRails::Utils.rsc_support_enabled?
+          if ReactOnRails::Utils.rsc_support_enabled?
+            rsc_payload_url = ReactOnRailsPro.configuration.rsc_payload_generation_url_path
+            result[:rscPayloadGenerationUrlPath] = rsc_payload_url
+          end
         end
 
         if defined?(request) && request.present?

From 1fccd8cb87a0b81a6a85b443de7821805d026f38 Mon Sep 17 00:00:00 2001
From: Abanoub Ghadban <abanoub@shakacode.com>
Date: Sat, 7 Jun 2025 14:27:12 +0300
Subject: [PATCH 50/50] removed unneeded rubocop disable statement

---
 lib/react_on_rails/helper.rb | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/lib/react_on_rails/helper.rb b/lib/react_on_rails/helper.rb
index 4be2a48ed5..10c0c9818d 100644
--- a/lib/react_on_rails/helper.rb
+++ b/lib/react_on_rails/helper.rb
@@ -358,7 +358,7 @@ def json_safe_and_pretty(hash_or_string)
     # second parameter passed to both component and store Render-Functions.
     # This method can be called from views and from the controller, as `helpers.rails_context`
     #
-    # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+    # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity
     def rails_context(server_side: true)
       # ALERT: Keep in sync with node_package/src/types/index.ts for the properties of RailsContext
       @rails_context ||= begin
@@ -438,7 +438,7 @@ def load_pack_for_generated_component(react_component_name, render_options)
       append_stylesheet_pack_tag("generated/#{react_component_name}")
     end
 
-    # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+    # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity
 
     private