feat: implement post-SSR hooks for enhanced server-side rendering control and update package dependencies

Author: AbanoubGhadban

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

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

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

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

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

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

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 = {

package.json

@@ -52,7 +52,6 @@
     "eslint-plugin-prettier": "^5.2.3",
     "eslint-plugin-react": "^7.37.4",
     "eslint-plugin-react-hooks": "^5.2.0",
-    "typescript-eslint": "^8.26.1",
     "globals": "^16.0.0",
     "jest": "^29.7.0",
     "jest-environment-jsdom": "^29.7.0",
@@ -68,7 +67,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.26.1"
   },
   "peerDependencies": {
     "react": ">= 16",