react_on_rails 17.0.1 → 17.1.0.rc.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c0a69e6dd7950d3edc83c8ce77b7ad56419f243b3355878140e8fad6e1f56d54
-  data.tar.gz: 2262184ed159c5e4efa4402e863d695c86cded69ff395dea8c7096b9fca73701
+  metadata.gz: 3c57ce4cf00568f0e471fb56202eda0a3483c1abdbcdd2ac75af3f7b0980fdcb
+  data.tar.gz: a5a7c6b5279f3274ece7bba232ad8d8367fab307532df3769fe222f4ad557b6b
 SHA512:
-  metadata.gz: abfc807dddaed6cc958329c40bece87518247237aea46f1f8fbbe7f5c7bfc7738658f80a2656de0755788cfaa861b1369ccda45c0de44fef225e37686cb6040a
-  data.tar.gz: 630f17042cc9b1df2ce8cdaebe33883eeee4baa21ab041de75590984a5710751c0e5d7c53eedea1580823efbe62850d23c2e79d58f8baa1263d1c2aa9f1b4e3b
+  metadata.gz: 7f42ff98daf96f7f8e5a32a7d790790b1a61e3f5fdcbe18d32962b43ea77863a2061b4b14b58a59f4a6b8e9b5ee555ce18353dcccdf591776ba9480827237e14
+  data.tar.gz: 79891caa83aea2acaa89f37a5351b22a6ac8ac30c80f458d9ad4c4bc1bb2df461e2fa212297d03ad7f06beef37b29cd7ec3dd723c477c5cbb2192eeb08a4985d

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    react_on_rails (17.0.1)
+    react_on_rails (17.1.0.rc.0)
       addressable
       connection_pool
       execjs (~> 2.5)

data/docs/agent/README.md

@@ -0,0 +1,26 @@
+# React on Rails bundled agent reference
+
+These guides and skills ship with the installed React on Rails version. Read them before relying on
+training data or hosted documentation, which may describe a different release.
+
+| Workflow                            | Skill                                                              | Guide                             |
+| ----------------------------------- | ------------------------------------------------------------------ | --------------------------------- |
+| Install or upgrade                  | [`install-and-upgrade`](../../skills/install-and-upgrade/SKILL.md) | [Guide](./install-and-upgrade.md) |
+| Adopt React Server Components (Pro) | [`rsc-adoption`](../../skills/rsc-adoption/SKILL.md)               | [Guide](./rsc-adoption.md)        |
+| Debug streaming SSR (Pro)           | [`streaming-debug`](../../skills/streaming-debug/SKILL.md)         | [Guide](./streaming-debug.md)     |
+| Iterate with the doctor             | [`doctor-fix-loop`](../../skills/doctor-fix-loop/SKILL.md)         | [Guide](./doctor-fix-loop.md)     |
+
+The gem and npm package contain byte-identical copies. Use the installed gem directory as the
+canonical, reliable lookup:
+
+```bash
+bundle show react_on_rails
+```
+
+Read `docs/agent/README.md` and the `skills/` paths from the returned directory. An optional
+direct-dependency path is `node_modules/react-on-rails/`, but use it only when that directory
+exists. Do not assume it exists: Pro installations may omit the direct base npm dependency, and
+pnpm may isolate a transitive copy.
+
+For broader explanation after reading the installed references, use the hosted documentation:
+https://reactonrails.com/docs/.

data/docs/agent/doctor-fix-loop.md

@@ -0,0 +1,25 @@
+# Doctor-driven fix loop
+
+Use the stable JSON form for agent and CI workflows:
+
+```bash
+bin/rails react_on_rails:doctor FORMAT=json
+```
+
+Standard output is one JSON document. The top-level `status`, `checks`, and `summary` describe the
+run. Every check exposes a stable `id`, `status`, `severity`, `message`, `fix_command`, `docs_url`,
+`remediation`, and `details` contract.
+
+For every non-passing check, in array order:
+
+1. Record `id` and `severity`.
+2. Inspect `message`, `remediation.files`, and the current app state.
+3. Use `remediation.prompt` and `remediation.expected_end_state` as bounded guidance.
+4. Review the smallest corrective diff.
+5. Rerun the JSON doctor and confirm the check passes without creating another failure.
+
+Exit code `1` means at least one error remains. Warnings keep exit code `0`, so read `status` or
+`summary.warn` when warning-free output matters. A `null` `fix_command` is expected; never infer an
+unsafe global repair command from the check ID.
+
+Secondary reference: https://reactonrails.com/docs/api-reference/doctor.

data/docs/agent/install-and-upgrade.md

@@ -0,0 +1,162 @@
+# Install and upgrade
+
+Use this guide for an existing Rails app. Keep app-specific choices and custom configuration intact.
+
+## Preflight
+
+- Record the Rails, Ruby, Node, Shakapacker, React on Rails gem, npm package, and package-manager state.
+- Identify both Ruby and JavaScript lockfiles and start from a reviewable working tree.
+- Keep the gem and npm package on the same React on Rails release. A Pro app must also update its Pro
+  gem and JavaScript packages together.
+
+## Install
+
+Add Shakapacker and React on Rails through Bundler.
+Choose exactly one stack flag before running the install generator.
+Use `--standard-only` for OSS, `--pro` for Pro, or `--rsc` for Pro with RSC.
+Do not rely on an interactive TTY prompt; replace `<STACK_FLAG>` explicitly in every command.
+Choose the language explicitly too: replace `<LANGUAGE_CHOICE>` with `--typescript` for TypeScript,
+or remove that placeholder for JavaScript. TypeScript is optional; omitting its flag preserves JavaScript.
+
+```bash
+bundle add shakapacker --strict
+bundle add react_on_rails --strict
+```
+
+For `--pro` or `--rsc`, React on Rails Pro is free for evaluation and non-production use;
+production use requires a subscription. Review [Pro licensing and setup](https://reactonrails.com/docs/pro/upgrading-to-pro/)
+before proceeding.
+
+Skip this Pro-gem preparation for `--standard-only`.
+For `--pro` or `--rsc` only, derive the exact installed base-gem version before adding the Pro gem:
+
+```bash
+ROR_GEM_VERSION="$(bundle exec ruby -rreact_on_rails/version -e 'print ReactOnRails::VERSION')"
+bundle add react_on_rails_pro --version="${ROR_GEM_VERSION}" --strict
+```
+
+If that exact version is an unpublished prerelease, require a matching local/path `react_on_rails_pro` gem
+and use the same exact version instead of the registry command:
+
+```bash
+bundle add react_on_rails_pro --path="<path-to-matching-react_on_rails_pro>" --version="${ROR_GEM_VERSION}" --strict
+```
+
+Never fall back silently to a stable Pro gem.
+For `--pro` or `--rsc` only, after either Pro source command succeeds, remove the direct base-gem declaration:
+
+```bash
+bundle remove react_on_rails
+```
+
+This cleanup removes only the direct `react_on_rails` declaration; `react_on_rails_pro` retains the matching base gem
+transitively. Do not run this cleanup for `--standard-only`.
+
+After the conditional Pro preparation, run the generator with the explicit stack flag:
+
+```bash
+bundle exec rails generate react_on_rails:install <LANGUAGE_CHOICE> <STACK_FLAG>
+```
+
+Use the app's declared JavaScript package manager if the generator prints a manual install command.
+Review the generated initializer, Shakapacker configuration, scripts, routes, and sample files.
+
+## Upgrade
+
+1. Record the installed Ruby gem version as `CURRENT_VERSION`:
+
+   ```bash
+   CURRENT_VERSION="$(bundle exec ruby -rreact_on_rails/version -e 'puts ReactOnRails::VERSION')"
+   printf '%s\n' "$CURRENT_VERSION"
+   ```
+
+2. Choose and verify explicit Ruby and npm target versions before editing dependency pins. Record
+   the Ruby/tag form as `GEM_TARGET_VERSION` and the npm semver form as `NPM_TARGET_VERSION`.
+   Ruby prereleases use dot notation (for example, `17.0.0.rc.6`); npm prereleases use hyphen notation
+   (for example, `17.0.0-rc.6`). Choose both explicitly rather than deriving either from
+   `CURRENT_VERSION` or from the other target.
+
+   ```bash
+   GEM_TARGET_VERSION="<Ruby/tag version you selected>"
+   NPM_TARGET_VERSION="<npm semver version you selected>"
+   git ls-remote --exit-code --tags https://github.com/shakacode/react_on_rails.git \
+     "refs/tags/v${GEM_TARGET_VERSION}"
+   ```
+
+3. Read the changelog and upgrade guidance from the immutable repository tag `v<GEM_TARGET_VERSION>`:
+   `https://github.com/shakacode/react_on_rails/tree/v<GEM_TARGET_VERSION>`. Compare the complete
+   `CURRENT_VERSION..GEM_TARGET_VERSION` release range before changing dependencies:
+   `https://github.com/shakacode/react_on_rails/compare/v<CURRENT_VERSION>...v<GEM_TARGET_VERSION>`.
+
+## JavaScript target matrix
+
+Use exactly the row matching the detected stack. Verify every relevant package version before
+pinning it; checking only the base package is insufficient. Use the app's declared package manager's
+registry-inspection command for every exact package spec below. Do not assume pnpm, npm, Yarn, or Bun
+is available merely because another package manager is installed.
+
+- **OSS (`--standard-only`)**: pin and verify `react-on-rails@${NPM_TARGET_VERSION}`.
+
+- **Pro (all renderers)**: pin and verify `react-on-rails-pro@${NPM_TARGET_VERSION}`. Also pin and verify
+  `react-on-rails-pro-node-renderer@${NPM_TARGET_VERSION}` only when the app uses the standalone NodeRenderer.
+  Do not add a direct `react-on-rails` dependency to Pro or RSC apps.
+
+- **RSC (`--rsc`)**: follow the Pro rule, including its conditional standalone NodeRenderer package
+  and prohibition on a direct base dependency. Select `RSC_TARGET_VERSION` independently from the
+  target release guidance or the target tag's
+  `ReactOnRails::Generators::JsDependencyManager::RSC_PACKAGE_VERSION_PIN`:
+  `https://github.com/shakacode/react_on_rails/blob/v<GEM_TARGET_VERSION>/react_on_rails/lib/generators/react_on_rails/js_dependency_manager.rb`.
+  Never derive `RSC_TARGET_VERSION` from `NPM_TARGET_VERSION`. Pin and verify the exact
+  `react-on-rails-rsc@${RSC_TARGET_VERSION}` release.
+
+  ```bash
+  RSC_TARGET_VERSION="<exact RSC pin from target guidance>"
+  ```
+
+4. Pin Ruby gems with `GEM_TARGET_VERSION` and regenerate the Bundler lockfile.
+   Apply exactly the matching JavaScript matrix row with the app's declared package manager, pin each
+   package to the verified exact version, and regenerate the JavaScript lockfile.
+5. Detect the app's existing stack and current generator choices from its dependencies and
+   configuration. Use the one preserving mapping that matches the existing stack:
+   - Use `--standard-only` for an existing OSS stack.
+   - Use `--pro` only for an existing Pro + NodeRenderer stack.
+   - Use `--rsc` for an existing RSC stack.
+
+   Pro + ExecJS has no preserving install-generator flag.
+   For that stack, skip both generator preview and apply steps; upgrade dependencies and configuration manually.
+   Preserve the ExecJS renderer setup. For the three preserving mappings, preserve the current stack.
+   Preserve every other current generator choice, such as TypeScript, Redux, or generated
+   test-framework choices.
+
+6. For a stack with a preserving mapping, first rerun the generator as a preview, substituting the
+   selected stack flag and the app's other current choices:
+
+   ```bash
+   bundle exec rails generate react_on_rails:install --pretend <STACK_FLAG> <OTHER_CURRENT_CHOICES>
+   ```
+
+   `--pretend` omits dependency installation and script effects; it is not a complete mutation audit.
+   Review the complete preview without overwriting app-owned configuration. Never prescribe or run a
+   bare, non-TTY generator rerun.
+
+7. Only for a stack with a preserving mapping, and only after reviewing and accepting the preview,
+   apply the same choices without `--pretend` in a clean branch or worktree:
+
+   ```bash
+   bundle exec rails generate react_on_rails:install <STACK_FLAG> <OTHER_CURRENT_CHOICES>
+   ```
+
+   Before accepting any generated change, audit `package.json` and the JavaScript lockfile against
+   their pre-run state. The apply step installs the generator's current dependency defaults even
+   though `--pretend` skipped them; preserve intentional app pins and reject unintended upgrades.
+
+8. Run the doctor loop, compile assets, and run focused application tests.
+
+```bash
+bin/rails react_on_rails:doctor FORMAT=json
+bundle exec rails shakapacker:compile
+```
+
+Secondary references:
+https://reactonrails.com/docs/getting-started/existing-rails-app and
+https://reactonrails.com/docs/upgrading/upgrading-react-on-rails.

data/docs/agent/rsc-adoption.md

@@ -0,0 +1,31 @@
+# React Server Components adoption (Pro)
+
+React Server Components require React on Rails Pro. Use the generator and installed package contracts;
+do not reconstruct the RSC build or renderer protocol from memory.
+
+## Adoption sequence
+
+1. Confirm the Pro gem/npm packages, Node renderer, React, React DOM, and RSC package are compatible.
+2. Preserve the app's language when running the generator: use
+   `bundle exec rails generate react_on_rails:rsc --typescript` for a TypeScript app and
+   `bundle exec rails generate react_on_rails:rsc` for a JavaScript app. Review the generated client,
+   server, and RSC bundle configuration.
+3. Move one leaf at a time. The `'use client'` directive marks the server-to-client boundary, not
+   every module that will execute on the client. Modules imported below that boundary remain client code
+   even when they lack the directive; place it only where a subtree needs browser APIs, state, effects,
+   or event handlers.
+4. Keep `.client.` and `.server.` suffixes conceptually separate: they select bundle placement and do
+   not classify React Server Components.
+5. Keep Rails-owned data and security decisions in Rails. Supply data through props or async props;
+   server components do not gain in-process access to Rails models, sessions, or cookies.
+6. Install the app safety guardrails and review the generated skill and advisory hook:
+
+```bash
+bundle exec rake react_on_rails:install_rsc_agent_guardrails
+bin/rails react_on_rails:doctor FORMAT=json
+```
+
+Before completion, protect any RSC payload route, keep the Node renderer private, avoid sensitive
+logged props or URLs, build all three bundles, and exercise navigation and hydration in a browser.
+
+Secondary reference: https://reactonrails.com/docs/pro/react-server-components.

data/docs/agent/streaming-debug.md

@@ -0,0 +1,57 @@
+# Streaming SSR debugging (Pro)
+
+Streaming requires React on Rails Pro and the Node renderer. First determine whether the selected
+helper is progressive or intentionally buffered.
+
+## Debug in boundary order
+
+1. Run `bin/rails react_on_rails:doctor FORMAT=json` and resolve configuration or dependency errors.
+2. Identify the exact helper before applying streaming prerequisites.
+
+## Progressive helpers
+
+For `stream_react_component`, `cached_stream_react_component`, and
+`stream_react_component_with_async_props`:
+
+1. Confirm the controller includes `ReactOnRailsPro::Stream`, the action enters the view through
+   `stream_view_containing_react_components` instead of ordinary `render`, and the Node renderer
+   is reachable.
+2. When Suspense content should reveal progressively, confirm the boundary's child actually suspends.
+3. For `stream_react_component_with_async_props` only, confirm
+   `ReactOnRailsPro.configuration.enable_rsc_support` is enabled by setting
+   `config.enable_rsc_support = true` in the Pro initializer.
+   This is not a prerequisite for `stream_react_component` or `cached_stream_react_component`.
+4. For async props, start slow work inside the streaming block, emit only JSON-serializable values,
+   and emit or reject every prop the renderer requests.
+
+## Buffered helpers
+
+For `buffered_stream_react_component`, `cached_buffered_stream_react_component`, and
+`cached_static_rsc_component`:
+
+1. Confirm the Node renderer is reachable and inspect the complete buffered result.
+2. These helpers do not require the streaming controller wrapper: they do not require
+   `ReactOnRailsPro::Stream`, `stream_view_containing_react_components`, or a suspending boundary.
+3. For `cached_static_rsc_component`, set `config.enable_rsc_support = true`; disabling RSC support
+   omits the RSC payload generation that gives this helper its static-RSC behavior.
+   This setting is not a prerequisite for `buffered_stream_react_component` or
+   `cached_buffered_stream_react_component`.
+4. Expect the browser to receive the page only after the renderer has produced the complete result;
+   early shell flush and progressive Suspense reveal are not buffered-helper behavior.
+
+## Debug either path
+
+Probe the origin with buffering disabled in the client, then compare the same route through each
+reverse proxy or CDN. Inspect response headers, chunk arrival, compression, Rails logs, Node
+renderer logs, and browser timing marks.
+
+A useful transport probe is:
+
+```bash
+curl --no-buffer --dump-header - https://your-app.example/streaming-route
+```
+
+If the origin streams but the public route buffers, fix the proxy/CDN boundary. If neither streams,
+reduce to one Suspense boundary and one known-slow value before changing application architecture.
+
+Secondary reference: https://reactonrails.com/docs/pro/streaming-ssr.

data/lib/generators/react_on_rails/base_generator.rb

@@ -251,9 +251,7 @@ module ReactOnRails
         ensure_new_app_root_route_initialized
 
         base_path = "base/base/"
-        base_files = %w[Procfile.dev
-                        Procfile.dev-static-assets
-                        Procfile.dev-prod-assets
+        base_files = %w[Procfile.dev-prod-assets
                         .dev-services.yml.example
                         .env.example
                         bin/shakapacker-precompile-hook]
@@ -262,7 +260,9 @@ module ReactOnRails
         # Exception: Redux still needs the HelloWorld controller even with RSC
         base_files << "app/controllers/hello_world_controller.rb" unless use_rsc? && !options.redux?
         base_files << "app/controllers/home_controller.rb" if generate_new_app_home_page?
-        base_templates = %w[config/initializers/react_on_rails.rb]
+        base_templates = %w[Procfile.dev
+                            Procfile.dev-static-assets
+                            config/initializers/react_on_rails.rb]
         base_files.each { |file| copy_file("#{base_path}#{file}", file) }
         copy_react_on_rails_default_layout(base_path)
         warn_existing_hello_world_tailwind_layout

data/lib/generators/react_on_rails/generator_helper.rb

@@ -85,7 +85,7 @@ module GeneratorHelper
   end
 
   def add_documentation_reference(message, source)
-    "#{message} \n#{source}"
+    "#{message}\n#{source}"
   end
 
   def print_generator_messages
@@ -492,6 +492,17 @@ module GeneratorHelper
     nil
   end
 
+  # Prefer Shakapacker's optional watcher binstub when the application has an executable copy. Older
+  # supported Shakapacker installations can still run watch mode through the required
+  # bin/shakapacker binstub, so React on Rails does not need to vendor a fallback watcher.
+  def shakapacker_watch_command
+    watch_binstub = File.join(destination_root, "bin/shakapacker-watch")
+    watch_binstub_available = File.file?(watch_binstub) && File.executable?(watch_binstub)
+    executable = watch_binstub_available ? "bin/shakapacker-watch" : "bin/shakapacker"
+
+    "#{executable} --watch"
+  end
+
   # Check if Shakapacker 9.0 or higher is available
   # Returns true if Shakapacker >= 9.0, false otherwise
   #

data/lib/generators/react_on_rails/install_generator.rb

@@ -86,16 +86,22 @@ module ReactOnRails
                    desc: "Write AI-agent guidance files (AGENTS.md + editor pointers). Default: true"
 
       # --pro
+      # No static default: prompt suppression needs to distinguish an omitted flag from --no-pro.
       class_option :pro,
                    type: :boolean,
-                   default: false,
-                   desc: "Install React on Rails Pro with Node Renderer. Default: false"
+                   desc: "Install React on Rails Pro with Node Renderer"
 
       # --rsc
+      # No static default: prompt suppression needs to distinguish an omitted flag from --no-rsc.
       class_option :rsc,
+                   type: :boolean,
+                   desc: "Install React Server Components support (includes Pro)"
+
+      # --standard-only
+      class_option :standard_only,
                    type: :boolean,
                    default: false,
-                   desc: "Install React Server Components support (includes Pro). Default: false"
+                   desc: "Install only the open-source package; cannot be combined with --pro or --rsc"
 
       # Hidden option: allows tests (and advanced users) to signal that Shakapacker
       # was just installed, triggering force-overwrite of shakapacker.yml with RoR's template.
@@ -196,6 +202,7 @@ module ReactOnRails
         # This is inherited by all invoked generators and persists through Rails initialization
         # See lib/react_on_rails/engine.rb for the validation skip logic
         ENV["REACT_ON_RAILS_SKIP_VALIDATION"] = "true"
+        prompt_for_pro_features_if_applicable
 
         if installation_prerequisites_met? || options.ignore_warnings?
           invoke_generators
@@ -230,6 +237,40 @@ module ReactOnRails
 
       private
 
+      def use_pro?
+        return @interactive_pro_selection if defined?(@interactive_pro_selection)
+
+        !!super
+      end
+
+      def prompt_for_pro_features_if_applicable
+        validate_product_stack_choice!
+        return if options.new_app? || explicit_product_stack_choice? || !interactive_install_session?
+
+        say "React on Rails Pro is free for evaluation; production use requires a subscription."
+        say "Learn more: https://reactonrails.com/docs/pro/upgrading-to-pro/"
+        answer = ask(
+          "Enable React on Rails Pro features (Node Renderer and streaming SSR; RSC available separately)? [Y/n]",
+          :cyan
+        )
+        normalized_answer = answer.to_s.strip
+        @interactive_pro_selection = normalized_answer.empty? || normalized_answer.match?(/\A(?:y|yes)\z/i)
+      end
+
+      def explicit_product_stack_choice?
+        options.key?(:pro) || options.key?(:rsc) || options.standard_only?
+      end
+
+      def interactive_install_session?
+        !ReactOnRails::GitUtils.truthy_env?(ENV.fetch("CI", nil)) && $stdin.tty? && $stdout.tty?
+      end
+
+      def validate_product_stack_choice!
+        return unless options.standard_only? && (options.pro? || options.rsc?)
+
+        raise Thor::Error, "--standard-only cannot be combined with --pro or --rsc"
+      end
+
       # Fresh-install context: default to Rspack (when Shakapacker supports it) unless the
       # app already declares a bundler. See GeneratorHelper#fresh_install_rspack_default.
       # NOTE: BaseGenerator#rspack_bundler_default is an intentional twin of this override
@@ -866,8 +907,12 @@ module ReactOnRails
       end
 
       def product_stack_install_flag
-        return "--rsc" if options.rsc?
-        return "--pro" if options.pro?
+        return "--rsc" if use_rsc?
+        return "--pro" if use_pro?
+        return "--standard-only" if options.standard_only?
+        return "--no-rsc" if options.key?(:rsc)
+        return "--no-pro" if options.key?(:pro)
+        return "--standard-only" if defined?(@interactive_pro_selection)
 
         nil
       end

data/lib/generators/react_on_rails/js_dependency_manager.rb

@@ -177,7 +177,7 @@ module ReactOnRails
       end
 
       def add_js_dependencies
-        using_pro = respond_to?(:use_pro?) && use_pro?
+        using_pro = respond_to?(:use_pro?, true) && use_pro?
         using_rsc = respond_to?(:use_rsc?) && use_rsc?
         # Pro package includes react-on-rails, so skip base package when using Pro
         add_react_on_rails_package unless using_pro

data/lib/generators/react_on_rails/pro_generator.rb

@@ -40,9 +40,11 @@ module ReactOnRails
           )
 
           setup_pro
-          add_pro_npm_dependencies
-          update_imports_to_pro_package unless options[:invoked_by_install]
-          print_success_message unless options[:invoked_by_install]
+          unless options[:invoked_by_install]
+            add_pro_npm_dependencies
+            update_imports_to_pro_package
+            print_success_message
+          end
         else
           GeneratorMessages.add_error(<<~MSG.strip)
             🚫 React on Rails Pro generator prerequisites not met!

data/lib/generators/react_on_rails/pro_setup.rb

@@ -33,6 +33,38 @@ module ReactOnRails
       AUTO_INSTALL_TIMEOUT = 120
       TERMINATION_GRACE_PERIOD = 5
 
+      # Loader helpers emitted by
+      # templates/base/base/config/webpack/serverWebpackConfig.js.tt.
+      #
+      # Keep both blocks byte-identical to that template: a fresh `--pro` install renders
+      # the template while a standalone Pro upgrade patches an existing base config, and
+      # the two must produce the same source text so drift is detectable (issue #4786).
+      GET_LOADER_PATH_JS = <<~JS
+        // Normalizes an entry of a webpack/rspack `rule.use` array to its loader path.
+        // Entries may be a bare string, a `{ loader, options }` object, or null.
+        function getLoaderPath(item) {
+          if (typeof item === 'string') return item;
+          if (item && typeof item.loader === 'string') return item.loader;
+          return '';
+        }
+      JS
+
+      EXTRACT_LOADER_JS = <<~JS
+        function extractLoader(rule, loaderName) {
+          if (!Array.isArray(rule.use)) return null;
+          return rule.use.find((item) => getLoaderPath(item).includes(loaderName));
+        }
+      JS
+
+      BUNDLER_REQUIRE_PATTERN =
+        %r{(const bundler = config\.assets_bundler.*\n.*require\('@rspack/core'\).*\n.*: require\('webpack'\);)}
+
+      # Matches any declaration of the getLoaderPath symbol, however it is written. The
+      # emitted extractLoader calls getLoaderPath, so we must never add a second
+      # declaration: `function` next to an existing `const` is a SyntaxError, not a
+      # silent shadow, and the generated config would fail to parse in Node.
+      GET_LOADER_PATH_DECLARATION = /(?:function\s+getLoaderPath\s*\(|(?:const|let|var)\s+getLoaderPath\s*=)/
+
       # Main entry point for Pro setup.
       # Orchestrates creation of all Pro-related files and configuration.
       #
@@ -488,25 +520,25 @@ module ReactOnRails
         # Skip if extractLoader already exists
         return if content.include?("function extractLoader")
 
-        extract_loader_code = <<~JS.chomp
-
-
-          function extractLoader(rule, loaderName) {
-            if (!Array.isArray(rule.use)) return null;
-            return rule.use.find((item) => {
-              if (!item) return false;
-              const testValue = typeof item === 'string' ? item : (typeof item.loader === 'string' ? item.loader : '');
-              return testValue.includes(loaderName);
-            });
-          }
-        JS
-
-        # Insert after bundler require line
-        gsub_file(
-          webpack_config,
-          %r{(const bundler = config\.assets_bundler.*\n.*require\('@rspack/core'\).*\n.*: require\('webpack'\);)},
-          "\\1#{extract_loader_code}"
-        )
+        if content.include?(GET_LOADER_PATH_JS)
+          # Config rendered by the current base template: append extractLoader directly after
+          # the shared getLoaderPath helper so the result matches the template's Pro output.
+          gsub_file(webpack_config, GET_LOADER_PATH_JS, "#{GET_LOADER_PATH_JS}\n#{EXTRACT_LOADER_JS}")
+        elsif content.match?(GET_LOADER_PATH_DECLARATION)
+          # The app already declares getLoaderPath but has customized it (reformatted, recommented,
+          # or rewritten as an arrow function). Reuse whatever is there and emit extractLoader only.
+          # Emitting our own copy would redeclare the identifier, which is a SyntaxError next to an
+          # existing const/let and silent shadowing next to another function declaration.
+          gsub_file(webpack_config, BUNDLER_REQUIRE_PATTERN, "\\1\n\n#{EXTRACT_LOADER_JS}".chomp)
+        else
+          # Base config generated before getLoaderPath existed: emit both helpers after the
+          # bundler require so extractLoader's dependency is present.
+          gsub_file(
+            webpack_config,
+            BUNDLER_REQUIRE_PATTERN,
+            "\\1\n\n#{GET_LOADER_PATH_JS}\n#{EXTRACT_LOADER_JS}".chomp
+          )
+        end
       end
 
       def add_babel_ssr_caller_to_server_config(webpack_config, content)

data/lib/generators/react_on_rails/rsc_generator.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "rails/generators"
+require "react_on_rails/agent_guardrails"
 require_relative "generator_helper"
 require_relative "generator_messages"
 require_relative "js_dependency_manager"
@@ -52,7 +53,8 @@ module ReactOnRails
         if options[:invoked_by_install] || prerequisites_met?
           warn_about_react_version_for_rsc(force: true)
           setup_rsc
-          add_rsc_npm_dependencies
+          add_rsc_npm_dependencies unless options[:invoked_by_install]
+          install_agent_guardrails
           print_success_message unless options[:invoked_by_install]
         else
           GeneratorMessages.add_error(<<~MSG.strip)
@@ -120,6 +122,21 @@ module ReactOnRails
         say "✅ RSC npm dependencies added", :green
       end
 
+      def install_agent_guardrails
+        if options[:pretend]
+          say_status :pretend, ".claude/ (RSC agent guardrails)", :yellow
+          return
+        end
+
+        say "🛡️  Installing RSC agent guardrails (rsc-app-safety skill + advisory hook)...", :yellow
+        ReactOnRails::AgentGuardrails.install(destination_root, skip_existing: options[:skip]).each do |action|
+          say "   #{action}"
+        end
+        say "✅ RSC agent guardrails installed", :green
+      rescue ReactOnRails::AgentGuardrails::Error, SystemCallError => e
+        say "⚠️  RSC agent guardrail installation incomplete: #{e.message}", :yellow
+      end
+
       def print_success_message
         GeneratorMessages.add_info(<<~MSG)
           Next steps: