react_on_rails 17.0.0.rc.5 → 17.0.0.rc.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 483be34de15d43cc71b1f39a384275d9f3af3b90f201c5777785d24e9377cceb
-  data.tar.gz: 2fa0039ba762f2a0e26882c1729c914c252197f99aedfc498b344a341863657f
+  metadata.gz: 60603cec3dbd4b84deedfe50bc3abcee226363d53fb0250e175f4b9af3f88492
+  data.tar.gz: 2a72fffbf70d1b840aeedfed0f7eafa2e378684e8688bef5c1b0b750749a4654
 SHA512:
-  metadata.gz: 2c8e998f636ef7aa1465d12587c7536150b83ec2a9b72a546610cbdc38cc29237cb9bb27e247637b60cf3b58385cca6d2c0dc06d267c1aa0adfc112e2d987abf
-  data.tar.gz: c98e20ac4c306db1faaa0eb49d4155f103057b5fc24baa8f57be7ac7c0325bdd1a2ab8e03f43dbefd01572ef9fbfd53a7c372549d44cb2f15b5072cdb81d155d
+  metadata.gz: f0dfddc3d2db936834d1d03f2c69c491359b482d1849d53cb08c6cbc07a052a96a73619ac6deccee5263cb8a72d03770ff9da8217309447330fde064f586a5c6
+  data.tar.gz: 525a931c6f9999180a3b388cd09f0cafabad9864b64adf5bb3fd824757c8f1c0511be22b6b0214d3d4c79ba9ef0c4ea5302e58378e659b9b478aae53979040c4

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    react_on_rails (17.0.0.rc.5)
+    react_on_rails (17.0.0.rc.6)
       addressable
       connection_pool
       execjs (~> 2.5)

data/lib/generators/react_on_rails/base_generator.rb

@@ -188,11 +188,46 @@ module ReactOnRails
         route "get 'hello_world', to: 'hello_world#index'"
       end
 
+      def copy_packer_config
+        # Rails generator actions run in method definition order.
+        # Keep this before actions that call shakapacker_source_path or
+        # shakapacker_source_entry_path; those helpers memoize on first read.
+        if instance_variable_defined?(:@shakapacker_source_path) ||
+           instance_variable_defined?(:@shakapacker_source_entry_path)
+          raise Thor::Error, "copy_packer_config must run before path-dependent generator actions"
+        end
+
+        base_path = "base/base/"
+        config = "config/shakapacker.yml"
+        use_rspack = using_rspack?
+
+        if options.shakapacker_just_installed?
+          say "Replacing Shakapacker default config with React on Rails version"
+          # Shakapacker's installer just created this file from scratch (no pre-existing config).
+          # Safe to overwrite silently with RoR's version-aware template (e.g., private_output_path).
+          template("#{base_path}#{config}.tt", config, force: true)
+        else
+          say "Adding Shakapacker #{ReactOnRails::PackerUtils.shakapacker_version} config"
+          # Thor handles the conflict: prompts user interactively, or respects --force/--skip flags.
+          template("#{base_path}#{config}.tt", config)
+        end
+
+        # Configure bundler-specific settings
+        configure_rspack_in_shakapacker if use_rspack
+
+        # Always ensure precompile_hook is configured (Shakapacker 9.0+ only)
+        configure_precompile_hook_in_shakapacker
+
+        # For SSR bundles, configure Shakapacker private_output_path (9.0+ only)
+        # This keeps Shakapacker and React on Rails server bundle paths in sync.
+        configure_private_output_path_in_shakapacker
+      end
+
       def create_react_directories
         # Skip HelloWorld directory for Redux (uses HelloWorldApp) or RSC (uses HelloServer)
         return if options.redux? || use_rsc?
 
-        empty_directory("app/javascript/src/HelloWorld/ror_components")
+        empty_directory(File.join(example_component_source_directory("HelloWorld"), "ror_components"))
       end
 
       def copy_base_files
@@ -235,14 +270,15 @@ module ReactOnRails
 
       def copy_js_bundle_files
         base_path = "base/base/"
-        base_files = %w[app/javascript/packs/server-bundle.js]
+        copy_file("#{base_path}app/javascript/packs/server-bundle.js",
+                  shakapacker_entrypoint_path("server-bundle.js"))
 
         # Skip HelloWorld CSS for Redux (uses HelloWorldApp) or RSC (uses HelloServer)
-        unless options.redux? || use_rsc? || use_tailwind?
-          base_files << "app/javascript/src/HelloWorld/ror_components/HelloWorld.module.css"
-        end
+        return if options.redux? || use_rsc? || use_tailwind?
 
-        base_files.each { |file| copy_file("#{base_path}#{file}", file) }
+        copy_file("#{base_path}app/javascript/src/HelloWorld/ror_components/HelloWorld.module.css",
+                  File.join(example_component_source_directory("HelloWorld"),
+                            "ror_components/HelloWorld.module.css"))
       end
 
       def copy_webpack_config
@@ -274,33 +310,7 @@ module ReactOnRails
 
         base_path = "base/tailwind/"
         copy_file("#{base_path}app/javascript/stylesheets/application.css",
-                  "app/javascript/stylesheets/application.css")
-      end
-
-      def copy_packer_config
-        base_path = "base/base/"
-        config = "config/shakapacker.yml"
-
-        if options.shakapacker_just_installed?
-          say "Replacing Shakapacker default config with React on Rails version"
-          # Shakapacker's installer just created this file from scratch (no pre-existing config).
-          # Safe to overwrite silently with RoR's version-aware template (e.g., private_output_path).
-          template("#{base_path}#{config}.tt", config, force: true)
-        else
-          say "Adding Shakapacker #{ReactOnRails::PackerUtils.shakapacker_version} config"
-          # Thor handles the conflict: prompts user interactively, or respects --force/--skip flags.
-          template("#{base_path}#{config}.tt", config)
-        end
-
-        # Configure bundler-specific settings
-        configure_rspack_in_shakapacker if using_rspack?
-
-        # Always ensure precompile_hook is configured (Shakapacker 9.0+ only)
-        configure_precompile_hook_in_shakapacker
-
-        # For SSR bundles, configure Shakapacker private_output_path (9.0+ only)
-        # This keeps Shakapacker and React on Rails server bundle paths in sync.
-        configure_private_output_path_in_shakapacker
+                  shakapacker_stylesheet_path("application.css"))
       end
 
       def add_base_gems_to_gemfile
@@ -686,10 +696,10 @@ module ReactOnRails
       end
 
       def example_source_path
-        return "app/javascript/src/HelloServer/" if use_rsc? && !options.redux?
-        return "app/javascript/src/HelloWorldApp/" if options.redux?
+        return example_component_source_path("HelloServer") if use_rsc? && !options.redux?
+        return example_component_source_path("HelloWorldApp") if options.redux?
 
-        "app/javascript/src/HelloWorld/"
+        example_component_source_path("HelloWorld")
       end
 
       def example_view_path

data/lib/generators/react_on_rails/demo_page_config.rb

@@ -15,13 +15,13 @@ module ReactOnRails
         }
       end
 
-      def build_hello_server_view_config(landing_page:, redux_demo:)
+      def build_hello_server_view_config(landing_page:, redux_demo:, source_path:)
         {
           title: "React Server Components Demo",
           intro: "This route shows the Pro React Server Components flow: Rails streams an async server " \
                  "component response while only client islands ship JavaScript to the browser.",
           highlights: hello_server_highlights,
-          file_hints: hello_server_file_hints,
+          file_hints: hello_server_file_hints(source_path:),
           quick_links: hello_server_quick_links(landing_page:, redux_demo:),
           learning_links: hello_server_learning_links
         }
@@ -167,10 +167,10 @@ module ReactOnRails
         ]
       end
 
-      def hello_server_file_hints
+      def hello_server_file_hints(source_path:)
         [
           {
-            path: "app/javascript/src/HelloServer/",
+            path: source_path,
             description: "Source for the generated server component example and client island."
           },
           {

data/lib/generators/react_on_rails/generator_helper.rb

@@ -1,12 +1,17 @@
 # frozen_string_literal: true
 
 require "json"
+require "pathname"
 require_relative "shakapacker_precompile_hook_helper"
 
 # rubocop:disable Metrics/ModuleLength
 module GeneratorHelper
   include ReactOnRails::Generators::ShakapackerPrecompileHookHelper
 
+  DEFAULT_SHAKAPACKER_SOURCE_PATH = "app/javascript"
+  DEFAULT_SHAKAPACKER_SOURCE_ENTRY_PATH = "packs"
+  private_constant :DEFAULT_SHAKAPACKER_SOURCE_PATH, :DEFAULT_SHAKAPACKER_SOURCE_ENTRY_PATH
+
   def package_json
     # Lazy load package_json gem only when actually needed for dependency management
 
@@ -75,6 +80,108 @@ module GeneratorHelper
     options.typescript? ? "tsx" : "jsx"
   end
 
+  def shakapacker_source_path
+    # These helpers memoize config-backed paths. Install generators must copy or
+    # overwrite config/shakapacker.yml before any path-dependent copy action runs.
+    @shakapacker_source_path ||= configured_shakapacker_relative_path("source_path", DEFAULT_SHAKAPACKER_SOURCE_PATH)
+  end
+
+  def shakapacker_source_entry_path
+    @shakapacker_source_entry_path ||= configured_shakapacker_relative_path(
+      "source_entry_path",
+      DEFAULT_SHAKAPACKER_SOURCE_ENTRY_PATH,
+      allow_root: true
+    )
+  end
+
+  def shakapacker_entrypoint_path(filename)
+    filename = filename.to_s
+    raise ArgumentError, "filename must be present" if filename.empty?
+
+    entry_dir = shakapacker_source_entry_path # "" means entrypoints live directly under source_path.
+    File.join(*[shakapacker_source_path, entry_dir, filename].reject(&:empty?))
+  end
+
+  def shakapacker_stylesheet_path(filename)
+    # "stylesheets" is a generated demo convention, not a Shakapacker config key.
+    File.join(shakapacker_source_path, "stylesheets", filename)
+  end
+
+  def relative_stylesheet_import_path(entry_path, filename: "application.css")
+    # InstallGenerator copies the final Shakapacker config before path-dependent demo files are generated.
+    safe_entry_path = safe_generator_destination_path(entry_path, default: nil)
+    raise ArgumentError, "entry_path must stay inside the generator destination" if safe_entry_path.nil?
+
+    entry_dir = Pathname.new(File.join(destination_root, safe_entry_path)).dirname
+    stylesheet = Pathname.new(File.join(destination_root, shakapacker_stylesheet_path(filename)))
+
+    stylesheet.relative_path_from(entry_dir).to_s
+  end
+
+  def example_component_source_directory(component_name)
+    File.join(shakapacker_source_path, "src", component_name)
+  end
+
+  def example_component_source_path(component_name)
+    # Trailing slash is intentional: this value is only for generated demo file hints.
+    "#{example_component_source_directory(component_name)}/"
+  end
+
+  def configured_shakapacker_relative_path(config_key, default, allow_root: false)
+    config_path = File.join(destination_root, "config/shakapacker.yml")
+    return default unless File.exist?(config_path)
+
+    config = parse_shakapacker_yml(config_path)
+    configured_path = shakapacker_path_config_value(config, config_key)
+
+    safe_generator_destination_path(configured_path, default:, allow_root:)
+  rescue Psych::SyntaxError
+    default
+  end
+
+  def shakapacker_path_config_value(config, config_key)
+    # Generators run in the development context, so prefer that section before falling back to shared defaults.
+    %w[development default].each do |section_name|
+      section = shakapacker_config_section(config, section_name)
+      value = shakapacker_config_value(section, config_key)
+      return value unless value.to_s.strip.empty?
+    end
+
+    nil
+  end
+
+  def safe_generator_destination_path(path, default:, allow_root: false)
+    candidate = path.to_s.strip
+    return default if candidate.empty?
+
+    pathname = Pathname.new(candidate).cleanpath
+    # Shakapacker uses "/" to mean entrypoints live directly under source_path.
+    return "" if allow_root && pathname.to_s == "/"
+
+    relative_path = if pathname.absolute?
+                      absolute_path_relative_to_destination(pathname)
+                    else
+                      pathname.to_s
+                    end
+
+    return default if unsafe_generator_destination_path?(relative_path)
+
+    relative_path
+  rescue ArgumentError # Pathname.new raises on null bytes in path strings.
+    default
+  end
+
+  def absolute_path_relative_to_destination(pathname)
+    destination = Pathname.new(destination_root).cleanpath
+    pathname.relative_path_from(destination).to_s
+  rescue ArgumentError
+    nil # Signals the caller to fall back to the default path.
+  end
+
+  def unsafe_generator_destination_path?(path)
+    path.nil? || path == "." || path == ".." || path.start_with?("../")
+  end
+
   # Check if a gem is present in Gemfile.lock
   # Always checks the target app's Gemfile.lock, not inherited BUNDLE_GEMFILE
   # See: https://github.com/shakacode/react_on_rails/issues/2287

data/lib/generators/react_on_rails/install_generator.rb

@@ -234,11 +234,7 @@ module ReactOnRails
 
       def invoke_generators
         ensure_shakapacker_installed
-        if options.typescript?
-          install_typescript_dependencies
-          create_css_module_types
-          create_typescript_config
-        end
+        install_typescript_dependencies if options.typescript?
         # `invoke` instantiates child generators with a fresh options hash, so
         # --pretend/--force/--skip must be forwarded explicitly at each boundary.
         invoke "react_on_rails:base", [],
@@ -247,6 +243,11 @@ module ReactOnRails
                  shakapacker_just_installed: shakapacker_just_installed?,
                  force: options[:force], skip: options[:skip], pretend: options[:pretend] }
 
+        if options.typescript?
+          create_css_module_types
+          create_typescript_config
+        end
+
         # Component generator logic:
         # - --rsc without --redux: Skip HelloWorld, HelloServer will be generated in setup_rsc
         # - --rsc with --redux: Generate HelloWorldApp (user explicitly wants Redux) + HelloServer
@@ -923,10 +924,10 @@ module ReactOnRails
         # Resolve the bundler via using_rspack?. shakapacker.yml doesn't exist yet at this point,
         # so the fresh-install default applies: an unset --rspack flag resolves to Rspack when
         # Shakapacker supports it (shakapacker_version_9_or_higher? is optimistically true on a
-        # brand-new install where Shakapacker isn't loaded yet). An explicit --no-rspack still
-        # selects Webpack. using_rspack? memoizes, so the rest of the run (e.g.
-        # configure_rspack_in_shakapacker) stays consistent with this decision.
-        shakapacker_install_env = using_rspack? ? { "SHAKAPACKER_ASSETS_BUNDLER" => "rspack" } : {}
+        # brand-new install where Shakapacker isn't loaded yet). Pass the resolved choice explicitly
+        # so Shakapacker installs dependencies for the same bundler that React on Rails configures.
+        assets_bundler = using_rspack? ? "rspack" : "webpack"
+        shakapacker_install_env = { "SHAKAPACKER_ASSETS_BUNDLER" => assets_bundler }
         success = Bundler.with_unbundled_env do
           system(shakapacker_install_env, "bundle exec rails shakapacker:install")
         end
@@ -1169,9 +1170,7 @@ module ReactOnRails
 
         say "📝 Creating CSS module type definitions...", :yellow
 
-        # Ensure the types directory exists
-        FileUtils.mkdir_p("app/javascript/types")
-
+        css_module_types_path = File.join(shakapacker_source_path, "types", "css-modules.d.ts")
         css_module_types_content = <<~TS.strip
           // TypeScript definitions for CSS modules
           declare module "*.module.css" {
@@ -1190,7 +1189,7 @@ module ReactOnRails
           }
         TS
 
-        File.write("app/javascript/types/css-modules.d.ts", css_module_types_content)
+        create_file(css_module_types_path, css_module_types_content)
         say "✅ Created CSS module type definitions", :green
       end
 
@@ -1222,7 +1221,7 @@ module ReactOnRails
             "jsx" => "react-jsx"
           },
           "include" => [
-            "app/javascript/**/*"
+            File.join(shakapacker_source_path, "**/*")
           ]
         }
 

data/lib/generators/react_on_rails/js_dependency_manager.rb

@@ -160,10 +160,9 @@ module ReactOnRails
       # prerelease RSC package broadly enough to keep `npm ls` healthy, but generator behavior still
       # installs the tested React 19.0.x range and exact RSC package pin until both policies advance.
       RSC_REACT_VERSION_RANGE = "~19.0.4"
-      # Pinned to 19.0.5-rc.7 because the discovery plugin export, native Rspack plugin, and
-      # RSC manifest CSS fixes all ship in that prerelease.
-      # TODO(#3642): switch to a stable react-on-rails-rsc release after 19.0.5 stable ships.
-      RSC_PACKAGE_VERSION_PIN = "19.0.5-rc.7"
+      # Pinned to the stable 19.0.5 release, which carries the discovery plugin export, native
+      # Rspack plugin, and RSC manifest CSS fixes.
+      RSC_PACKAGE_VERSION_PIN = "19.0.5"
 
       private
 
@@ -489,23 +488,42 @@ module ReactOnRails
         RSC_PACKAGE_VERSION_PIN.split("-", 2).first
       end
 
+      def rsc_package_version_prerelease?
+        RSC_PACKAGE_VERSION_PIN.include?("-")
+      end
+
       def rsc_dependency_pin_info
-        "React Server Components package pin: all --rsc installs temporarily use " \
-          "react-on-rails-rsc@#{RSC_PACKAGE_VERSION_PIN}, including Webpack projects. " \
-          "This prerelease keeps react-on-rails-rsc/WebpackPlugin compatible while adding " \
-          "react-on-rails-rsc/RspackPlugin. Keep the pin until stable " \
-          "react-on-rails-rsc@#{rsc_stable_package_version_target} " \
-          "is published and tagged latest."
+        if rsc_package_version_prerelease?
+          "React Server Components package pin: all --rsc installs temporarily use " \
+            "react-on-rails-rsc@#{RSC_PACKAGE_VERSION_PIN}, including Webpack projects. " \
+            "This prerelease keeps react-on-rails-rsc/WebpackPlugin compatible while adding " \
+            "react-on-rails-rsc/RspackPlugin. Keep the pin until stable " \
+            "react-on-rails-rsc@#{rsc_stable_package_version_target} " \
+            "is published and tagged latest."
+        else
+          "React Server Components package pin: all --rsc installs use " \
+            "react-on-rails-rsc@#{RSC_PACKAGE_VERSION_PIN}, including Webpack projects. " \
+            "This pin keeps react-on-rails-rsc/WebpackPlugin compatible while adding " \
+            "react-on-rails-rsc/RspackPlugin."
+        end
       end
 
       def rsc_dependency_pin_failed_warning
-        "Warning: Could not install the pinned react-on-rails-rsc@#{RSC_PACKAGE_VERSION_PIN}. " \
-          "All RSC projects are temporarily pinned to that version: the prerelease keeps " \
-          "react-on-rails-rsc/WebpackPlugin compatible while adding react-on-rails-rsc/RspackPlugin, " \
-          "and the unversioned `latest` tag may not include both until stable " \
-          "#{rsc_stable_package_version_target} " \
-          "is published, so the generator left the version pin in package.json rather than " \
-          "install a potentially incompatible version."
+        if rsc_package_version_prerelease?
+          "Warning: Could not install the pinned react-on-rails-rsc@#{RSC_PACKAGE_VERSION_PIN}. " \
+            "All RSC projects are temporarily pinned to that version: the prerelease keeps " \
+            "react-on-rails-rsc/WebpackPlugin compatible while adding react-on-rails-rsc/RspackPlugin, " \
+            "and the unversioned `latest` tag may not include both until stable " \
+            "#{rsc_stable_package_version_target} " \
+            "is published, so the generator left the version pin in package.json rather than " \
+            "install a potentially incompatible version."
+        else
+          "Warning: Could not install the pinned react-on-rails-rsc@#{RSC_PACKAGE_VERSION_PIN}. " \
+            "All RSC projects are pinned to that version: this pin keeps " \
+            "react-on-rails-rsc/WebpackPlugin compatible while adding react-on-rails-rsc/RspackPlugin, " \
+            "so the generator left the version pin in package.json rather than " \
+            "install a potentially incompatible version."
+        end
       end
 
       def rsc_dependency_pin_failure_details(used_version_pins)

data/lib/generators/react_on_rails/react_no_redux_generator.rb

@@ -32,22 +32,27 @@ module ReactOnRails
         base_js_path = "base/base"
         tailwind_js_path = "base/tailwind"
         ext = component_extension(options)
+        component_dir = example_component_source_directory("HelloWorld")
 
         # Determine which component files to copy based on TypeScript option
         client_component =
-          "app/javascript/src/HelloWorld/ror_components/HelloWorld.client.#{ext}"
+          "#{component_dir}/ror_components/HelloWorld.client.#{ext}"
         server_component =
-          "app/javascript/src/HelloWorld/ror_components/HelloWorld.server.#{ext}"
+          "#{component_dir}/ror_components/HelloWorld.server.#{ext}"
+        client_component_template = "app/javascript/src/HelloWorld/ror_components/HelloWorld.client.#{ext}"
 
+        # Source paths are relative to this generator's templates; only
+        # destinations vary with the app's Shakapacker config.
         if use_tailwind?
-          copy_file("#{tailwind_js_path}/#{client_component}", client_component)
+          copy_file("#{tailwind_js_path}/#{client_component_template}", client_component)
         else
-          copy_file("#{base_js_path}/#{client_component}", client_component)
+          copy_file("#{base_js_path}/#{client_component_template}", client_component)
           copy_file("#{base_js_path}/app/javascript/src/HelloWorld/ror_components/HelloWorld.module.css",
-                    "app/javascript/src/HelloWorld/ror_components/HelloWorld.module.css")
+                    "#{component_dir}/ror_components/HelloWorld.module.css")
         end
 
-        copy_file("#{base_js_path}/#{server_component}", server_component)
+        copy_file("#{base_js_path}/app/javascript/src/HelloWorld/ror_components/HelloWorld.server.#{ext}",
+                  server_component)
       end
 
       def create_appropriate_templates
@@ -58,7 +63,7 @@ module ReactOnRails
                  "app/views/hello_world/index.html.erb",
                  build_hello_world_view_config(
                    component_name: "HelloWorld",
-                   source_path: "app/javascript/src/HelloWorld/",
+                   source_path: example_component_source_path("HelloWorld"),
                    landing_page: new_app_landing_page_available?,
                    redux: false,
                    rsc_demo: false

data/lib/generators/react_on_rails/react_with_redux_generator.rb

@@ -41,42 +41,42 @@ module ReactOnRails
                    hide: true
 
       def create_redux_directories
+        component_dir = example_component_source_directory("HelloWorldApp")
+
         # Create auto-bundling directory structure for Redux
-        empty_directory("app/javascript/src/HelloWorldApp/ror_components")
+        empty_directory("#{component_dir}/ror_components")
 
         # Create Redux support directories within the component directory
         dirs = %w[actions constants containers reducers store components]
-        dirs.each { |name| empty_directory("app/javascript/src/HelloWorldApp/#{name}") }
+        dirs.each { |name| empty_directory("#{component_dir}/#{name}") }
       end
 
       def copy_base_files
         base_js_path = "redux/base"
         ext = component_extension(options)
+        component_dir = example_component_source_directory("HelloWorldApp")
 
         # Copy Redux-connected component to auto-bundling structure
         copy_file("#{base_js_path}/app/javascript/bundles/HelloWorld/startup/HelloWorldApp.client.#{ext}",
-                  "app/javascript/src/HelloWorldApp/ror_components/HelloWorldApp.client.#{ext}")
+                  "#{component_dir}/ror_components/HelloWorldApp.client.#{ext}")
         copy_file("#{base_js_path}/app/javascript/bundles/HelloWorld/startup/HelloWorldApp.server.#{ext}",
-                  "app/javascript/src/HelloWorldApp/ror_components/HelloWorldApp.server.#{ext}")
+                  "#{component_dir}/ror_components/HelloWorldApp.server.#{ext}")
 
         unless use_tailwind?
           copy_file("#{base_js_path}/app/javascript/bundles/HelloWorld/components/HelloWorld.module.css",
-                    "app/javascript/src/HelloWorldApp/components/HelloWorld.module.css")
+                    "#{component_dir}/components/HelloWorld.module.css")
         end
 
-        # Update import paths in client component
-        ror_client_file = "app/javascript/src/HelloWorldApp/ror_components/HelloWorldApp.client.#{ext}"
-        gsub_file(ror_client_file, "../store/helloWorldStore", "../store/helloWorldStore")
-        gsub_file(ror_client_file, "../containers/HelloWorldContainer",
-                  "../containers/HelloWorldContainer")
         return unless use_tailwind?
 
-        stylesheet_import = "import '../../../stylesheets/application.css';\n"
-        ror_client_file_path = File.join(destination_root, ror_client_file)
+        ror_client_file = "#{component_dir}/ror_components/HelloWorldApp.client.#{ext}"
         if options[:pretend]
           say_status :pretend, "Would add Tailwind stylesheet import to #{ror_client_file}", :yellow
           return
         end
+
+        stylesheet_import = "import '#{relative_stylesheet_import_path(ror_client_file)}';\n"
+        ror_client_file_path = File.join(destination_root, ror_client_file)
         return if File.read(ror_client_file_path).include?(stylesheet_import)
 
         prepend_to_file(ror_client_file, stylesheet_import)
@@ -86,6 +86,7 @@ module ReactOnRails
         base_hello_world_path = "redux/base/app/javascript/bundles/HelloWorld"
         tailwind_hello_world_path = "redux/tailwind/app/javascript/bundles/HelloWorld"
         redux_extension = options.typescript? ? "ts" : "js"
+        component_dir = example_component_source_directory("HelloWorldApp")
 
         # Copy Redux infrastructure files with appropriate extension
         %W[actions/helloWorldActionCreators.#{redux_extension}
@@ -94,13 +95,13 @@ module ReactOnRails
            reducers/helloWorldReducer.#{redux_extension}
            store/helloWorldStore.#{redux_extension}].each do |file|
              copy_file("#{base_hello_world_path}/#{file}",
-                       "app/javascript/src/HelloWorldApp/#{file}")
+                       "#{component_dir}/#{file}")
            end
 
         component_file = "components/HelloWorld.#{component_extension(options)}"
         component_source_path = use_tailwind? ? tailwind_hello_world_path : base_hello_world_path
         copy_file("#{component_source_path}/#{component_file}",
-                  "app/javascript/src/HelloWorldApp/#{component_file}")
+                  "#{component_dir}/#{component_file}")
       end
 
       def create_appropriate_templates
@@ -111,7 +112,7 @@ module ReactOnRails
                  "app/views/hello_world/index.html.erb",
                  build_hello_world_view_config(
                    component_name: "HelloWorldApp",
-                   source_path: "app/javascript/src/HelloWorldApp/",
+                   source_path: example_component_source_path("HelloWorldApp"),
                    landing_page: new_app_landing_page_available?,
                    redux: true,
                    rsc_demo: options[:rsc]

data/lib/generators/react_on_rails/rsc_setup.rb

@@ -198,7 +198,7 @@ module ReactOnRails
       end
 
       def create_hello_server_component
-        hello_server_dir = "app/javascript/src/HelloServer"
+        hello_server_dir = example_component_source_directory("HelloServer")
         ror_components_dir = "#{hello_server_dir}/ror_components"
         components_dir = "#{hello_server_dir}/components"
         ext = component_extension(options)
@@ -246,8 +246,7 @@ module ReactOnRails
         end
         return false unless relative_entry_path
 
-        # Path is relative to app/javascript/src/HelloServer/components/.
-        stylesheet_import = "import '../../../stylesheets/application.css';"
+        stylesheet_import = "import '#{relative_stylesheet_import_path(relative_entry_path)}';"
         entry_path = File.join(destination_root, relative_entry_path)
         entry_content = File.read(entry_path)
         return false if entry_content.include?(stylesheet_import)
@@ -296,7 +295,8 @@ module ReactOnRails
                  view_path,
                  build_hello_server_view_config(
                    landing_page: new_app_landing_page_available?,
-                   redux_demo: options[:redux]
+                   redux_demo: options[:redux],
+                   source_path: example_component_source_path("HelloServer")
                  ))
 
         say "✅ Created #{view_path}", :green

data/lib/generators/react_on_rails/templates/base/base/app/views/hello_world/index.html.erb.tt

@@ -129,6 +129,15 @@
     background: rgba(17, 32, 49, 0.06);
     color: var(--ink);
     font-size: 0.95em;
+    overflow-wrap: anywhere;
+    word-break: break-word;
+  }
+
+  .path-hint {
+    display: inline-block;
+    max-width: 100%;
+    overflow-wrap: anywhere;
+    word-break: break-word;
   }
 
   @media (max-width: 900px) {
@@ -179,7 +188,7 @@
       <ul>
         <% config[:file_hints].each do |hint| %>
           <li>
-            <code><%= hint[:path] %></code><br>
+            <code class="path-hint"><%= hint[:path] %></code><br>
             <%= hint[:description] %>
           </li>
         <% end %>

data/lib/generators/react_on_rails/templates/base/base/app/views/home/index.html.erb.tt

@@ -259,13 +259,18 @@
     letter-spacing: 0.08em;
   }
 
+  /* Home-page code samples are all compact commands or path hints, so they share wrapping rules. */
   .command-list code,
   .hint-list code {
+    display: inline-block;
+    max-width: 100%;
     padding: 2px 6px;
     border-radius: 8px;
     background: rgba(17, 32, 49, 0.06);
     color: var(--ink);
     font-size: 0.95em;
+    overflow-wrap: anywhere;
+    word-break: break-word;
   }
 
   .footer-note {

data/lib/generators/react_on_rails/templates/base/base/config/webpack/serverWebpackConfig.js.tt

@@ -219,6 +219,22 @@ const configureServer = () => {
 
   // Disable Node.js polyfills - not needed when targeting Node
   serverWebpackConfig.node = false;
+
+  // Source-mapped SSR stack traces in production:
+  // The Pro Node renderer can remap bundled stack frames back to your original
+  // source files (see docs/oss/building-features/node-renderer/debugging.md). This
+  // needs source maps in the *production* server bundle, which the default above
+  // disables (`devtool: false`). To opt in, replace only the `serverWebpackConfig.devtool`
+  // assignment above (keep the eval-devtool note) with a production-aware variant so
+  // development is unaffected. Both examples below use non-`eval` devtools, satisfying
+  // that constraint. E.g.:
+  //   serverWebpackConfig.devtool = process.env.NODE_ENV === 'production' ? 'source-map' : 'cheap-module-source-map';
+  //     // 'source-map' — external .map (smaller bundle; stage the .map next to the uploaded bundle)
+  //   serverWebpackConfig.devtool = process.env.NODE_ENV === 'production' ? 'inline-source-map' : 'cheap-module-source-map';
+  //     // 'inline-source-map' — simplest; map travels inside the bundle (larger file)
+  // The server bundle is never served to browsers; still, never expose
+  // server-bundle source maps publicly.
+
 <% else -%>
   // If using the default 'web', then libraries like Emotion and loadable-components
   // break with SSR. The fix is to use a node renderer and change the target.

data/lib/generators/react_on_rails/templates/rsc/base/app/views/hello_server/index.html.erb.tt

@@ -131,6 +131,13 @@
     font-size: 0.95em;
   }
 
+  .path-hint {
+    display: inline-block;
+    max-width: 100%;
+    overflow-wrap: anywhere;
+    word-break: break-word;
+  }
+
   @media (max-width: 900px) {
     .hero,
     .card,
@@ -179,7 +186,7 @@
       <ul>
         <% config[:file_hints].each do |hint| %>
           <li>
-            <code><%= hint[:path] %></code><br>
+            <code class="path-hint"><%= hint[:path] %></code><br>
             <%= hint[:description] %>
           </li>
         <% end %>

data/lib/generators/react_on_rails/templates/rsc/base/config/webpack/rscWebpackConfig.js.tt

@@ -50,10 +50,13 @@ const configureRsc = () => {
   // Pass true to skip the RSC manifest plugin - RSC bundle doesn't need it
   const rscConfig = serverWebpackConfig(true);
   const discoveryBuild = process.env.RSC_REFERENCE_DISCOVERY_BUILD === 'true';
+  // Shakapacker uses "/" to mean entrypoints live directly under source_path.
+  // Keep that sentinel relative so path.resolve does not escape to the filesystem root.
+  const sourceEntryPath = config.source_entry_path === '/' ? '' : config.source_entry_path;
 
   const defaultServerComponentRegistrationEntry = resolve(
     config.source_path,
-    config.source_entry_path,
+    sourceEntryPath,
     '../generated/server-component-registration-entry.js',
   );
   const expectedServerComponentRegistrationEntry = 'server-component-registration-entry.js';

data/lib/react_on_rails/length_prefixed_parser.rb

@@ -11,6 +11,11 @@ module ReactOnRails
   # Used by both streaming (Pro) and non-streaming (OSS) paths.
   # Strict protocol parser — any format violation raises an error.
   class LengthPrefixedParser
+    # Keep aligned with ReactOnRailsPro::StreamRequest::CONTROL_MESSAGE_TYPES,
+    # which routes these same control frames during bidirectional streaming.
+    CONTROL_MESSAGE_TYPES = %w[propRequest renderComplete].freeze
+    private_constant :CONTROL_MESSAGE_TYPES
+
     # Parses a complete length-prefixed result string that must contain exactly one chunk.
     # Used by the non-streaming rendering path where ExecJS/node renderer returns a single result.
     # Returns a single Hash: { "html" => String|nil, "consoleReplayScript" => "...", ... }
@@ -127,6 +132,20 @@ module ReactOnRails
       raw_content = @buf.byteslice(0, @content_len).force_encoding(Encoding::UTF_8)
       @buf = @buf.byteslice(@content_len, @buf.bytesize - @content_len)
 
+      # Control messages (propRequest, renderComplete) have no HTML payload;
+      # raw_content is therefore empty and intentionally unused. Those two
+      # messageType values are reserved by the wire format. Other messageType
+      # metadata is treated as ordinary chunk metadata so future tracing or
+      # diagnostics annotations cannot be swallowed accidentally.
+      if CONTROL_MESSAGE_TYPES.include?(@metadata["messageType"])
+        @metadata.delete("payloadType")
+        result = @metadata
+        @metadata = nil
+        @state = :header
+        yield result
+        return true
+      end
+
       # Reconstruct html type based on payloadType:
       #   "object" → JSON-serialized value (ServerRenderHash or null), needs JSON.parse
       #   "string" → raw HTML string, used as-is

data/lib/react_on_rails/locales/base.rb

@@ -77,10 +77,15 @@ module ReactOnRails
       def obsolete?
         return true if exist_files.length != files.length # Some files missing
         return true if exist_files.empty?
+        return true if generated_files_obsolete?
 
         files_are_outdated
       end
 
+      def generated_files_obsolete?
+        false
+      end
+
       def exist_files
         @exist_files ||= files.select { |file| File.exist?(file) }
       end
@@ -188,11 +193,9 @@ module ReactOnRails
 
       def template_default
         <<~JS
-          import { defineMessages } from 'react-intl';
-
-          const defaultLocale = '#{default_locale}';
+          const defaultLocale = #{default_locale.to_json};
 
-          const defaultMessages = defineMessages(#{@defaults});
+          const defaultMessages = #{@defaults};
 
           export { defaultMessages, defaultLocale };
         JS

data/lib/react_on_rails/locales/to_js.rb

@@ -11,22 +11,13 @@ module ReactOnRails
         "js"
       end
 
-      def template_translations
-        <<~JS
-          export const translations = #{@translations};
-        JS
-      end
-
-      def template_default
-        <<~JS
-          import { defineMessages } from 'react-intl';
-
-          const defaultLocale = '#{default_locale}';
-
-          const defaultMessages = defineMessages(#{@defaults});
+      def generated_files_obsolete?
+        # obsolete? only calls this after all output files exist; if the file disappears, regenerate.
+        default_source = File.read(file("default"))
 
-          export { defaultMessages, defaultLocale };
-        JS
+        default_source.match?(/^\s*import\s+\{\s*defineMessages\s*\}\s+from\s+["']react-intl["'];?/)
+      rescue Errno::ENOENT
+        true
       end
     end
   end

data/lib/react_on_rails/pro_helper.rb

@@ -15,6 +15,8 @@ module ReactOnRails
                                                 "data-component-name" => render_options.react_component_name,
                                                 "data-trace" => (render_options.trace ? true : nil),
                                                 "data-dom-id" => render_options.dom_id,
+                                                "data-hydrate-on" =>
+                                                  hydrate_on_data_attribute_value(render_options),
                                                 "data-ssr-identifier-prefix" =>
                                                   (render_options.html_streaming? ? render_options.dom_id : nil),
                                                 "data-store-dependencies" =>
@@ -39,6 +41,12 @@ module ReactOnRails
       spec_tag.html_safe
     end
 
+    def hydrate_on_data_attribute_value(render_options)
+      return unless render_options.internal_option(:hydrate_on) || render_options.hydrate_on != :immediate
+
+      render_options.hydrate_on
+    end
+
     def generated_stylesheet_hrefs_json(render_options)
       return unless render_options.auto_load_bundle
 

data/lib/react_on_rails/react_component/render_options.rb

@@ -4,6 +4,23 @@ require "react_on_rails/utils"
 
 module ReactOnRails
   module ReactComponent
+    HYDRATE_ON_MODES = %i[immediate visible idle].freeze
+
+    def self.normalize_hydrate_on(value)
+      normalized_value = value.is_a?(String) ? value.to_sym : value
+      unless HYDRATE_ON_MODES.include?(normalized_value)
+        raise ArgumentError,
+              "Invalid hydrate_on option: #{value.inspect}. " \
+              "Supported OSS modes are :immediate, :visible, and :idle."
+      end
+
+      return normalized_value if normalized_value == :immediate || !ReactOnRails::Utils.react_on_rails_pro?
+
+      raise ArgumentError,
+            "hydrate_on: #{value.inspect} is only supported by the open-source React on Rails client renderer. " \
+            "React on Rails Pro does not support hydrate_on scheduling yet; use :immediate."
+    end
+
     class RenderOptions
       include Utils::Required
 
@@ -54,9 +71,10 @@ module ReactOnRails
       def initialize(react_component_name: required("react_component_name"), options: required("options"))
         @react_component_name = react_component_name.camelize
         @options = options
+        @hydrate_on = ReactComponent.normalize_hydrate_on(options.fetch(:hydrate_on, :immediate))
       end
 
-      attr_reader :react_component_name
+      attr_reader :react_component_name, :hydrate_on
 
       def throw_js_errors
         options.fetch(:throw_js_errors, false)

data/lib/react_on_rails/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ReactOnRails
-  VERSION = "17.0.0.rc.5"
+  VERSION = "17.0.0.rc.6"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: react_on_rails
 version: !ruby/object:Gem::Version
-  version: 17.0.0.rc.5
+  version: 17.0.0.rc.6
 platform: ruby
 authors:
 - Justin Gordon