initialize the rsc payload array in a sync manner when the generate rsc function is called to avoid hydration race conditions

Author: AbanoubGhadban

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));
 

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,26 +38,36 @@ 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>[] = [];
 
       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;
     }

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();
     },
   });

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

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>
   );