react_on_rails 14.2.1 → 16.1.1

data/lib/react_on_rails/engine.rb

@@ -8,5 +8,11 @@ module ReactOnRails
       VersionChecker.build.log_if_gem_and_node_package_versions_differ
       ReactOnRails::ServerRenderingPool.reset_pool
     end
+
+    rake_tasks do
+      load File.expand_path("../tasks/generate_packs.rake", __dir__)
+      load File.expand_path("../tasks/assets.rake", __dir__)
+      load File.expand_path("../tasks/locale.rake", __dir__)
+    end
   end
 end

data/lib/react_on_rails/git_utils.rb

@@ -11,9 +11,19 @@ module ReactOnRails
       return false if git_installed && status&.empty?
 
       error = if git_installed
-                "You have uncommitted code. Please commit or stash your changes before continuing"
+                <<~MSG.strip
+                  You have uncommitted changes. Please commit or stash them before continuing.
+
+                  The React on Rails generator creates many new files and it's important to keep
+                  your existing changes separate from the generated code for easier review.
+                MSG
               else
-                "You do not have Git installed. Please install Git, and commit your changes before continuing"
+                <<~MSG.strip
+                  Git is not installed. Please install Git and commit your changes before continuing.
+
+                  The React on Rails generator creates many new files and version control helps
+                  track what was generated versus your existing code.
+                MSG
               end
       message_handler.add_error(error)
       true

data/lib/react_on_rails/helper.rb

@@ -11,10 +11,12 @@ require "addressable/uri"
 require "react_on_rails/utils"
 require "react_on_rails/json_output"
 require "active_support/concern"
+require "react_on_rails/pro/helper"
 
 module ReactOnRails
   module Helper
     include ReactOnRails::Utils::Required
+    include ReactOnRails::Pro::Helper
 
     COMPONENT_HTML_KEY = "componentHtml"
 
@@ -32,7 +34,7 @@ module ReactOnRails
     #
     #   Exposing the react_component_name is necessary to both a plain ReactComponent as well as
     #     a generator:
-    #   See README.md for how to "register" your react components.
+    #   See README.md for how to "register" your React components.
     #   See spec/dummy/client/app/packs/server-bundle.js and
     #     spec/dummy/client/app/packs/client-bundle.js for examples of this.
     #
@@ -61,12 +63,13 @@ module ReactOnRails
 
       case server_rendered_html
       when String
-        build_react_component_result_for_server_rendered_string(
+        html = build_react_component_result_for_server_rendered_string(
           server_rendered_html: server_rendered_html,
           component_specification_tag: internal_result[:tag],
           console_script: console_script,
           render_options: render_options
         )
+        html.html_safe
       when Hash
         msg = <<~MSG
           Use react_component_hash (not react_component) to return a Hash to your ruby view code. See
@@ -119,34 +122,74 @@ module ReactOnRails
     # @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"
+      # stream_react_component doesn't have the prerender option
+      # Because setting prerender to false is equivalent to calling react_component with prerender: false
+      options[:prerender] = true
+      options = options.merge(immediate_hydration: true) unless options.key?(:immediate_hydration)
+      run_stream_inside_fiber do
+        internal_stream_react_component(component_name, options)
       end
+    end
 
-      rendering_fiber = Fiber.new do
-        stream = internal_stream_react_component(component_name, options)
-        stream.each_chunk do |chunk|
-          Fiber.yield chunk
-        end
+    # Renders the React Server Component (RSC) payload for a given component. This helper generates
+    # a special format designed by React for serializing server components and transmitting them
+    # to the client.
+    #
+    # @return [String] Returns a Newline Delimited JSON (NDJSON) stream where each line contains a JSON object with:
+    #   - html: The RSC payload containing the rendered server components and client component references
+    #   - consoleReplayScript: JavaScript to replay server-side console logs in the client
+    #   - hasErrors: Boolean indicating if any errors occurred during rendering
+    #   - isShellReady: Boolean indicating if the initial shell is ready for hydration
+    #
+    # Example NDJSON stream:
+    #   {"html":"<RSC Payload>","consoleReplayScript":"","hasErrors":false,"isShellReady":true}
+    #   {"html":"<RSC Payload>","consoleReplayScript":"console.log('Loading...')","hasErrors":false,"isShellReady":true}
+    #
+    # The RSC payload within the html field contains:
+    # - The component's rendered output from the server
+    # - References to client components that need hydration
+    # - Data props passed to client components
+    #
+    # @param component_name [String] The name of the React component to render. This component should
+    #   be a server component or a mixed component tree containing both server and client components.
+    #
+    # @param options [Hash] Options for rendering the component
+    # @option options [Hash] :props Props to pass to the component (default: {})
+    # @option options [Boolean] :trace Enable tracing for debugging (default: false)
+    # @option options [String] :id Custom DOM ID for the component container (optional)
+    #
+    # @example Basic usage with a server component
+    #   <%= rsc_payload_react_component("ReactServerComponentPage") %>
+    #
+    # @example With props and tracing enabled
+    #   <%= rsc_payload_react_component("RSCPostsPage",
+    #         props: { artificialDelay: 1000 },
+    #         trace: true) %>
+    #
+    # @note This helper requires React Server Components support to be enabled in your configuration:
+    #   ReactOnRailsPro.configure do |config|
+    #     config.enable_rsc_support = true
+    #   end
+    #
+    # @raise [ReactOnRailsPro::Error] if RSC support is not enabled in configuration
+    #
+    # @note You don't have to deal directly with this helper function - it's used internally by the
+    # `rsc_payload_route` helper function. The returned data from this function is used internally by
+    # components registered using the `registerServerComponent` function. Don't use it unless you need
+    # more control over the RSC payload generation. To know more about RSC payload, see the following link:
+    # @see https://www.shakacode.com/react-on-rails-pro/docs/how-react-server-components-works.md
+    #   for technical details about the RSC payload format
+    def rsc_payload_react_component(component_name, options = {})
+      # rsc_payload_react_component doesn't have the prerender option
+      # Because setting prerender to false will not do anything
+      options[:prerender] = true
+      run_stream_inside_fiber do
+        internal_rsc_payload_react_component(component_name, options)
       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
@@ -168,6 +211,7 @@ module ReactOnRails
     #
     def react_component_hash(component_name, options = {})
       options[:prerender] = true
+
       internal_result = internal_react_component(component_name, options)
       server_rendered_html = internal_result[:result]["html"]
       console_script = internal_result[:result]["consoleReplayScript"]
@@ -184,6 +228,7 @@ module ReactOnRails
           console_script: console_script,
           render_options: render_options
         )
+
       else
         msg = <<~MSG
           Render-Function used by react_component_hash for #{component_name} is expected to return
@@ -207,19 +252,22 @@ module ReactOnRails
     # props: Ruby Hash or JSON string which contains the properties to pass to the redux store.
     # Options
     #    defer: false -- pass as true if you wish to render this below your component.
-    def redux_store(store_name, props: {}, defer: false)
+    #    immediate_hydration: false -- React on Rails Pro (licensed) feature. Pass as true if you wish to
+    #                        hydrate this store immediately instead of waiting for the page to load.
+    def redux_store(store_name, props: {}, defer: false, immediate_hydration: nil)
+      immediate_hydration = ReactOnRails.configuration.immediate_hydration if immediate_hydration.nil?
+
       redux_store_data = { store_name: store_name,
-                           props: props }
+                           props: props,
+                           immediate_hydration: immediate_hydration }
       if defer
-        @registered_stores_defer_render ||= []
-        @registered_stores_defer_render << redux_store_data
+        registered_stores_defer_render << redux_store_data
         "YOU SHOULD NOT SEE THIS ON YOUR VIEW -- Uses as a code block, like <% redux_store %> " \
           "and not <%= redux store %>"
       else
-        @registered_stores ||= []
-        @registered_stores << redux_store_data
+        registered_stores << redux_store_data
         result = render_redux_store_data(redux_store_data)
-        prepend_render_rails_context(result)
+        prepend_render_rails_context(result).html_safe
       end
     end
 
@@ -229,9 +277,9 @@ module ReactOnRails
     # client side rendering of this hydration data, which is a hidden div with a matching class
     # that contains a data props.
     def redux_store_hydration_data
-      return if @registered_stores_defer_render.blank?
+      return if registered_stores_defer_render.blank?
 
-      @registered_stores_defer_render.reduce(+"") do |accum, redux_store_data|
+      registered_stores_defer_render.reduce(+"") do |accum, redux_store_data|
         accum << render_redux_store_data(redux_store_data)
       end.html_safe
     end
@@ -292,7 +340,7 @@ module ReactOnRails
 
       html = result["html"]
       console_log_script = result["consoleLogScript"]
-      raw("#{html}#{render_options.replay_console ? console_log_script : ''}")
+      raw("#{html}#{console_log_script if render_options.replay_console}")
     rescue ExecJS::ProgramError => err
       raise ReactOnRails::PrerenderError.new(component_name: "N/A (server_render_js called)",
                                              err: err,
@@ -321,6 +369,7 @@ module ReactOnRails
       # ALERT: Keep in sync with node_package/src/types/index.ts for the properties of RailsContext
       @rails_context ||= begin
         result = {
+          componentRegistryTimeout: ReactOnRails.configuration.component_registry_timeout,
           railsEnv: Rails.env,
           inMailer: in_mailer?,
           # Locale settings
@@ -330,8 +379,14 @@ module ReactOnRails
           # TODO: v13 just use the version if existing
           rorPro: ReactOnRails::Utils.react_on_rails_pro?
         }
+
         if ReactOnRails::Utils.react_on_rails_pro?
           result[:rorProVersion] = ReactOnRails::Utils.react_on_rails_pro_version
+
+          if ReactOnRails::Utils.rsc_support_enabled?
+            rsc_payload_url = ReactOnRailsPro.configuration.rsc_payload_generation_url_path
+            result[:rscPayloadGenerationUrlPath] = rsc_payload_url
+          end
         end
 
         if defined?(request) && request.present?
@@ -352,7 +407,7 @@ module ReactOnRails
           result.merge!(
             # URL settings
             href: uri.to_s,
-            location: "#{uri.path}#{uri.query.present? ? "?#{uri.query}" : ''}",
+            location: "#{uri.path}#{"?#{uri.query}" if uri.query.present?}",
             scheme: uri.scheme, # http
             host: uri.host, # foo.com
             port: uri.port,
@@ -379,17 +434,68 @@ module ReactOnRails
         is_component_pack_present = File.exist?(generated_components_pack_path(react_component_name))
         raise_missing_autoloaded_bundle(react_component_name) unless is_component_pack_present
       end
-      append_javascript_pack_tag("generated/#{react_component_name}",
-                                 defer: ReactOnRails.configuration.defer_generated_component_packs)
+
+      options = { defer: ReactOnRails.configuration.generated_component_packs_loading_strategy == :defer }
+      # Old versions of Shakapacker don't support async script tags.
+      # ReactOnRails.configure already validates if async loading is supported by the installed Shakapacker version.
+      # Therefore, we only need to pass the async option if the loading strategy is explicitly set to :async
+      options[:async] = true if ReactOnRails.configuration.generated_component_packs_loading_strategy == :async
+      append_javascript_pack_tag("generated/#{react_component_name}", **options)
       append_stylesheet_pack_tag("generated/#{react_component_name}")
     end
 
     # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity
 
-    private
+    def run_stream_inside_fiber
+      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 = yield
+        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
+
+    def registered_stores
+      @registered_stores ||= []
+    end
+
+    def registered_stores_defer_render
+      @registered_stores_defer_render ||= []
+    end
+
+    def registered_stores_including_deferred
+      registered_stores + registered_stores_defer_render
+    end
+
+    def create_render_options(react_component_name, options)
+      # If no store dependencies are passed, default to all registered stores up till now
+      unless options.key?(:store_dependencies)
+        store_dependencies = registered_stores_including_deferred.map { |store| store[:store_name] }
+        options = options.merge(store_dependencies: store_dependencies.presence)
+      end
+      ReactOnRails::ReactComponent::RenderOptions.new(react_component_name: react_component_name,
+                                                      options: options)
+    end
 
     def internal_stream_react_component(component_name, options = {})
-      options = options.merge(stream?: true)
+      options = options.merge(render_mode: :html_streaming)
       result = internal_react_component(component_name, options)
       build_react_component_result_for_server_streamed_content(
         rendered_html_stream: result[:result],
@@ -398,6 +504,15 @@ module ReactOnRails
       )
     end
 
+    def internal_rsc_payload_react_component(react_component_name, options = {})
+      options = options.merge(render_mode: :rsc_payload_streaming)
+      render_options = create_render_options(react_component_name, options)
+      json_stream = server_rendered_react_component(render_options)
+      json_stream.transform do |chunk|
+        "#{chunk.to_json}\n".html_safe
+      end
+    end
+
     def generated_components_pack_path(component_name)
       "#{ReactOnRails::PackerUtils.packer_source_entry_path}/generated/#{component_name}.js"
     end
@@ -489,14 +604,13 @@ module ReactOnRails
       )
     end
 
-    def compose_react_component_html_with_spec_and_console(component_specification_tag, rendered_output, console_script)
+    def compose_react_component_html_with_spec_and_console(component_specification_tag, rendered_output,
+                                                           console_script)
       # IMPORTANT: Ensure that we mark string as html_safe to avoid escaping.
-      html_content = <<~HTML
-        #{rendered_output}
-              #{component_specification_tag}
-              #{console_script}
-      HTML
-      html_content.strip.html_safe
+      added_html = "#{component_specification_tag}\n#{console_script}".strip
+      added_html = added_html.present? ? "\n#{added_html}" : ""
+
+      "#{rendered_output}#{added_html}".html_safe
     end
 
     def rails_context_if_not_already_rendered
@@ -514,7 +628,9 @@ module ReactOnRails
 
     # 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
+      rails_context_content = rails_context_if_not_already_rendered
+      rails_context_content = rails_context_content.present? ? "#{rails_context_content}\n" : ""
+      "#{rails_context_content}#{render_value}".html_safe
     end
 
     def internal_react_component(react_component_name, options = {})
@@ -525,26 +641,11 @@ module ReactOnRails
       # (re-hydrate the data). This enables react rendered on the client to see that the
       # server has already rendered the HTML.
 
-      render_options = ReactOnRails::ReactComponent::RenderOptions.new(react_component_name: react_component_name,
-                                                                       options: options)
+      render_options = create_render_options(react_component_name, options)
 
       # Setup the page_loaded_js, which is the same regardless of prerendering or not!
       # The reason is that React is smart about not doing extra work if the server rendering did its job.
-      component_specification_tag = content_tag(:script,
-                                                json_safe_and_pretty(render_options.client_props).html_safe,
-                                                type: "application/json",
-                                                class: "js-react-on-rails-component",
-                                                "data-component-name" => render_options.react_component_name,
-                                                "data-trace" => (render_options.trace ? true : nil),
-                                                "data-dom-id" => render_options.dom_id)
-
-      if render_options.force_load
-        component_specification_tag.concat(
-          content_tag(:script, %(
-ReactOnRails.reactOnRailsComponentLoaded('#{render_options.dom_id}');
-          ).html_safe)
-        )
-      end
+      component_specification_tag = generate_component_script(render_options)
 
       load_pack_for_generated_component(react_component_name, render_options)
       # Create the HTML rendering part
@@ -558,12 +659,9 @@ ReactOnRails.reactOnRailsComponentLoaded('#{render_options.dom_id}');
     end
 
     def render_redux_store_data(redux_store_data)
-      result = content_tag(:script,
-                           json_safe_and_pretty(redux_store_data[:props]).html_safe,
-                           type: "application/json",
-                           "data-js-react-on-rails-store" => redux_store_data[:store_name].html_safe)
+      store_hydration_data = generate_store_script(redux_store_data)
 
-      prepend_render_rails_context(result)
+      prepend_render_rails_context(store_hydration_data)
     end
 
     def props_string(props)
@@ -620,7 +718,7 @@ ReactOnRails.reactOnRailsComponentLoaded('#{render_options.dom_id}');
       js_code = ReactOnRails::ServerRenderingJsCode.server_rendering_component_js_code(
         props_string: props_string(props).gsub("\u2028", '\u2028').gsub("\u2029", '\u2029'),
         rails_context: rails_context(server_side: true).to_json,
-        redux_stores: initialize_redux_stores,
+        redux_stores: initialize_redux_stores(render_options),
         react_component_name: react_component_name,
         render_options: render_options
       )
@@ -636,7 +734,7 @@ ReactOnRails.reactOnRailsComponentLoaded('#{render_options.dom_id}');
                                                js_code: js_code)
       end
 
-      if render_options.stream?
+      if render_options.streaming?
         result.transform do |chunk_json_result|
           if should_raise_streaming_prerender_error?(chunk_json_result, render_options)
             raise_prerender_error(chunk_json_result, react_component_name, props, js_code)
@@ -651,17 +749,20 @@ ReactOnRails.reactOnRailsComponentLoaded('#{render_options.dom_id}');
       result
     end
 
-    def initialize_redux_stores
+    def initialize_redux_stores(render_options)
       result = +<<-JS
       ReactOnRails.clearHydratedStores();
       JS
 
-      return result unless @registered_stores.present? || @registered_stores_defer_render.present?
+      store_dependencies = render_options.store_dependencies
+      return result unless store_dependencies.present?
 
       declarations = +"var reduxProps, store, storeGenerator;\n"
-      all_stores = (@registered_stores || []) + (@registered_stores_defer_render || [])
+      store_objects = registered_stores_including_deferred.select do |store|
+        store_dependencies.include?(store[:store_name])
+      end
 
-      result << all_stores.each_with_object(declarations) do |redux_store_data, memo|
+      result << store_objects.each_with_object(declarations) do |redux_store_data, memo|
         store_name = redux_store_data[:store_name]
         props = props_string(redux_store_data[:props])
         memo << <<-JS.strip_heredoc
@@ -687,6 +788,7 @@ ReactOnRails.reactOnRailsComponentLoaded('#{render_options.dom_id}');
 
     if defined?(ScoutApm)
       include ScoutApm::Tracer
+
       instrument_method :react_component, type: "ReactOnRails", name: "react_component"
       instrument_method :react_component_hash, type: "ReactOnRails", name: "react_component_hash"
     end

data/lib/react_on_rails/json_parse_error.rb

@@ -7,7 +7,12 @@ module ReactOnRails
     def initialize(parse_error:, json:)
       @json = json
       @original_error = parse_error
-      super(parse_error.message)
+      message = <<~MSG
+        #{parse_error.message}
+
+        #{Utils.default_troubleshooting_section}
+      MSG
+      super(message)
     end
 
     def to_honeybadger_context