Refactor RSC component handling to improve payload key generation

AbanoubGhadban · AbanoubGhadban · commit 745753d155b6 · 2025-07-08T14:45:32.000+03:00
- Updated `createRSCPayloadKey` to remove `domNodeId` dependency for cache key generation.
- Modified `getReactServerComponent` functions to accept context parameters more cleanly.
- Enhanced documentation for clarity on function responsibilities and parameters.
- Adjusted `injectRSCPayload` to align with new cache key structure.
- Streamlined RSCProvider integration by removing unnecessary parameters.
diff --git 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 type { ClientGetReactServerComponentProps } from './getReactServerComponent.client.ts';
+import { createRSCPayloadKey } from './utils.ts';
 
 type RSCContextType = {
   getComponent: (componentName: string, componentProps: unknown) => Promise<React.ReactNode>;
@@ -30,13 +30,9 @@ const RSCContext = React.createContext<RSCContextType | undefined>(undefined);
  * for client-side rendering or 'react-on-rails/wrapServerComponentRenderer/server' for server-side rendering.
  */
 export const createRSCProvider = ({
-  railsContext,
   getServerComponent,
-  createRSCPayloadKey,
 }: {
-  railsContext: RailsContext;
-  getServerComponent: typeof getReactServerComponent;
-  createRSCPayloadKey: (componentName: string, componentProps: unknown) => string;
+  getServerComponent: (props: ClientGetReactServerComponentProps) => Promise<React.ReactNode>;
 }) => {
   const fetchRSCPromises: Record<string, Promise<React.ReactNode>> = {};
 
@@ -46,7 +42,7 @@ export const createRSCProvider = ({
       return fetchRSCPromises[key];
     }
 
-    const promise = getServerComponent({ componentName, componentProps, railsContext, createRSCPayloadKey });
+    const promise = getServerComponent({ componentName, componentProps });
     fetchRSCPromises[key] = promise;
     return promise;
   };
@@ -56,9 +52,7 @@ export const createRSCProvider = ({
     const promise = getServerComponent({
       componentName,
       componentProps,
-      railsContext,
       enforceRefetch: true,
-      createRSCPayloadKey,
     });
     fetchRSCPromises[key] = promise;
     return promise;
diff --git a/node_package/src/RSCRequestTracker.ts b/node_package/src/RSCRequestTracker.ts
@@ -5,6 +5,15 @@ import {
   RailsContextWithServerComponentMetadata,
 } from './types/index.ts';
 
+/**
+ * Global function provided by React on Rails Pro for generating RSC payloads.
+ *
+ * This function is injected into the global scope during server-side rendering
+ * by the RORP rendering request. It handles the actual generation of React Server
+ * Component payloads on the server side.
+ *
+ * @see https://github.com/shakacode/react_on_rails_pro/blob/master/lib/react_on_rails_pro/server_rendering_js_code.rb
+ */
 declare global {
   function generateRSCPayload(
     componentName: string,
diff --git 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 { fetch, wrapInNewPromise } from './utils.ts';
+import { createRSCPayloadKey, fetch, wrapInNewPromise } from './utils.ts';
 import transformRSCStreamAndReplayConsoleLogs from './transformRSCStreamAndReplayConsoleLogs.ts';
 import { RailsContext } from './types/index.ts';
 
@@ -10,12 +10,10 @@ declare global {
   }
 }
 
-type ClientGetReactServerComponentProps = {
+export type ClientGetReactServerComponentProps = {
   componentName: string;
   componentProps: unknown;
-  railsContext: RailsContext;
   enforceRefetch?: boolean;
-  createRSCPayloadKey: (componentName: string, componentProps: unknown) => string;
 };
 
 const createFromFetch = async (fetchPromise: Promise<Response>) => {
@@ -40,11 +38,16 @@ const createFromFetch = async (fetchPromise: Promise<Response>) => {
  * 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
+ * @param props - Object containing component name and props
+ * @param railsContext - The Rails context containing configuration
  * @returns A Promise resolving to the rendered React element
  * @throws Error if RSC payload generation URL path is not configured or network request fails
  */
-const fetchRSC = ({ componentName, componentProps, railsContext }: ClientGetReactServerComponentProps) => {
+const fetchRSC = ({
+  componentName,
+  componentProps,
+  railsContext,
+}: ClientGetReactServerComponentProps & { railsContext: RailsContext }) => {
   const { rscPayloadGenerationUrlPath } = railsContext;
 
   if (!rscPayloadGenerationUrlPath) {
@@ -131,41 +134,48 @@ const createFromPreloadedPayloads = (payloads: string[]) => {
 };
 
 /**
- * Fetches and renders a server component on the client side.
+ * Creates a function that 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
+ * This style of higher-order function is necessary as the function that gets server components
+ * on server has different parameters than the function that gets them on client. The environment
+ * dependent parameters (domNodeId, railsContext) are passed from the `wrapServerComponentRenderer`
+ * function, while the environment agnostic parameters (componentName, componentProps, enforceRefetch)
+ * are passed from the RSCProvider which is environment agnostic.
+ *
+ * The returned function:
+ * 1. Checks for embedded RSC payloads in window.REACT_ON_RAILS_RSC_PAYLOADS using the domNodeId
  * 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 domNodeId - The DOM node ID to create a unique key for the RSC payload store
+ * @param railsContext - Context for the current request, shared across all components
+ * @returns A function that accepts RSC parameters and returns a Promise resolving to the rendered React element
+ *
+ * The returned function accepts:
  * @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
  * @param enforceRefetch - Whether to enforce a refetch of the component
- * @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 refetchComponent 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,
-  railsContext,
-  enforceRefetch = false,
-  createRSCPayloadKey,
-}: ClientGetReactServerComponentProps) => {
-  const componentKey = createRSCPayloadKey(componentName, componentProps);
-  const payloads = window.REACT_ON_RAILS_RSC_PAYLOADS?.[componentKey];
-  if (!enforceRefetch && payloads) {
-    return createFromPreloadedPayloads(payloads);
-  }
-  return fetchRSC({ componentName, componentProps, railsContext, createRSCPayloadKey });
-};
+const getReactServerComponent =
+  (domNodeId: string, railsContext: RailsContext) =>
+  ({ componentName, componentProps, enforceRefetch = false }: ClientGetReactServerComponentProps) => {
+    const componentCacheKey = createRSCPayloadKey(componentName, componentProps);
+
+    const rscPayloadKey = `${componentCacheKey}-${domNodeId}`;
+    const payloads = window.REACT_ON_RAILS_RSC_PAYLOADS?.[rscPayloadKey];
+    if (!enforceRefetch && payloads) {
+      return createFromPreloadedPayloads(payloads);
+    }
+    return fetchRSC({ componentName, componentProps, railsContext });
+  };
 
 export default getReactServerComponent;
diff --git a/node_package/src/getReactServerComponent.server.ts b/node_package/src/getReactServerComponent.server.ts
@@ -2,12 +2,11 @@ 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 { assertRailsContextWithServerStreamingCapabilities, RailsContext } from './types/index.ts';
+import type { RailsContextWithServerStreamingCapabilities } from './types/index.ts';
 
 type GetReactServerComponentOnServerProps = {
   componentName: string;
   componentProps: unknown;
-  railsContext: RailsContext;
 };
 
 let clientRendererPromise: Promise<ReturnType<typeof buildClientRenderer>> | undefined;
@@ -37,9 +36,15 @@ const createFromReactOnRailsNodeStream = async (
 };
 
 /**
- * Fetches and renders a server component on the server side.
+ * Creates a function that fetches and renders a server component on the server side.
  *
- * This function:
+ * This style of higher-order function is necessary as the function that gets server components
+ * on server has different parameters than the function that gets them on client. The environment
+ * dependent parameters (railsContext) are passed from the `wrapServerComponentRenderer`
+ * function, while the environment agnostic parameters (componentName, componentProps) are
+ * passed from the RSCProvider which is environment agnostic.
+ *
+ * The returned 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
@@ -49,31 +54,28 @@ const createFromReactOnRailsNodeStream = async (
  * - Used to render the server component
  * - Tracked so it can be embedded in the HTML response
  *
+ * @param railsContext - Context for the current request with server streaming capabilities
+ * @returns A function that accepts RSC parameters and returns a Promise resolving to the rendered React element
+ *
+ * The returned function accepts:
  * @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
- * @param enforceRefetch - Whether to enforce a refetch of the component
- * @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 refetchComponent 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,
-  railsContext,
-}: GetReactServerComponentOnServerProps) => {
-  assertRailsContextWithServerStreamingCapabilities(railsContext);
+const getReactServerComponent =
+  (railsContext: RailsContextWithServerStreamingCapabilities) =>
+  async ({ componentName, componentProps }: GetReactServerComponentOnServerProps) => {
+    const rscPayloadStream = await railsContext.getRSCPayloadStream(componentName, componentProps);
 
-  const rscPayloadStream = await railsContext.getRSCPayloadStream(componentName, componentProps);
-
-  return createFromReactOnRailsNodeStream(
-    rscPayloadStream,
-    railsContext.reactServerClientManifestFileName,
-    railsContext.reactClientManifestFileName,
-  );
-};
+    return createFromReactOnRailsNodeStream(
+      rscPayloadStream,
+      railsContext.reactServerClientManifestFileName,
+      railsContext.reactClientManifestFileName,
+    );
+  };
 
 export default getReactServerComponent;
diff --git a/node_package/src/injectRSCPayload.ts b/node_package/src/injectRSCPayload.ts
@@ -210,23 +210,24 @@ export default function injectRSCPayload(
 
       rscRequestTracker.onRSCPayloadGenerated((streamInfo) => {
         const { stream, props, componentName } = streamInfo;
-        const cacheKey = createRSCPayloadKey(componentName, props, domNodeId);
+        const cacheKey = createRSCPayloadKey(componentName, props);
+        const rscPayloadKey = `${cacheKey}-${domNodeId}`;
 
         // CRITICAL TIMING: Initialize global array IMMEDIATELY when component requests RSC
         // This ensures the array exists before the component's HTML is rendered and sent.
         // Client-side hydration depends on this array being present in the page.
         //
         // The initialization script creates: (self.REACT_ON_RAILS_RSC_PAYLOADS||={})[cacheKey]||=[]
         // This creates a global array that the client-side RSCProvider monitors for new chunks.
-        const initializationScript = createRSCPayloadInitializationScript(cacheKey);
+        const initializationScript = createRSCPayloadInitializationScript(rscPayloadKey);
         rscInitializationBuffers.push(Buffer.from(initializationScript));
 
         // Process RSC payload stream asynchronously
         rscPromises.push(
           (async () => {
             for await (const chunk of stream ?? []) {
               const decodedChunk = typeof chunk === 'string' ? chunk : decoder.decode(chunk);
-              const payloadScript = createRSCPayloadChunk(decodedChunk, cacheKey);
+              const payloadScript = createRSCPayloadChunk(decodedChunk, rscPayloadKey);
               rscPayloadBuffers.push(Buffer.from(payloadScript));
               scheduleFlush();
             }
diff --git a/node_package/src/utils.ts b/node_package/src/utils.ts
@@ -11,38 +11,18 @@ const customFetch = (...args: Parameters<typeof fetch>) => {
 export { customFetch as fetch };
 
 /**
- * Creates a unique cache key for RSC payloads to prevent collisions between component instances.
+ * Creates a unique cache key for RSC payloads.
  *
  * This function generates cache keys that ensure:
  * 1. Different components have different keys
  * 2. Same components with different props have different keys
- * 3. Multiple instances of the same component on the same rails view have different keys
  *
  * @param componentName - Name of the React Server Component
  * @param componentProps - Props passed to the component (serialized to JSON)
- * @param domNodeId - DOM node ID of the parent react component rendered at the rails view (prevents instance collisions)
  * @returns A unique cache key string
- * @throws Error if domNodeId is missing, which could lead to cache collisions
  */
-export const createRSCPayloadKey = (
-  componentName: string,
-  componentProps: unknown,
-  domNodeId: string | undefined,
-) => {
-  if (!domNodeId) {
-    const errorMessage =
-      'domNodeId is required when using React Server Components to ensure unique RSC payload caching ' +
-      'and prevent conflicts between multiple instances of the same component at the same rails view. ' +
-      'This could lead to incorrect hydration and component state issues.';
-
-    if (process.env.NODE_ENV === 'development') {
-      throw new Error(`RSC Cache Key Error: ${errorMessage}`);
-    } else {
-      console.warn(`Warning: ${errorMessage}`);
-    }
-  }
-
-  return `${componentName}-${JSON.stringify(componentProps)}-${domNodeId}`;
+export const createRSCPayloadKey = (componentName: string, componentProps: unknown) => {
+  return `${componentName}-${JSON.stringify(componentProps)}`;
 };
 
 /**
@@ -60,3 +40,5 @@ export const wrapInNewPromise = <T>(promise: Promise<T>) => {
     void promise.catch(reject);
   });
 };
+
+export const 
diff --git a/node_package/src/wrapServerComponentRenderer/client.tsx b/node_package/src/wrapServerComponentRenderer/client.tsx
@@ -4,7 +4,6 @@ import { ReactComponentOrRenderFunction, RenderFunction } from '../types/index.t
 import isRenderFunction from '../isRenderFunction.ts';
 import { ensureReactUseAvailable } from '../reactApis.cts';
 import { createRSCProvider } from '../RSCProvider.tsx';
-import { createRSCPayloadKey } from '../utils.ts';
 import getReactServerComponent from '../getReactServerComponent.client.ts';
 
 ensureReactUseAvailable();
@@ -55,10 +54,7 @@ const wrapServerComponentRenderer = (componentOrRenderFunction: ReactComponentOr
     }
 
     const RSCProvider = createRSCProvider({
-      railsContext,
-      getServerComponent: getReactServerComponent,
-      createRSCPayloadKey: (componentName, componentProps) =>
-        createRSCPayloadKey(componentName, componentProps, domNodeId),
+      getServerComponent: getReactServerComponent(domNodeId, railsContext),
     });
 
     const root = (
diff --git a/node_package/src/wrapServerComponentRenderer/server.tsx b/node_package/src/wrapServerComponentRenderer/server.tsx
@@ -4,7 +4,6 @@ import getReactServerComponent from '../getReactServerComponent.server.ts';
 import { createRSCProvider } from '../RSCProvider.tsx';
 import isRenderFunction from '../isRenderFunction.ts';
 import { assertRailsContextWithServerStreamingCapabilities } from '../types/index.ts';
-import { createRSCPayloadKey } from '../utils.ts';
 
 /**
  * Wraps a client component with the necessary RSC context and handling for server-side operations.
@@ -42,13 +41,7 @@ const wrapServerComponentRenderer = (componentOrRenderFunction: ReactComponentOr
     }
 
     const RSCProvider = createRSCProvider({
-      railsContext,
-      getServerComponent: getReactServerComponent,
-      // Server-side rendering processes each component in isolation during separate requests,
-      // eliminating the possibility of cache key conflicts between component instances.
-      // Therefore, we can safely use `server` as the domNodeId parameter.
-      createRSCPayloadKey: (componentName, componentProps) =>
-        createRSCPayloadKey(componentName, componentProps, 'server'),
+      getServerComponent: getReactServerComponent(railsContext),
     });
 
     return () => (
