Add support for streaming rendered components using renderToPipeableStream

CHANGELOG.md

@@ -18,6 +18,13 @@ Please follow the recommendations outlined at [keepachangelog.com](http://keepac
 ### [Unreleased]
 Changes since the last non-beta release.
 
+### Added
+- Added streaming server rendering support:
+  - New `stream_react_component` helper for adding streamed components to views
+  - New `streamServerRenderedReactComponent` function in the react-on-rails package that uses React 18's `renderToPipeableStream` API
+  - Enables progressive page loading and improved performance for server-rendered React components
+  [PR #1633](https://github.com/shakacode/react_on_rails/pull/1633) by [AbanoubGhadban](https://github.com/AbanoubGhadban).
+
 #### Changed
 - Console replay script generation now awaits the render request promise before generating, allowing it to capture console logs from asynchronous operations. This requires using a version of the Node renderer that supports replaying async console logs. [PR #1649](https://github.com/shakacode/react_on_rails/pull/1649) by [AbanoubGhadban](https://github.com/AbanoubGhadban).
 

jest.config.js

@@ -1,4 +1,5 @@
 module.exports = {
   preset: 'ts-jest/presets/js-with-ts',
   testEnvironment: 'jsdom',
+  setupFiles: ['<rootDir>/node_package/tests/jest.setup.js'],
 };

lib/react_on_rails/helper.rb

@@ -91,6 +91,64 @@ def react_component(component_name, options = {})
       end
     end
 
+    # Streams a server-side rendered React component using React's `renderToPipeableStream`.
+    # Supports React 18 features like Suspense, concurrent rendering, and selective hydration.
+    # Enables progressive rendering and improved performance for large components.
+    #
+    # Note: This function can only be used with React on Rails Pro.
+    # The view that uses this function must be rendered using the
+    # `stream_view_containing_react_components` method from the React on Rails Pro gem.
+    #
+    # Example of an async React component that can benefit from streaming:
+    #
+    # const AsyncComponent = async () => {
+    #   const data = await fetchData();
+    #   return <div>{data}</div>;
+    # };
+    #
+    # function App() {
+    #   return (
+    #     <Suspense fallback={<div>Loading...</div>}>
+    #       <AsyncComponent />
+    #     </Suspense>
+    #   );
+    # }
+    #
+    # @param [String] component_name Name of your registered component
+    # @param [Hash] options Options for rendering
+    # @option options [Hash] :props Props to pass to the react component
+    # @option options [String] :dom_id DOM ID of the component container
+    # @option options [Hash] :html_options Options passed to content_tag
+    # @option options [Boolean] :prerender Set to false to disable server-side rendering
+    # @option options [Boolean] :trace Set to true to add extra debugging information to the HTML
+    # @option options [Boolean] :raise_on_prerender_error Set to true to raise exceptions during server-side rendering
+    # Any other options are passed to the content tag, including the id.
+    def stream_react_component(component_name, options = {})
+      unless ReactOnRails::Utils.react_on_rails_pro?
+        raise ReactOnRails::Error,
+              "You must use React on Rails Pro to use the stream_react_component method."
+      end
+
+      if @rorp_rendering_fibers.nil?
+        raise ReactOnRails::Error,
+              "You must call stream_view_containing_react_components to render the view containing the react component"
+      end
+
+      rendering_fiber = Fiber.new do
+        stream = internal_stream_react_component(component_name, options)
+        stream.each_chunk do |chunk|
+          Fiber.yield chunk
+        end
+      end
+
+      @rorp_rendering_fibers << rendering_fiber
+
+      # return the first chunk of the fiber
+      # It contains the initial html of the component
+      # all updates will be appended to the stream sent to browser
+      rendering_fiber.resume
+    end
+
     # react_component_hash is used to return multiple HTML strings for server rendering, such as for
     # adding meta-tags to a page.
     # It is exactly like react_component except for the following:
@@ -330,6 +388,16 @@ def load_pack_for_generated_component(react_component_name, render_options)
 
     private
 
+    def internal_stream_react_component(component_name, options = {})
+      options = options.merge(stream?: true)
+      result = internal_react_component(component_name, options)
+      build_react_component_result_for_server_streamed_content(
+        rendered_html_stream: result[:result],
+        component_specification_tag: result[:tag],
+        render_options: result[:render_options]
+      )
+    end
+
     def generated_components_pack_path(component_name)
       "#{ReactOnRails::PackerUtils.packer_source_entry_path}/generated/#{component_name}.js"
     end
@@ -361,6 +429,33 @@ def build_react_component_result_for_server_rendered_string(
       prepend_render_rails_context(result)
     end
 
+    def build_react_component_result_for_server_streamed_content(
+      rendered_html_stream: required("rendered_html_stream"),
+      component_specification_tag: required("component_specification_tag"),
+      render_options: required("render_options")
+    )
+      content_tag_options_html_tag = render_options.html_options[:tag] || "div"
+      # The component_specification_tag is appended to the first chunk
+      # We need to pass it early with the first chunk because it's needed in hydration
+      # We need to make sure that client can hydrate the app early even before all components are streamed
+      is_first_chunk = true
+      rendered_html_stream = rendered_html_stream.transform do |chunk|
+        if is_first_chunk
+          is_first_chunk = false
+          html_content = <<-HTML
+            #{rails_context_if_not_already_rendered}
+            #{component_specification_tag}
+            <#{content_tag_options_html_tag} id="#{render_options.dom_id}">#{chunk}</#{content_tag_options_html_tag}>
+          HTML
+          next html_content.strip
+        end
+        chunk
+      end
+
+      rendered_html_stream.transform(&:html_safe)
+      # TODO: handle console logs
+    end
+
     def build_react_component_result_for_server_rendered_hash(
       server_rendered_html: required("server_rendered_html"),
       component_specification_tag: required("component_specification_tag"),
@@ -404,20 +499,22 @@ def compose_react_component_html_with_spec_and_console(component_specification_t
       HTML
     end
 
-    # prepend the rails_context if not yet applied
-    def prepend_render_rails_context(render_value)
-      return render_value if @rendered_rails_context
+    def rails_context_if_not_already_rendered
+      return "" if @rendered_rails_context
 
       data = rails_context(server_side: false)
 
       @rendered_rails_context = true
 
-      rails_context_content = content_tag(:script,
-                                          json_safe_and_pretty(data).html_safe,
-                                          type: "application/json",
-                                          id: "js-react-on-rails-context")
+      content_tag(:script,
+                  json_safe_and_pretty(data).html_safe,
+                  type: "application/json",
+                  id: "js-react-on-rails-context")
+    end
 
-      "#{rails_context_content}\n#{render_value}".html_safe
+    # prepend the rails_context if not yet applied
+    def prepend_render_rails_context(render_value)
+      "#{rails_context_if_not_already_rendered}\n#{render_value}".strip.html_safe
     end
 
     def internal_react_component(react_component_name, options = {})
@@ -520,6 +617,9 @@ def server_rendered_react_component(render_options)
                                                js_code: js_code)
       end
 
+      # TODO: handle errors for streams
+      return result if render_options.stream?
+
       if result["hasErrors"] && render_options.raise_on_prerender_error
         # We caught this exception on our backtrace handler
         raise ReactOnRails::PrerenderError.new(component_name: react_component_name,

lib/react_on_rails/react_component/render_options.rb

@@ -107,6 +107,10 @@ def set_option(key, value)
         options[key] = value
       end
 
+      def stream?
+        options[:stream?]
+      end
+
       private
 
       attr_reader :options

lib/react_on_rails/server_rendering_pool/ruby_embedded_java_script.rb

@@ -92,6 +92,12 @@ def exec_server_render_js(js_code, render_options, js_evaluator = nil)
         end
         # rubocop:enable Metrics/CyclomaticComplexity, Metrics/AbcSize, Metrics/PerceivedComplexity
 
+        # TODO: merge with exec_server_render_js
+        def exec_server_render_streaming_js(js_code, render_options, js_evaluator = nil)
+          js_evaluator ||= self
+          js_evaluator.eval_streaming_js(js_code, render_options)
+        end
+
         def trace_js_code_used(msg, js_code, file_name = "tmp/server-generated.js", force: false)
           return unless ReactOnRails.configuration.trace || force
 

node_package/src/ReactOnRails.ts

@@ -1,10 +1,11 @@
 import type { ReactElement } from 'react';
+import type { Readable } from 'stream';
 
 import * as ClientStartup from './clientStartup';
 import handleError from './handleError';
 import ComponentRegistry from './ComponentRegistry';
 import StoreRegistry from './StoreRegistry';
-import serverRenderReactComponent from './serverRenderReactComponent';
+import serverRenderReactComponent, { streamServerRenderedReactComponent } from './serverRenderReactComponent';
 import buildConsoleReplay from './buildConsoleReplay';
 import createReactOutput from './createReactOutput';
 import Authenticity from './Authenticity';
@@ -247,6 +248,14 @@ ctx.ReactOnRails = {
     return serverRenderReactComponent(options);
   },
 
+  /**
+   * Used by server rendering by Rails
+   * @param options
+   */
+  streamServerRenderedReactComponent(options: RenderParams): Readable {
+    return streamServerRenderedReactComponent(options);
+  },
+
   /**
    * Used by Rails to catch errors in rendering
    * @param options

node_package/src/serverRenderReactComponent.ts

@@ -1,4 +1,5 @@
 import ReactDOMServer from 'react-dom/server';
+import { PassThrough, Readable } from 'stream';
 import type { ReactElement } from 'react';
 
 import ComponentRegistry from './ComponentRegistry';
@@ -192,4 +193,53 @@ const serverRenderReactComponent: typeof serverRenderReactComponentInternal = (o
   }
 };
 
+const stringToStream = (str: string): Readable => {
+  const stream = new PassThrough();
+  stream.push(str);
+  stream.push(null);
+  return stream;
+};
+
+export const streamServerRenderedReactComponent = (options: RenderParams): Readable => {
+  const { name: componentName, domNodeId, trace, props, railsContext, throwJsErrors } = options;
+
+  let renderResult: null | Readable = null;
+
+  try {
+    const componentObj = ComponentRegistry.get(componentName);
+    validateComponent(componentObj, componentName);
+
+    const reactRenderingResult = createReactOutput({
+      componentObj,
+      domNodeId,
+      trace,
+      props,
+      railsContext,
+    });
+
+    if (isServerRenderHash(reactRenderingResult) || isPromise(reactRenderingResult)) {
+      throw new Error('Server rendering of streams is not supported for server render hashes or promises.');
+    }
+
+    const renderStream = new PassThrough();
+    ReactDOMServer.renderToPipeableStream(reactRenderingResult).pipe(renderStream);
+    renderResult = renderStream;
+
+    // TODO: Add console replay script to the stream
+  } catch (e) {
+    if (throwJsErrors) {
+      throw e;
+    }
+
+    const error = e instanceof Error ? e : new Error(String(e));
+    renderResult = stringToStream(handleError({
+      e: error,
+      name: componentName,
+      serverSide: true,
+    }));
+  }
+
+  return renderResult;
+};
+
 export default serverRenderReactComponent;

node_package/src/types/index.ts

@@ -1,4 +1,5 @@
 import type { ReactElement, ReactNode, Component, ComponentType } from 'react';
+import type { Readable } from 'stream';
 
 // Don't import redux just for the type definitions
 // See https://github.com/shakacode/react_on_rails/issues/1321
@@ -168,6 +169,7 @@ export interface ReactOnRails {
   ): RenderReturnType;
   getComponent(name: string): RegisteredComponent;
   serverRenderReactComponent(options: RenderParams): null | string | Promise<RenderResult>;
+  streamServerRenderedReactComponent(options: RenderParams): Readable;
   handleError(options: ErrorOptions): string | undefined;
   buildConsoleReplay(): string;
   registeredComponents(): Map<string, RegisteredComponent>;

node_package/tests/ReactOnRails.test.js

@@ -19,10 +19,15 @@ describe('ReactOnRails', () => {
     });
     ReactOnRails.register({ R1 });
 
-    document.body.innerHTML = '<div id="root"></div>';
-    // eslint-disable-next-line no-underscore-dangle
-    const actual = ReactOnRails.render('R1', {}, 'root')._reactInternals.type;
-    expect(actual).toEqual(R1);
+    const root = document.createElement('div');
+    root.id = 'root';
+    root.textContent = ' WORLD ';
+
+    document.body.innerHTML = '';
+    document.body.appendChild(root);
+    ReactOnRails.render('R1', {}, 'root');
+
+    expect(document.getElementById('root').textContent).toEqual(' WORLD ');
   });
 
   it('accepts traceTurbolinks as an option true', () => {

node_package/tests/jest.setup.js

@@ -0,0 +1,13 @@
+// If jsdom environment is set and TextEncoder is not defined, then define TextEncoder and TextDecoder
+// The current version of jsdom does not support TextEncoder and TextDecoder
+// The following code will tell us when jsdom supports TextEncoder and TextDecoder
+if (typeof window !== 'undefined' && typeof window.TextEncoder !== 'undefined') {
+  throw new Error('TextEncoder is already defined, remove the polyfill');
+}
+
+if (typeof window !== 'undefined') {
+  // eslint-disable-next-line global-require
+  const { TextEncoder, TextDecoder } = require('util');
+  global.TextEncoder = TextEncoder;
+  global.TextDecoder = TextDecoder;
+}

package.json

@@ -15,8 +15,8 @@
     "@babel/preset-react": "^7.18.6",
     "@babel/types": "^7.20.7",
     "@types/jest": "^29.0.0",
-    "@types/react": "^17.0.0",
-    "@types/react-dom": "^17.0.0",
+    "@types/react": "^18.2.0",
+    "@types/react-dom": "^18.2.0",
     "@types/turbolinks": "^5.2.2",
     "@types/webpack-env": "^1.18.4",
     "@typescript-eslint/eslint-plugin": "^6.18.1",
@@ -39,8 +39,8 @@
     "prettier": "^2.8.8",
     "prettier-eslint-cli": "^5.0.0",
     "prop-types": "^15.8.1",
-    "react": "^17.0.0",
-    "react-dom": "^17.0.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
     "react-transform-hmr": "^1.0.4",
     "redux": "^4.2.1",
     "ts-jest": "^29.1.0",

spec/dummy/config/webpack/alias.js

@@ -4,6 +4,7 @@ module.exports = {
   resolve: {
     alias: {
       Assets: resolve(__dirname, '..', '..', 'client', 'app', 'assets'),
+      stream: 'stream-browserify',
     },
   },
 };

spec/dummy/config/webpack/commonWebpackConfig.js

@@ -41,6 +41,7 @@ baseClientWebpackConfig.plugins.push(
   new webpack.ProvidePlugin({
     $: 'jquery',
     jQuery: 'jquery',
+    process: 'process/browser',
   }),
 );
 

spec/dummy/config/webpack/webpackConfig.js

@@ -4,6 +4,7 @@ const serverWebpackConfig = require('./serverWebpackConfig');
 const webpackConfig = (envSpecific) => {
   const clientConfig = clientWebpackConfig();
   const serverConfig = serverWebpackConfig();
+  clientConfig.resolve.fallback = { stream: require.resolve('stream-browserify') };
 
   if (envSpecific) {
     envSpecific(clientConfig, serverConfig);