react-on-rails-pro 16.7.0-rc.3 → 17.0.0-rc.0

package/lib/ReactOnRailsRSC.d.ts

@@ -1,4 +1,6 @@
 declare const ReactOnRails: import("react-on-rails/types").ReactOnRailsInternal;
 export * from 'react-on-rails/types';
+export { unstable_cache, registerCacheHandler } from './cache/index.ts';
+export type { CacheHandler, CacheEntry, UnstableCacheOptions } from './cache/index.ts';
 export default ReactOnRails;
 //# sourceMappingURL=ReactOnRailsRSC.d.ts.map

package/lib/ReactOnRailsRSC.js

@@ -17,5 +17,6 @@ import createReactOnRailsPro from "./createReactOnRailsPro.js";
 const currentGlobal = globalThis.ReactOnRails || null;
 const ReactOnRails = createReactOnRailsPro([createSSRCapability(), createProRSCCapability()], currentGlobal);
 export * from 'react-on-rails/types';
+export { unstable_cache, registerCacheHandler } from "./cache/index.js"; // eslint-disable-line camelcase -- matches Next.js API naming convention
 export default ReactOnRails;
 //# sourceMappingURL=ReactOnRailsRSC.js.map

package/lib/cache/CacheHandler.d.ts

@@ -0,0 +1,10 @@
+export interface CacheEntry {
+    value: Buffer[];
+    revalidate: number;
+    timestamp: number;
+}
+export interface CacheHandler {
+    get(key: string): Promise<CacheEntry | null>;
+    set(key: string, entry: CacheEntry): Promise<void>;
+}
+//# sourceMappingURL=CacheHandler.d.ts.map

package/lib/cache/CacheHandler.js

@@ -0,0 +1,15 @@
+/*
+ * Copyright (c) 2025 Shakacode LLC
+ *
+ * This file is NOT licensed under the MIT (open source) license.
+ * It is part of the React on Rails Pro offering and is licensed separately.
+ *
+ * Unauthorized copying, modification, distribution, or use of this file,
+ * via any medium, is strictly prohibited without a valid license agreement
+ * from Shakacode LLC.
+ *
+ * For licensing terms, please see:
+ * https://github.com/shakacode/react_on_rails/blob/master/REACT-ON-RAILS-PRO-LICENSE.md
+ */
+export {};
+//# sourceMappingURL=CacheHandler.js.map

package/lib/cache/InMemoryLRUCacheHandler.d.ts

@@ -0,0 +1,9 @@
+import type { CacheEntry, CacheHandler } from './CacheHandler.ts';
+export declare class InMemoryLRUCacheHandler implements CacheHandler {
+    private cache;
+    private maxEntries;
+    constructor(maxEntries?: number);
+    get(key: string): Promise<CacheEntry | null>;
+    set(key: string, entry: CacheEntry): Promise<void>;
+}
+//# sourceMappingURL=InMemoryLRUCacheHandler.d.ts.map

package/lib/cache/InMemoryLRUCacheHandler.js

@@ -0,0 +1,50 @@
+/*
+ * Copyright (c) 2025 Shakacode LLC
+ *
+ * This file is NOT licensed under the MIT (open source) license.
+ * It is part of the React on Rails Pro offering and is licensed separately.
+ *
+ * Unauthorized copying, modification, distribution, or use of this file,
+ * via any medium, is strictly prohibited without a valid license agreement
+ * from Shakacode LLC.
+ *
+ * For licensing terms, please see:
+ * https://github.com/shakacode/react_on_rails/blob/master/REACT-ON-RAILS-PRO-LICENSE.md
+ */
+// eslint-disable-next-line import/prefer-default-export -- designed for named import alongside the interface
+export class InMemoryLRUCacheHandler {
+    constructor(maxEntries = 1000) {
+        this.cache = new Map();
+        this.maxEntries = maxEntries;
+    }
+    // eslint-disable-next-line @typescript-eslint/require-await -- CacheHandler interface is async for remote implementations
+    async get(key) {
+        const entry = this.cache.get(key);
+        if (!entry)
+            return null;
+        if (entry.revalidate > 0 && Date.now() - entry.timestamp > entry.revalidate * 1000) {
+            this.cache.delete(key);
+            return null;
+        }
+        // Move to end (most-recently-used) by re-inserting
+        this.cache.delete(key);
+        this.cache.set(key, entry);
+        return entry;
+    }
+    // eslint-disable-next-line @typescript-eslint/require-await
+    async set(key, entry) {
+        // If key already exists, remove it first so re-insert goes to end
+        if (this.cache.has(key)) {
+            this.cache.delete(key);
+        }
+        // Evict oldest (first) entry if at capacity
+        if (this.cache.size >= this.maxEntries) {
+            const oldestKey = this.cache.keys().next().value;
+            if (oldestKey !== undefined) {
+                this.cache.delete(oldestKey);
+            }
+        }
+        this.cache.set(key, entry);
+    }
+}
+//# sourceMappingURL=InMemoryLRUCacheHandler.js.map

package/lib/cache/buildCacheKey.d.ts

@@ -0,0 +1,2 @@
+export declare function buildCacheKey(buildId: string, id: string, args: unknown[]): string;
+//# sourceMappingURL=buildCacheKey.d.ts.map

package/lib/cache/buildCacheKey.js

@@ -0,0 +1,25 @@
+/*
+ * Copyright (c) 2025 Shakacode LLC
+ *
+ * This file is NOT licensed under the MIT (open source) license.
+ * It is part of the React on Rails Pro offering and is licensed separately.
+ *
+ * Unauthorized copying, modification, distribution, or use of this file,
+ * via any medium, is strictly prohibited without a valid license agreement
+ * from Shakacode LLC.
+ *
+ * For licensing terms, please see:
+ * https://github.com/shakacode/react_on_rails/blob/master/REACT-ON-RAILS-PRO-LICENSE.md
+ */
+import { createHash } from 'crypto';
+// eslint-disable-next-line import/prefer-default-export -- will grow with additional key utilities
+export function buildCacheKey(buildId, id, args) {
+    const hash = createHash('sha256');
+    hash.update(buildId);
+    hash.update(':');
+    hash.update(id);
+    hash.update(':');
+    hash.update(JSON.stringify(args));
+    return `rorp:rsc-cache:${hash.digest('hex')}`;
+}
+//# sourceMappingURL=buildCacheKey.js.map

package/lib/cache/buildIdProvider.d.ts

@@ -0,0 +1,3 @@
+export declare function setBuildId(id: string): void;
+export declare function getBuildId(): string;
+//# sourceMappingURL=buildIdProvider.d.ts.map

package/lib/cache/buildIdProvider.js

@@ -0,0 +1,25 @@
+/*
+ * Copyright (c) 2025 Shakacode LLC
+ *
+ * This file is NOT licensed under the MIT (open source) license.
+ * It is part of the React on Rails Pro offering and is licensed separately.
+ *
+ * Unauthorized copying, modification, distribution, or use of this file,
+ * via any medium, is strictly prohibited without a valid license agreement
+ * from Shakacode LLC.
+ *
+ * For licensing terms, please see:
+ * https://github.com/shakacode/react_on_rails/blob/master/REACT-ON-RAILS-PRO-LICENSE.md
+ */
+let buildId;
+export function setBuildId(id) {
+    buildId = id;
+}
+export function getBuildId() {
+    if (!buildId) {
+        throw new Error('BUILD_ID not set. Ensure unstable_cache is used within a React Server Component render context. ' +
+            'The BUILD_ID is initialized from rscBundleHash during the first render request.');
+    }
+    return buildId;
+}
+//# sourceMappingURL=buildIdProvider.js.map

package/lib/cache/cacheHandlerRegistry.d.ts

@@ -0,0 +1,4 @@
+import type { CacheHandler } from './CacheHandler.ts';
+export declare function registerCacheHandler(kind: string, handler: CacheHandler): void;
+export declare function getCacheHandler(kind: string): CacheHandler;
+//# sourceMappingURL=cacheHandlerRegistry.d.ts.map

package/lib/cache/cacheHandlerRegistry.js

@@ -0,0 +1,29 @@
+/*
+ * Copyright (c) 2025 Shakacode LLC
+ *
+ * This file is NOT licensed under the MIT (open source) license.
+ * It is part of the React on Rails Pro offering and is licensed separately.
+ *
+ * Unauthorized copying, modification, distribution, or use of this file,
+ * via any medium, is strictly prohibited without a valid license agreement
+ * from Shakacode LLC.
+ *
+ * For licensing terms, please see:
+ * https://github.com/shakacode/react_on_rails/blob/master/REACT-ON-RAILS-PRO-LICENSE.md
+ */
+import { InMemoryLRUCacheHandler } from "./InMemoryLRUCacheHandler.js";
+const handlers = new Map();
+handlers.set('default', new InMemoryLRUCacheHandler());
+export function registerCacheHandler(kind, handler) {
+    handlers.set(kind, handler);
+}
+export function getCacheHandler(kind) {
+    const handler = handlers.get(kind);
+    if (!handler) {
+        throw new Error(`No CacheHandler registered for kind "${kind}". ` +
+            `Available kinds: ${[...handlers.keys()].join(', ')}. ` +
+            'Register a handler with registerCacheHandler(kind, handler).');
+    }
+    return handler;
+}
+//# sourceMappingURL=cacheHandlerRegistry.js.map

package/lib/cache/index.d.ts

@@ -0,0 +1,5 @@
+export { unstable_cache } from './unstable_cache.ts';
+export type { UnstableCacheOptions } from './unstable_cache.ts';
+export type { CacheHandler, CacheEntry } from './CacheHandler.ts';
+export { registerCacheHandler } from './cacheHandlerRegistry.ts';
+//# sourceMappingURL=index.d.ts.map

package/lib/cache/index.js

@@ -0,0 +1,17 @@
+/*
+ * Copyright (c) 2025 Shakacode LLC
+ *
+ * This file is NOT licensed under the MIT (open source) license.
+ * It is part of the React on Rails Pro offering and is licensed separately.
+ *
+ * Unauthorized copying, modification, distribution, or use of this file,
+ * via any medium, is strictly prohibited without a valid license agreement
+ * from Shakacode LLC.
+ *
+ * For licensing terms, please see:
+ * https://github.com/shakacode/react_on_rails/blob/master/REACT-ON-RAILS-PRO-LICENSE.md
+ */
+/* eslint-disable camelcase -- matches Next.js API naming convention */
+export { unstable_cache } from "./unstable_cache.js";
+export { registerCacheHandler } from "./cacheHandlerRegistry.js";
+//# sourceMappingURL=index.js.map

package/lib/cache/index.stub.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Stub module for non-react-server contexts (e.g. SSR server bundle).
+ *
+ * The auto-load system includes .server.tsx files in both the RSC bundle
+ * and the SSR server bundle. The SSR bundle never executes server component
+ * code (it delegates to the RSC bundle), but webpack still needs to resolve
+ * all imports at build time. This stub satisfies that requirement.
+ */
+import type { ReactNode } from 'react';
+import type { CacheHandler, CacheEntry } from './CacheHandler.ts';
+export type { CacheHandler, CacheEntry };
+export interface UnstableCacheOptions {
+    id: string;
+    revalidate?: number;
+    kind?: string;
+}
+export declare function unstable_cache<TArgs extends unknown[]>(originalFn: (...args: TArgs) => Promise<ReactNode> | ReactNode, options: UnstableCacheOptions): (...args: TArgs) => Promise<ReactNode>;
+export declare function registerCacheHandler(kind: string, handler: CacheHandler): void;
+//# sourceMappingURL=index.stub.d.ts.map

package/lib/cache/index.stub.js

@@ -0,0 +1,25 @@
+/*
+ * Copyright (c) 2025 Shakacode LLC
+ *
+ * This file is NOT licensed under the MIT (open source) license.
+ * It is part of the React on Rails Pro offering and is licensed separately.
+ *
+ * Unauthorized copying, modification, distribution, or use of this file,
+ * via any medium, is strictly prohibited without a valid license agreement
+ * from Shakacode LLC.
+ *
+ * For licensing terms, please see:
+ * https://github.com/shakacode/react_on_rails/blob/master/REACT-ON-RAILS-PRO-LICENSE.md
+ */
+const STUB_ERROR = 'unstable_cache is only available in the react-server bundle. ' +
+    'It should not be called from the SSR server bundle or client bundle.';
+// eslint-disable-next-line camelcase -- matches Next.js API naming convention
+export function unstable_cache(originalFn, options) {
+    return () => {
+        throw new Error(STUB_ERROR);
+    };
+}
+export function registerCacheHandler(kind, handler) {
+    throw new Error(STUB_ERROR);
+}
+//# sourceMappingURL=index.stub.js.map

package/lib/cache/manifestLoader.d.ts

@@ -0,0 +1,5 @@
+import { buildClientRenderer } from 'react-on-rails-rsc/client.node';
+export declare function setManifestFileNames(clientManifest: string, serverClientManifest: string): void;
+export declare function getClientManifestFileName(): string | undefined;
+export declare function getClientRenderer(): Promise<ReturnType<typeof buildClientRenderer>>;
+//# sourceMappingURL=manifestLoader.d.ts.map

package/lib/cache/manifestLoader.js

@@ -0,0 +1,46 @@
+/*
+ * Copyright (c) 2025 Shakacode LLC
+ *
+ * This file is NOT licensed under the MIT (open source) license.
+ * It is part of the React on Rails Pro offering and is licensed separately.
+ *
+ * Unauthorized copying, modification, distribution, or use of this file,
+ * via any medium, is strictly prohibited without a valid license agreement
+ * from Shakacode LLC.
+ *
+ * For licensing terms, please see:
+ * https://github.com/shakacode/react_on_rails/blob/master/REACT-ON-RAILS-PRO-LICENSE.md
+ */
+import { buildClientRenderer } from 'react-on-rails-rsc/client.node';
+import loadJsonFile from "../loadJsonFile.js";
+let clientManifestFileName;
+let serverClientManifestFileName;
+let clientRendererPromise;
+export function setManifestFileNames(clientManifest, serverClientManifest) {
+    clientManifestFileName = clientManifest;
+    serverClientManifestFileName = serverClientManifest;
+}
+export function getClientManifestFileName() {
+    return clientManifestFileName;
+}
+export function getClientRenderer() {
+    if (!clientRendererPromise) {
+        if (!clientManifestFileName || !serverClientManifestFileName) {
+            throw new Error('Manifest file names not set. Ensure setManifestFileNames() is called before getClientRenderer(). ' +
+                'This is done automatically during the first RSC render request.');
+        }
+        const clientFile = clientManifestFileName;
+        const serverFile = serverClientManifestFileName;
+        clientRendererPromise = Promise.all([
+            loadJsonFile(serverFile),
+            loadJsonFile(clientFile),
+        ])
+            .then(([reactServerManifest, reactClientManifest]) => buildClientRenderer(reactClientManifest, reactServerManifest))
+            .catch((err) => {
+            clientRendererPromise = undefined;
+            throw err;
+        });
+    }
+    return clientRendererPromise;
+}
+//# sourceMappingURL=manifestLoader.js.map

package/lib/cache/manifestLoaderServer.d.ts

@@ -0,0 +1,3 @@
+import { buildServerRenderer } from 'react-on-rails-rsc/server.node';
+export declare function getServerRenderer(): Promise<ReturnType<typeof buildServerRenderer>>;
+//# sourceMappingURL=manifestLoaderServer.d.ts.map

package/lib/cache/manifestLoaderServer.js

@@ -0,0 +1,35 @@
+/*
+ * Copyright (c) 2025 Shakacode LLC
+ *
+ * This file is NOT licensed under the MIT (open source) license.
+ * It is part of the React on Rails Pro offering and is licensed separately.
+ *
+ * Unauthorized copying, modification, distribution, or use of this file,
+ * via any medium, is strictly prohibited without a valid license agreement
+ * from Shakacode LLC.
+ *
+ * For licensing terms, please see:
+ * https://github.com/shakacode/react_on_rails/blob/master/REACT-ON-RAILS-PRO-LICENSE.md
+ */
+import { buildServerRenderer } from 'react-on-rails-rsc/server.node';
+import loadJsonFile from "../loadJsonFile.js";
+import { getClientManifestFileName } from "./manifestLoader.js";
+let serverRendererPromise;
+// eslint-disable-next-line import/prefer-default-export -- named export for consistency with manifestLoader
+export function getServerRenderer() {
+    if (!serverRendererPromise) {
+        const clientManifest = getClientManifestFileName();
+        if (!clientManifest) {
+            throw new Error('Manifest file names not set. Ensure setManifestFileNames() is called before getServerRenderer(). ' +
+                'This is done automatically during the first RSC render request.');
+        }
+        serverRendererPromise = loadJsonFile(clientManifest)
+            .then((reactClientManifest) => buildServerRenderer(reactClientManifest))
+            .catch((err) => {
+            serverRendererPromise = undefined;
+            throw err;
+        });
+    }
+    return serverRendererPromise;
+}
+//# sourceMappingURL=manifestLoaderServer.js.map

package/lib/cache/unstable_cache.d.ts

@@ -0,0 +1,11 @@
+import type { ReactNode } from 'react';
+export interface UnstableCacheOptions {
+    /** Stable identifier for this cached function. Required. */
+    id: string;
+    /** Time in seconds before the cache entry is considered stale. 0 = indefinite. */
+    revalidate?: number;
+    /** Cache handler kind to use. Defaults to 'default' (in-memory LRU). */
+    kind?: string;
+}
+export declare function unstable_cache<TArgs extends unknown[]>(originalFn: (...args: TArgs) => Promise<ReactNode> | ReactNode, options: UnstableCacheOptions): (...args: TArgs) => Promise<ReactNode>;
+//# sourceMappingURL=unstable_cache.d.ts.map

package/lib/cache/unstable_cache.js

@@ -0,0 +1,85 @@
+/*
+ * Copyright (c) 2025 Shakacode LLC
+ *
+ * This file is NOT licensed under the MIT (open source) license.
+ * It is part of the React on Rails Pro offering and is licensed separately.
+ *
+ * Unauthorized copying, modification, distribution, or use of this file,
+ * via any medium, is strictly prohibited without a valid license agreement
+ * from Shakacode LLC.
+ *
+ * For licensing terms, please see:
+ * https://github.com/shakacode/react_on_rails/blob/master/REACT-ON-RAILS-PRO-LICENSE.md
+ */
+import { PassThrough } from 'stream';
+import { getCacheHandler } from "./cacheHandlerRegistry.js";
+import { buildCacheKey } from "./buildCacheKey.js";
+import { getBuildId } from "./buildIdProvider.js";
+import { getClientRenderer } from "./manifestLoader.js";
+import { getServerRenderer } from "./manifestLoaderServer.js";
+function chunksToNodeStream(chunks) {
+    const stream = new PassThrough();
+    for (const chunk of chunks) {
+        stream.push(chunk);
+    }
+    stream.push(null);
+    return stream;
+}
+function bufferNodeStream(stream) {
+    const chunks = [];
+    return new Promise((resolve, reject) => {
+        stream.on('data', (chunk) => chunks.push(chunk));
+        stream.on('end', () => resolve(chunks));
+        stream.on('error', reject);
+    });
+}
+// eslint-disable-next-line camelcase -- matches Next.js API naming convention
+export function unstable_cache(originalFn, options) {
+    const { id, revalidate = 0, kind = 'default' } = options;
+    return async function cachedFn(...args) {
+        const handler = getCacheHandler(kind);
+        const cacheKey = buildCacheKey(getBuildId(), id, args);
+        // --- HIT path ---
+        const entry = await handler.get(cacheKey);
+        if (entry) {
+            const replayStream = chunksToNodeStream(entry.value);
+            const { createFromNodeStream } = await getClientRenderer();
+            return createFromNodeStream(replayStream);
+        }
+        // --- MISS path ---
+        const reactTree = await originalFn(...args);
+        const { renderToPipeableStream } = await getServerRenderer();
+        const rscPipeable = renderToPipeableStream(reactTree);
+        const source = new PassThrough();
+        const forCache = new PassThrough();
+        const forReturn = new PassThrough();
+        rscPipeable.pipe(source);
+        source.on('data', (chunk) => {
+            forCache.push(chunk);
+            forReturn.push(chunk);
+        });
+        source.on('end', () => {
+            forCache.push(null);
+            forReturn.push(null);
+        });
+        source.on('error', (err) => {
+            forCache.destroy(err);
+            forReturn.destroy(err);
+        });
+        bufferNodeStream(forCache)
+            .then((chunks) => {
+            const newEntry = {
+                value: chunks,
+                revalidate,
+                timestamp: Date.now(),
+            };
+            return handler.set(cacheKey, newEntry);
+        })
+            .catch((err) => {
+            console.error('unstable_cache: failed to store cache entry', err);
+        });
+        const { createFromNodeStream } = await getClientRenderer();
+        return createFromNodeStream(forReturn);
+    };
+}
+//# sourceMappingURL=unstable_cache.js.map

package/lib/capabilities/proRSC.js

@@ -1,17 +1,64 @@
 /* eslint-disable import/prefer-default-export -- named export for consistency with capability API */
-import { buildServerRenderer } from 'react-on-rails-rsc/server.node';
 import { assertRailsContextWithServerStreamingCapabilities, } from 'react-on-rails/types';
 import { convertToError } from 'react-on-rails/serverRenderUtils';
 import handleError from "../handleErrorRSC.js";
 import { getOrCreateAsyncPropsManager } from "../AsyncPropsManager.js";
 import { streamServerRenderedComponent, transformRenderStreamChunksToResultObject, } from "../streamingUtils.js";
-import loadJsonFile from "../loadJsonFile.js";
-let serverRendererPromise;
+import { setManifestFileNames } from "../cache/manifestLoader.js";
+import { getServerRenderer } from "../cache/manifestLoaderServer.js";
+import { setBuildId } from "../cache/buildIdProvider.js";
+const CLIENT_HOOK_NAMES = [
+    'useState',
+    'useEffect',
+    'useReducer',
+    'useCallback',
+    'useMemo',
+    'useRef',
+    'useLayoutEffect',
+    'useImperativeHandle',
+    'useContext',
+    'useSyncExternalStore',
+    'useTransition',
+    'useDeferredValue',
+    'useId',
+    'useDebugValue',
+    'useInsertionEffect',
+    'useOptimistic',
+    'useActionState',
+].join('|');
+const CLIENT_HOOK_RUNTIME_ERROR_REGEX = new RegExp(`(?:(?:React\\.)|\\(0\\s*,\\s*[\\w$]+\\.)?(${CLIENT_HOOK_NAMES})\\)? is not a function\\b`);
+const addRSCClientHookDiagnostic = (error, componentName) => {
+    const match = error.message.match(CLIENT_HOOK_RUNTIME_ERROR_REGEX);
+    if (!match)
+        return error;
+    const hookName = match[1];
+    const enhancedError = new Error(`[React on Rails Pro] Component "${componentName}" called client hook "${hookName}" while rendering in ` +
+        `the React Server Components runtime.\n\n` +
+        `Most likely cause: "${componentName}", or a component it imports, uses client-only APIs but is missing ` +
+        `the '"use client";' directive.\n\n` +
+        `Add '"use client";' as the first statement of the client component file, or move hooks, event handlers, ` +
+        `and class components into a separate client component.\n\n` +
+        `Note: .client/.server file suffixes only control bundle placement. The '"use client";' directive controls ` +
+        `RSC client/server classification.\n\n` +
+        `Original error: ${error.message}`);
+    enhancedError.name = error.name;
+    enhancedError.cause = error;
+    const enhancedStackFrames = enhancedError.stack?.split('\n').slice(1).join('\n');
+    enhancedError.stack = `${enhancedError.name}: ${enhancedError.message}${enhancedStackFrames ? `\n${enhancedStackFrames}` : ''}\nCaused by: ${error.stack || error.message}`;
+    return enhancedError;
+};
 const streamRenderRSCComponent = (reactRenderingResult, options, streamingTrackers) => {
-    const { throwJsErrors } = options;
+    const { name: componentName, throwJsErrors } = options;
     const { railsContext } = options;
     assertRailsContextWithServerStreamingCapabilities(railsContext);
-    const { reactClientManifestFileName } = railsContext;
+    const { reactClientManifestFileName, reactServerClientManifestFileName } = railsContext;
+    // Initialize manifest loader and BUILD_ID on first render request.
+    // These are per-process constants that don't change between requests.
+    setManifestFileNames(reactClientManifestFileName, reactServerClientManifestFileName);
+    const rscPayloadParams = railsContext.serverSideRSCPayloadParameters;
+    if (rscPayloadParams?.rscBundleHash) {
+        setBuildId(rscPayloadParams.rscBundleHash);
+    }
     const renderState = {
         result: null,
         hasErrors: false,
@@ -19,23 +66,17 @@ const streamRenderRSCComponent = (reactRenderingResult, options, streamingTracke
     };
     const { pipeToTransform, readableStream, emitError } = transformRenderStreamChunksToResultObject(renderState);
     const reportError = (error) => {
-        console.error('Error in RSC stream', error);
+        const diagnosticError = addRSCClientHookDiagnostic(error, componentName);
+        console.error('Error in RSC stream', diagnosticError);
         if (throwJsErrors) {
-            emitError(error);
+            emitError(diagnosticError);
         }
         renderState.hasErrors = true;
-        renderState.error = error;
+        renderState.error = diagnosticError;
+        return diagnosticError;
     };
     const initializeAndRender = async () => {
-        if (!serverRendererPromise) {
-            serverRendererPromise = loadJsonFile(reactClientManifestFileName)
-                .then((reactClientManifest) => buildServerRenderer(reactClientManifest))
-                .catch((err) => {
-                serverRendererPromise = undefined;
-                throw err;
-            });
-        }
-        const { renderToPipeableStream } = await serverRendererPromise;
+        const { renderToPipeableStream } = await getServerRenderer();
         const rscStream = renderToPipeableStream(await reactRenderingResult, {
             onError: (err) => {
                 const error = convertToError(err);
@@ -45,8 +86,7 @@ const streamRenderRSCComponent = (reactRenderingResult, options, streamingTracke
         pipeToTransform(rscStream);
     };
     initializeAndRender().catch((e) => {
-        const error = convertToError(e);
-        reportError(error);
+        const error = reportError(convertToError(e));
         const errorHtml = handleError({ e: error, name: options.name, serverSide: true });
         pipeToTransform(errorHtml);
     });

package/lib/getReactServerComponent.client.js

@@ -15,6 +15,7 @@ import { createFromReadableStream } from 'react-on-rails-rsc/client.browser';
 import { createRSCPayloadKey, fetch, wrapInNewPromise, extractErrorMessage } from "./utils.js";
 import sanitizeNonce from 'react-on-rails/@internal/sanitizeNonce';
 import LengthPrefixedStreamParser from "./parseLengthPrefixedStream.js";
+import { buildRSCStreamDiagnosticError, mergeRSCStreamDiagnosticError, RSC_STREAM_DIAGNOSTIC_ERROR_NAME, } from "./rscDiagnostics.js";
 /**
  * Replays a consoleReplayScript by injecting it as a <script> element.
  */
@@ -39,7 +40,7 @@ const replayConsole = (consoleReplayScript, nonce) => {
  *
  * Extracts raw Flight data for React, replays console from metadata.
  */
-const createFromFetch = async (fetchPromise, cspNonce) => {
+const createFromFetch = async (fetchPromise, { componentName, cspNonce, source, }) => {
     const response = await fetchPromise;
     const { body } = response;
     if (!body) {
@@ -47,6 +48,13 @@ const createFromFetch = async (fetchPromise, cspNonce) => {
     }
     const nonce = sanitizeNonce(cspNonce);
     const parser = new LengthPrefixedStreamParser();
+    let rscDiagnosticError;
+    const reportDiagnosticError = (metadata) => {
+        const diagnosticError = buildRSCStreamDiagnosticError(metadata, { componentName, source });
+        if (diagnosticError && !rscDiagnosticError) {
+            rscDiagnosticError = diagnosticError;
+        }
+    };
     const transformedStream = new ReadableStream({
         async start(controller) {
             const reader = body.getReader();
@@ -58,6 +66,7 @@ const createFromFetch = async (fetchPromise, cspNonce) => {
                     done = readResult.done;
                     if (readResult.value) {
                         parser.feed(readResult.value, (content, metadata) => {
+                            reportDiagnosticError(metadata);
                             controller.enqueue(content);
                             const consoleScript = metadata.consoleReplayScript ?? '';
                             if (consoleScript) {
@@ -75,7 +84,14 @@ const createFromFetch = async (fetchPromise, cspNonce) => {
         },
     });
     const renderPromise = createFromReadableStream(transformedStream);
-    return wrapInNewPromise(renderPromise);
+    // `rscDiagnosticError` is set before the matching chunk is enqueued: the parser callback
+    // records it first, then enqueues the content in the ReadableStream `start` callback above.
+    // React can only read a chunk after it has been enqueued, so by the time `renderPromise`
+    // rejects the diagnostic — if the stream carried one — is already set; it is never undefined
+    // purely because of timing.
+    return wrapInNewPromise(renderPromise).catch((error) => {
+        throw mergeRSCStreamDiagnosticError(error, rscDiagnosticError);
+    });
 };
 /**
  * Fetches an RSC payload via HTTP request.
@@ -104,9 +120,22 @@ const fetchRSC = ({ componentName, componentProps, railsContext, }) => {
         const propsString = JSON.stringify(componentProps);
         const strippedUrlPath = rscPayloadGenerationUrlPath.replace(/^\/|\/$/g, '');
         const encodedParams = new URLSearchParams({ props: propsString }).toString();
-        const fetchUrl = `/${strippedUrlPath}/${componentName}?${encodedParams}`;
-        return createFromFetch(fetch(fetchUrl), railsContext.cspNonce).catch((error) => {
-            throw new Error(`Failed to fetch RSC payload for component "${componentName}" from "${fetchUrl}": ${extractErrorMessage(error)}`);
+        const sourcePath = `/${strippedUrlPath}/${componentName}`;
+        const fetchUrl = `${sourcePath}?${encodedParams}`;
+        return createFromFetch(fetch(fetchUrl), {
+            componentName,
+            cspNonce: railsContext.cspNonce,
+            // Keep `source` query-string free so serialized props aren't echoed into error messages
+            // or attached error-monitoring events. The outer wrapper below retains `fetchUrl` for reproducibility.
+            source: sourcePath,
+        }).catch((error) => {
+            // RSC stream diagnostic errors already carry component/source context — preserve them
+            // (including .cause and the merged stack) instead of flattening to a plain Error.
+            if (error instanceof Error && error.name === RSC_STREAM_DIAGNOSTIC_ERROR_NAME)
+                throw error;
+            const wrapper = new Error(`Failed to fetch RSC payload for component "${componentName}" from "${fetchUrl}": ${extractErrorMessage(error)}`);
+            wrapper.cause = error;
+            throw wrapper;
         });
     }
     catch (error) {
@@ -158,12 +187,22 @@ const createRSCStreamFromArray = (payloads) => {
  * the payload is already embedded in the page.
  *
  * @param payloads - Array of raw Flight data strings from the global array
+ * @param componentName - Name of the server component, used for error context
  * @returns A Promise resolving to the rendered React element
  */
-const createFromPreloadedPayloads = (payloads) => {
+const createFromPreloadedPayloads = (payloads, componentName) => {
     const stream = createRSCStreamFromArray(payloads);
     const renderPromise = createFromReadableStream(stream);
-    return wrapInNewPromise(renderPromise);
+    return wrapInNewPromise(renderPromise).catch((error) => {
+        // Preloaded payloads carry only raw Flight data — the server consumes the length-prefixed
+        // `renderingError` metadata during injection (see injectRSCPayload), so there is no RSC
+        // bundle diagnostic to merge here. Still, name the failing component (and preserve the
+        // original error as `cause`) so a hydration failure is attributable instead of surfacing a
+        // bare React error.
+        const wrapper = new Error(`Failed to hydrate preloaded RSC payload for component "${componentName}": ${extractErrorMessage(error)}`);
+        wrapper.cause = error;
+        throw wrapper;
+    });
 };
 /**
  * Creates a function that fetches and renders a server component on the client side.
@@ -202,7 +241,7 @@ const getReactServerComponent = (domNodeId, railsContext) => ({ componentName, c
         const rscPayloadKey = createRSCPayloadKey(componentName, componentProps, domNodeId);
         const payloads = window.REACT_ON_RAILS_RSC_PAYLOADS[rscPayloadKey];
         if (payloads) {
-            return createFromPreloadedPayloads(payloads);
+            return createFromPreloadedPayloads(payloads, componentName);
         }
     }
     return fetchRSC({ componentName, componentProps, railsContext });

package/lib/getReactServerComponent.server.js

@@ -14,8 +14,9 @@
 import { buildClientRenderer } from 'react-on-rails-rsc/client.node';
 import transformRSCStream from "./transformRSCNodeStream.js";
 import loadJsonFile from "./loadJsonFile.js";
+import { mergeRSCStreamDiagnosticError } from "./rscDiagnostics.js";
 let clientRendererPromise;
-const createFromReactOnRailsNodeStream = async (stream, reactServerManifestFileName, reactClientManifestFileName) => {
+const createFromReactOnRailsNodeStream = async (stream, reactServerManifestFileName, reactClientManifestFileName, componentName) => {
     if (!clientRendererPromise) {
         clientRendererPromise = Promise.all([
             loadJsonFile(reactServerManifestFileName),
@@ -28,8 +29,26 @@ const createFromReactOnRailsNodeStream = async (stream, reactServerManifestFileN
         });
     }
     const { createFromNodeStream } = await clientRendererPromise;
-    const transformedStream = transformRSCStream(stream);
-    return createFromNodeStream(transformedStream);
+    let rscDiagnosticError;
+    const transformedStream = transformRSCStream(stream, {
+        componentName,
+        onDiagnosticError(error) {
+            rscDiagnosticError = error;
+        },
+    });
+    // Note: this try/catch enriches any error that rejects `createFromNodeStream` — stream read
+    // failures, malformed Flight data, or synchronous render errors. It does NOT catch errors
+    // React surfaces through its error-boundary / Suspense mechanism during the deferred render
+    // phase (e.g. when a Suspense boundary resolves a lazy element); those never reject this
+    // promise. In that case `rscDiagnosticError` (a local that goes out of scope when this
+    // function returns) is discarded and the caller sees only the generic React error. Enriching
+    // the deferred-render path is tracked in #3475.
+    try {
+        return await createFromNodeStream(transformedStream);
+    }
+    catch (error) {
+        throw mergeRSCStreamDiagnosticError(error, rscDiagnosticError);
+    }
 };
 /**
  * Creates a function that fetches and renders a server component on the server side.
@@ -64,7 +83,7 @@ const createFromReactOnRailsNodeStream = async (stream, reactServerManifestFileN
  */
 const getReactServerComponent = (railsContext) => async ({ componentName, componentProps }) => {
     const rscPayloadStream = await railsContext.getRSCPayloadStream(componentName, componentProps);
-    return createFromReactOnRailsNodeStream(rscPayloadStream, railsContext.reactServerClientManifestFileName, railsContext.reactClientManifestFileName);
+    return createFromReactOnRailsNodeStream(rscPayloadStream, railsContext.reactServerClientManifestFileName, railsContext.reactClientManifestFileName, componentName);
 };
 export default getReactServerComponent;
 //# sourceMappingURL=getReactServerComponent.server.js.map

package/lib/rscDiagnostics.d.ts

@@ -0,0 +1,29 @@
+type RSCStreamDiagnosticContext = {
+    componentName?: string;
+    source?: string;
+};
+export type RSCStreamDiagnosticsOptions = RSCStreamDiagnosticContext & {
+    onDiagnosticError?: (error: Error) => void;
+};
+export declare const RSC_STREAM_DIAGNOSTIC_ERROR_NAME = "ReactOnRailsRSCStreamError";
+export declare const MERGED_DIAGNOSTIC_FLAG = "__rorRSCDiagMerged";
+type RSCStreamDiagnosticError = Error & {
+    [MERGED_DIAGNOSTIC_FLAG]?: true;
+    cause?: unknown;
+};
+export declare const extractModulePathFromStack: (stack?: string) => string | undefined;
+export declare const buildRSCStreamDiagnosticError: (metadata: Record<string, unknown>, context?: RSCStreamDiagnosticContext) => Error | undefined;
+/**
+ * Merges a generic React stream error with the original RSC bundle diagnostic.
+ *
+ * Idempotent on `error`: if `error` is already a merged result (carries `MERGED_DIAGNOSTIC_FLAG`)
+ * it is returned untouched, so re-entering this in a chain of catch handlers won't double-wrap.
+ *
+ * Precondition: `diagnosticError` must be a fresh (non-merged) diagnostic — in practice it always
+ * comes from `buildRSCStreamDiagnosticError`, which never sets the flag. The idempotency guard
+ * intentionally only inspects `error`; passing an already-merged error as `diagnosticError` would
+ * duplicate context.
+ */
+export declare const mergeRSCStreamDiagnosticError: (error: unknown, diagnosticError?: Error) => RSCStreamDiagnosticError;
+export {};
+//# sourceMappingURL=rscDiagnostics.d.ts.map

package/lib/rscDiagnostics.js

@@ -0,0 +1,130 @@
+/*
+ * Copyright (c) 2025 Shakacode LLC
+ *
+ * This file is NOT licensed under the MIT (open source) license.
+ * It is part of the React on Rails Pro offering and is licensed separately.
+ *
+ * Unauthorized copying, modification, distribution, or use of this file,
+ * via any medium, is strictly prohibited without a valid license agreement
+ * from Shakacode LLC.
+ *
+ * For licensing terms, please see:
+ * https://github.com/shakacode/react_on_rails/blob/master/REACT-ON-RAILS-PRO-LICENSE.md
+ */
+import { extractErrorMessage } from "./utils.js";
+export const RSC_STREAM_DIAGNOSTIC_ERROR_NAME = 'ReactOnRailsRSCStreamError';
+// Exported so tests reference the marker by constant rather than a duplicated string literal.
+export const MERGED_DIAGNOSTIC_FLAG = '__rorRSCDiagMerged';
+const nonEmptyString = (value) => {
+    if (typeof value !== 'string')
+        return undefined;
+    // Trim so a whitespace-only `renderingError.message`/`stack` (e.g. `"  "` or `"\n"`) is
+    // treated as absent rather than surfacing as `Original error:` with blank text.
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+};
+// Bundler/framework frames point at library code rather than the failing component, so they
+// are a poor value for `Module:`. Skip them when a later user-code frame is available.
+// Note: this is matched against the extracted file *path*, not the raw frame, so a webpack
+// runtime frame is caught by its `webpack/` or `webpack-internal:` path, not its function name.
+const INTERNAL_FRAME_RE = /(?:^|[\\/])node_modules[\\/]|(?:^|[\\/])webpack[\\/]|\bwebpack-internal:/;
+export const extractModulePathFromStack = (stack) => {
+    if (!stack)
+        return undefined;
+    let firstLocation;
+    for (const rawLine of stack.split('\n')) {
+        const line = rawLine.trim();
+        // Two V8 frame shapes:
+        //   `at fn (/path/to/file.js:10:5)`  -> parenthesized
+        //   `at /path:10:5` / `at async /path:10:5` -> anonymous/top-level
+        // The anonymous form is anchored to an absolute path (POSIX `/` or a Windows drive) and
+        // tolerates the optional `async ` keyword, so a bare function name in an unusual
+        // `at fn /path:10:5` frame isn't mistaken for the module path.
+        const match = /\(([^()]+):\d+:\d+\)$|\bat\s+(?:async\s+)?((?:\/|[A-Za-z]:[\\/]).*?):\d+:\d+$/.exec(line);
+        const location = (match?.[1] ?? match?.[2])?.replace(/\?.*$/, '');
+        if (location) {
+            firstLocation ?? (firstLocation = location);
+            if (!INTERNAL_FRAME_RE.test(location))
+                return location;
+        }
+    }
+    // Every frame was framework-internal — fall back to the first so `Module:` is still populated.
+    return firstLocation;
+};
+export const buildRSCStreamDiagnosticError = (metadata, context = {}) => {
+    const raw = metadata.renderingError;
+    // `RenderingErrorMetadata` has only optional `unknown` fields, so a plain annotation
+    // accepts any object without a type assertion; `nonEmptyString()` validates each field at runtime.
+    const re = typeof raw === 'object' && raw !== null ? raw : {};
+    const originalMessage = nonEmptyString(re.message);
+    const originalStack = nonEmptyString(re.stack);
+    // Wire contract: the React on Rails server bundle only emits `renderingError` on actual
+    // failure, so presence of a message or stack is treated as a failure signal even when
+    // `hasErrors` isn't explicitly set. Belt-and-suspenders intentional — if a future producer
+    // wants to use `renderingError` for non-fatal info, this guard needs to change with it.
+    if (metadata.hasErrors !== true && !originalMessage && !originalStack)
+        return undefined;
+    const modulePath = extractModulePathFromStack(originalStack);
+    // Without a message, name the actual signal that triggered the diagnostic: `hasErrors=true`
+    // when that flag is set, otherwise a stack-only `renderingError` (claiming `hasErrors=true`
+    // in the latter case would be inaccurate).
+    const fallbackOriginalError = metadata.hasErrors === true
+        ? 'RSC stream metadata reported hasErrors=true'
+        : 'RSC stream metadata reported a rendering error';
+    const message = [
+        '[ReactOnRails] RSC bundle rendering failed.',
+        context.componentName && `Component: ${context.componentName}`,
+        context.source && `Source: ${context.source}`,
+        modulePath && `Module: ${modulePath}`,
+        `Original error: ${originalMessage ?? fallbackOriginalError}`,
+    ]
+        .filter((line) => Boolean(line))
+        .join('\n');
+    const diagnosticError = new Error(message);
+    diagnosticError.name = RSC_STREAM_DIAGNOSTIC_ERROR_NAME;
+    // Always overwrite the auto-generated stack. With an original stack we surface it; without one
+    // we reduce the stack to just the header line, because the V8-generated stack would otherwise
+    // point at this diagnostics module and error monitors (Sentry, Honeybadger) would misattribute
+    // the error origin to react-on-rails internals.
+    diagnosticError.stack = originalStack
+        ? `${diagnosticError.name}: ${message}\nOriginal stack:\n${originalStack}`
+        : `${diagnosticError.name}: ${message}`;
+    return diagnosticError;
+};
+/**
+ * Merges a generic React stream error with the original RSC bundle diagnostic.
+ *
+ * Idempotent on `error`: if `error` is already a merged result (carries `MERGED_DIAGNOSTIC_FLAG`)
+ * it is returned untouched, so re-entering this in a chain of catch handlers won't double-wrap.
+ *
+ * Precondition: `diagnosticError` must be a fresh (non-merged) diagnostic — in practice it always
+ * comes from `buildRSCStreamDiagnosticError`, which never sets the flag. The idempotency guard
+ * intentionally only inspects `error`; passing an already-merged error as `diagnosticError` would
+ * duplicate context.
+ */
+export const mergeRSCStreamDiagnosticError = (error, diagnosticError) => {
+    const streamError = error instanceof Error ? error : new Error(extractErrorMessage(error));
+    if (!diagnosticError || streamError[MERGED_DIAGNOSTIC_FLAG])
+        return streamError;
+    const message = `${diagnosticError.message}\nReact stream error: ${streamError.message}`;
+    const mergedError = new Error(message);
+    mergedError.name = RSC_STREAM_DIAGNOSTIC_ERROR_NAME;
+    mergedError.cause = streamError;
+    // Non-enumerable so error reporters that iterate own keys (Sentry "extra data",
+    // structured cloning, etc.) don't pick up this internal marker.
+    Object.defineProperty(mergedError, MERGED_DIAGNOSTIC_FLAG, {
+        value: true,
+        writable: false,
+        enumerable: false,
+        configurable: false,
+    });
+    mergedError.stack = [
+        `${mergedError.name}: ${message}`,
+        diagnosticError.stack && `RSC diagnostic stack:\n${diagnosticError.stack}`,
+        streamError.stack && `React stream stack:\n${streamError.stack}`,
+    ]
+        .filter((line) => Boolean(line))
+        .join('\n\n');
+    return mergedError;
+};
+//# sourceMappingURL=rscDiagnostics.js.map

package/lib/transformRSCNodeStream.d.ts

@@ -1,3 +1,4 @@
+import { RSCStreamDiagnosticsOptions } from './rscDiagnostics.ts';
 /**
  * Transforms an RSC Node.js stream for server-side processing.
  *
@@ -12,5 +13,5 @@
  * @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;
+export default function transformRSCStream(stream: NodeJS.ReadableStream, diagnosticsOptions?: RSCStreamDiagnosticsOptions): NodeJS.ReadableStream;
 //# sourceMappingURL=transformRSCNodeStream.d.ts.map

package/lib/transformRSCNodeStream.js

@@ -14,6 +14,7 @@
 import { Transform } from 'stream';
 import safePipe from "./safePipe.js";
 import LengthPrefixedStreamParser from "./parseLengthPrefixedStream.js";
+import { buildRSCStreamDiagnosticError } from "./rscDiagnostics.js";
 /**
  * Transforms an RSC Node.js stream for server-side processing.
  *
@@ -28,12 +29,21 @@ import LengthPrefixedStreamParser from "./parseLengthPrefixedStream.js";
  * @param stream - The Node.js RSC payload stream
  * @returns A transformed stream compatible with React's SSR runtime
  */
-export default function transformRSCStream(stream) {
+export default function transformRSCStream(stream, diagnosticsOptions = {}) {
     const parser = new LengthPrefixedStreamParser();
+    let reportedDiagnosticError = false;
     const htmlExtractor = new Transform({
         transform(chunk, _, callback) {
             try {
-                parser.feed(chunk, (content) => {
+                parser.feed(chunk, (content, metadata) => {
+                    const diagnosticError = buildRSCStreamDiagnosticError(metadata, diagnosticsOptions);
+                    // First-wins: report only the earliest diagnostic. A failing RSC stream emits a single
+                    // renderingError, so this avoids duplicate reports of the same failure. (A later chunk
+                    // carrying a richer renderingError would be dropped, but that doesn't occur in practice.)
+                    if (diagnosticError && !reportedDiagnosticError) {
+                        reportedDiagnosticError = true;
+                        diagnosticsOptions.onDiagnosticError?.(diagnosticError);
+                    }
                     this.push(content);
                 });
                 callback();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-on-rails-pro",
-  "version": "16.7.0-rc.3",
+  "version": "17.0.0-rc.0",
   "description": "React on Rails Pro package with React Server Components support",
   "main": "lib/ReactOnRails.full.js",
   "type": "module",
@@ -43,12 +43,16 @@
       "react-server": "./lib/wrapServerComponentRenderer/server.rsc.js",
       "default": "./lib/wrapServerComponentRenderer/server.js"
     },
+    "./cache": {
+      "react-server": "./lib/cache/index.js",
+      "default": "./lib/cache/index.stub.js"
+    },
     "./RSCRoute": "./lib/RSCRoute.js",
     "./RSCProvider": "./lib/RSCProvider.js",
     "./ServerComponentFetchError": "./lib/ServerComponentFetchError.js"
   },
   "dependencies": {
-    "react-on-rails": "16.7.0-rc.3"
+    "react-on-rails": "17.0.0-rc.0"
   },
   "peerDependencies": {
     "react": ">= 16",