react_on_rails 17.0.1 → 17.1.0.rc.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c0a69e6dd7950d3edc83c8ce77b7ad56419f243b3355878140e8fad6e1f56d54
-  data.tar.gz: 2262184ed159c5e4efa4402e863d695c86cded69ff395dea8c7096b9fca73701
+  metadata.gz: 7026d13c6ff6a7d80dcb8c566a11e8446036d052ec2418e47f2bcdaec6a2eed3
+  data.tar.gz: 0a1354cabb04d73d50281387151ab91c440b06955d038dd0c564cc08cc20e51e
 SHA512:
-  metadata.gz: abfc807dddaed6cc958329c40bece87518247237aea46f1f8fbbe7f5c7bfc7738658f80a2656de0755788cfaa861b1369ccda45c0de44fef225e37686cb6040a
-  data.tar.gz: 630f17042cc9b1df2ce8cdaebe33883eeee4baa21ab041de75590984a5710751c0e5d7c53eedea1580823efbe62850d23c2e79d58f8baa1263d1c2aa9f1b4e3b
+  metadata.gz: a40e5cc18caeef6e4879a46314aa86ea6c5b48128fbf60b2e4793b1d32748b334767b4f432c8ef6e1779fa21a07d53edf00253235ced9d641b5e3b43f74db4b8
+  data.tar.gz: e3af833f783b8096f457d1ecbd4e268a7e07b61f8b39f00f48de30c0c976ad5f75f3285bf534afc71d179c73af75b55c6d640a0bf82b0ff656cadfd08ab24775

data/Gemfile.development_dependencies

@@ -2,7 +2,7 @@
 
 eval_gemfile File.expand_path("../Gemfile.shared_dev_dependencies", __dir__)
 
-gem "shakapacker", "10.3.0"
+gem "shakapacker", "10.3.2"
 gem "bootsnap", require: false
 gem "rails", "~> 7.1.0"
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    react_on_rails (17.0.1)
+    react_on_rails (17.1.0.rc.1)
       addressable
       connection_pool
       execjs (~> 2.5)
@@ -117,7 +117,7 @@ GEM
     cgi (0.5.2)
     childprocess (5.0.0)
     coderay (1.1.3)
-    concurrent-ruby (1.3.7)
+    concurrent-ruby (1.3.8)
     connection_pool (3.0.2)
     crass (1.0.7)
     csv (3.3.5)
@@ -132,7 +132,7 @@ GEM
     drb (2.2.3)
     equivalent-xml (0.6.0)
       nokogiri (>= 1.4.3)
-    erb (6.0.4)
+    erb (6.0.7)
     erubi (1.13.1)
     execjs (2.9.1)
     ffi (1.16.3)
@@ -146,7 +146,7 @@ GEM
     i18n (1.15.2)
       concurrent-ruby (~> 1.0)
     interception (0.5)
-    io-console (0.8.2)
+    io-console (0.9.2)
     irb (1.18.0)
       pp (>= 0.6.0)
       prism (>= 1.3.0)
@@ -169,7 +169,7 @@ GEM
       rb-fsevent (~> 0.10, >= 0.10.3)
       rb-inotify (~> 0.9, >= 0.9.10)
     logger (1.7.0)
-    loofah (2.25.1)
+    loofah (2.25.2)
       crass (~> 1.0.2)
       nokogiri (>= 1.12.0)
     mail (2.9.0)
@@ -228,16 +228,16 @@ GEM
     pry-rescue (1.6.0)
       interception (>= 0.5)
       pry (>= 0.12.0)
-    psych (5.4.0)
+    psych (5.5.0)
       date
       stringio
     public_suffix (6.0.2)
     puma (6.6.1)
       nio4r (~> 2.0)
     racc (1.8.1)
-    rack (3.2.6)
-    rack-proxy (0.8.3)
-      rack
+    rack (3.2.7)
+    rack-proxy (1.0.1)
+      rack (>= 2.0, < 4)
     rack-session (2.1.2)
       base64 (>= 0.1.0)
       rack (>= 3.0.0)
@@ -263,8 +263,8 @@ GEM
       activesupport (>= 5.0.0)
       minitest
       nokogiri (>= 1.6)
-    rails-html-sanitizer (1.7.0)
-      loofah (~> 2.25)
+    rails-html-sanitizer (1.7.1)
+      loofah (~> 2.25, >= 2.25.2)
       nokogiri (>= 1.15.7, != 1.16.7, != 1.16.6, != 1.16.5, != 1.16.4, != 1.16.3, != 1.16.2, != 1.16.1, != 1.16.0.rc1, != 1.16.0)
     railties (7.1.6)
       actionpack (= 7.1.6)
@@ -288,7 +288,7 @@ GEM
       psych (>= 4.0.0)
       tsort
     regexp_parser (2.11.3)
-    reline (0.6.3)
+    reline (0.7.0)
       io-console (~> 0.5)
     rexml (3.4.4)
     rspec-core (3.13.0)
@@ -331,7 +331,7 @@ GEM
       rubyzip (>= 1.2.2, < 3.0)
       websocket (~> 1.0)
     semantic_range (3.1.1)
-    shakapacker (10.3.0)
+    shakapacker (10.3.2)
       activesupport (>= 5.2)
       package_json
       rack-proxy (>= 0.6.1)
@@ -402,7 +402,7 @@ GEM
     xpath (3.2.0)
       nokogiri (~> 1.8)
     yard (0.9.36)
-    zeitwerk (2.8.2)
+    zeitwerk (2.8.3)
 
 PLATFORMS
   arm64-darwin
@@ -443,7 +443,7 @@ DEPENDENCIES
   sass-rails (~> 6.0)
   sdoc
   selenium-webdriver (= 4.9.0)
-  shakapacker (= 10.3.0)
+  shakapacker (= 10.3.2)
   simplecov (~> 0.16.1)
   spring (~> 4.0)
   sprockets (~> 4.0)

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,164 @@
+# 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 React on Rails first so Bundler resolves a compatible Shakapacker version, then pin that resolved version when
+promoting Shakapacker to a direct dependency.
+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 react_on_rails --strict
+SHAKAPACKER_VERSION="$(bundle exec ruby -rreact_on_rails -e 'print ReactOnRails::PackerUtils.shakapacker_version')"
+bundle add shakapacker --version="${SHAKAPACKER_VERSION}" --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
@@ -988,7 +1033,13 @@ module ReactOnRails
         say "📝 Adding Shakapacker to Gemfile...", :yellow
         # Use with_unbundled_env to prevent inheriting BUNDLE_GEMFILE from parent process
         # See: https://github.com/shakacode/react_on_rails/issues/2287
-        success = Bundler.with_unbundled_env { system("bundle add shakapacker --strict") }
+        # Pin the version already resolved through react_on_rails. Without an explicit
+        # version, `bundle add --strict` can prefer an older globally installed gem and
+        # downgrade the target app's lockfile.
+        shakapacker_version = ReactOnRails::PackerUtils.shakapacker_version
+        success = Bundler.with_unbundled_env do
+          system("bundle", "add", "shakapacker", "--version", shakapacker_version, "--strict")
+        end
         return true if success
 
         handle_shakapacker_gemfile_error
@@ -1118,6 +1169,7 @@ module ReactOnRails
       end
 
       def handle_shakapacker_gemfile_error
+        shakapacker_version = ReactOnRails::PackerUtils.shakapacker_version
         error = <<~MSG.strip
           🚫 Failed to add Shakapacker to your Gemfile.
 
@@ -1127,7 +1179,7 @@ module ReactOnRails
           • Gemfile permissions
 
           Please try manually:
-              bundle add shakapacker --strict
+              bundle add shakapacker --version #{shakapacker_version} --strict
 
           #{recovery_working_tree_note}
           Then re-run: #{recovery_install_command}

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!