Hide legacy Redux install generator path

Author: justin808

CHANGELOG.md

@@ -41,6 +41,8 @@ After a release, run `/update-changelog` in Claude Code to analyze commits, writ
 
 #### Changed
 
+- **Redux is now hidden from the V17 install generator path**: The `react_on_rails:install --redux` option is no longer shown in install generator help or usage text, and recovery guidance no longer recommends `--redux` for new installs. The hidden legacy path and direct `react_on_rails:react_with_redux` generator now warn that Redux scaffolding is legacy while keeping runtime Redux APIs available. Closes [Issue 4272](https://github.com/shakacode/react_on_rails/issues/4272) and [Issue 4273](https://github.com/shakacode/react_on_rails/issues/4273). [PR 4277](https://github.com/shakacode/react_on_rails/pull/4277) by [justin808](https://github.com/justin808).
+
 - **`create-react-on-rails-app` now defaults to Pro for React 19.2 support**: Running
   `npx create-react-on-rails-app my-app` no longer asks setup questions and generates the recommended
   React on Rails Pro scaffold by default. Automation note: non-TTY environments, including CI and piped

react_on_rails/lib/generators/USAGE

@@ -2,12 +2,6 @@ Description:
 
 The react_on_rails:install generator integrates a React frontend, including SSR, with Rails.
 
-* Redux (Optional)
-
-    Passing the --redux generator option causes the generated Hello World example
-    to integrate the Redux state container framework. The necessary node modules
-    will be automatically included for you.
-
 * Tailwind CSS v4 (Optional)
 
     Passing the --tailwind generator option installs Tailwind CSS v4, configures

react_on_rails/lib/generators/react_on_rails/base_generator.rb

@@ -17,12 +17,13 @@ class BaseGenerator < Rails::Generators::Base
       Rails::Generators.hide_namespace(namespace)
       source_root(File.expand_path("templates", __dir__))
 
-      # --redux
+      # Internal hidden legacy Redux plumbing for install_generator.
       class_option :redux,
                    type: :boolean,
                    default: false,
-                   desc: "Install Redux package and Redux version of Hello World Example",
-                   aliases: "-R"
+                   desc: "Internal legacy Redux scaffolding flag",
+                   aliases: "-R",
+                   hide: true
 
       # --rspack / --no-rspack (Rspack is the default on fresh installs; --no-rspack selects Webpack)
       # IMPORTANT: do NOT add a `default:` here. The absence of a default is load-bearing — Thor

react_on_rails/lib/generators/react_on_rails/install_generator.rb

@@ -32,12 +32,13 @@ class InstallGenerator < Rails::Generators::Base
       # fetch USAGE file for details generator description
       source_root(File.expand_path(__dir__))
 
-      # --redux
+      # Hidden legacy --redux escape hatch for existing scripted installs.
       class_option :redux,
                    type: :boolean,
                    default: false,
-                   desc: "Install Redux package and Redux version of Hello World Example. Default: false",
-                   aliases: "-R"
+                   desc: "Deprecated legacy Redux install path; use react_on_rails:react_with_redux directly.",
+                   aliases: "-R",
+                   hide: true
 
       # --typescript
       class_option :typescript,
@@ -195,6 +196,7 @@ def run_generators
         # 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"
+        add_legacy_redux_install_warning
 
         if installation_prerequisites_met? || options.ignore_warnings?
           invoke_generators
@@ -252,9 +254,9 @@ def invoke_generators
         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
-        # - Without --rsc: Normal behavior (HelloWorld or HelloWorldApp based on --redux)
+        # - --rsc without hidden legacy Redux: Skip HelloWorld; setup_rsc generates HelloServer.
+        # - Hidden legacy --redux: Generate HelloWorldApp as a one-major escape hatch.
+        # - Without --rsc: Generate the default HelloWorld example unless the legacy flag is present.
         if options.redux?
           invoke "react_on_rails:react_with_redux", [], { typescript: options.typescript?,
                                                           tailwind: use_tailwind?,
@@ -781,6 +783,33 @@ def shakapacker_setup_incomplete?
         @shakapacker_setup_incomplete == true
       end
 
+      def add_legacy_redux_install_warning
+        return unless options.redux?
+
+        legacy_guidance, legacy_command =
+          if use_tailwind?
+            [
+              "Existing apps that need Redux with Tailwind should keep using the hidden install path:",
+              "bundle exec rails generate react_on_rails:install --redux --tailwind"
+            ]
+          else
+            [
+              "Existing apps that need the legacy Redux scaffold can run:",
+              "bundle exec rails generate react_on_rails:react_with_redux"
+            ]
+          end
+
+        GeneratorMessages.add_warning(<<~MSG.strip)
+          The install --redux option is a hidden legacy Redux generator path and is not recommended
+          for new React on Rails apps.
+          Use the default install generator for new apps. #{legacy_guidance}
+
+              #{legacy_command}
+
+          Runtime Redux APIs such as redux_store remain supported.
+        MSG
+      end
+
       def recovery_install_command
         flags = []
         flags << "--redux" if options.redux?

react_on_rails/lib/generators/react_on_rails/react_with_redux_generator.rb

@@ -13,6 +13,12 @@ class ReactWithReduxGenerator < Rails::Generators::Base
 
       Rails::Generators.hide_namespace(namespace)
       source_root(File.expand_path("templates", __dir__))
+      LEGACY_REDUX_GENERATOR_WARNING = <<~MSG.strip
+        The react_on_rails:react_with_redux generator is a hidden legacy Redux generator path and is not
+        recommended for new React on Rails apps.
+        New apps should use the default React on Rails installer without Redux. Runtime Redux APIs such as
+        redux_store remain supported.
+      MSG
 
       class_option :typescript,
                    type: :boolean,
@@ -131,13 +137,14 @@ def add_redux_npm_dependencies
       def add_redux_specific_messages
         return if options.invoked_by_install?
 
-        # Append Redux-specific post-install instructions
+        GeneratorMessages.add_warning(LEGACY_REDUX_GENERATOR_WARNING)
         GeneratorMessages.add_info(
           GeneratorMessages.helpful_message_after_installation(component_name: "HelloWorldApp", route: "hello_world",
                                                                pro: Gem.loaded_specs.key?("react_on_rails_pro"),
                                                                tailwind: use_tailwind?,
                                                                app_root: destination_root)
         )
+        print_generator_messages
       end
 
       private
@@ -152,9 +159,13 @@ def unsupported_standalone_tailwind?
           Tailwind setup requires the base React on Rails installer so it can create the
           react_on_rails_tailwind pack, stylesheet, dependencies, and webpack/Rspack config.
 
-          Use the install generator for Redux + Tailwind setup:
+          Use the hidden legacy installer path if you intentionally need the Redux scaffold with Tailwind:
 
-            rails generate react_on_rails:install --redux --tailwind
+            bundle exec rails generate react_on_rails:install --redux --tailwind
+
+          For new apps, run the default installer without Redux:
+
+            bundle exec rails generate react_on_rails:install --tailwind
         MSG
         true
       end

react_on_rails/spec/react_on_rails/generators/install_generator_spec.rb

@@ -349,6 +349,25 @@ def repo_pinned_pnpm_version
     end
   end
 
+  describe "Redux generator policy" do
+    it "hides the install --redux option from public help and usage text" do
+      redux_option = described_class.class_options.fetch(:redux)
+
+      expect(redux_option.hide).to be(true)
+
+      usage_text = File.read(File.expand_path("../../../lib/generators/USAGE", __dir__))
+      expect(usage_text).not_to include("--redux")
+      expect(usage_text).not_to include("Redux (Optional)")
+    end
+
+    it "marks the base generator Redux option as internal legacy plumbing" do
+      redux_option = ReactOnRails::Generators::BaseGenerator.class_options.fetch(:redux)
+
+      expect(redux_option.hide).to be(true)
+      expect(redux_option.description).to include("legacy")
+    end
+  end
+
   describe "manual generator fixtures" do
     it "keep CI workflow generation inside the generator spec destination" do
       prepare_destination
@@ -4485,6 +4504,27 @@ class ActiveSupport::TestCase
       expect(output_text).to include("Re-run: rails generate react_on_rails:install --redux --typescript")
     end
 
+    specify "hidden install --redux emits a legacy warning" do
+      install_generator = install_generator_fixture(redux: true)
+
+      install_generator.send(:add_legacy_redux_install_warning)
+      output_text = GeneratorMessages.messages.join("\n")
+
+      expect(output_text).to include("legacy Redux generator path")
+      expect(output_text).to include("bundle exec rails generate react_on_rails:react_with_redux")
+    end
+
+    specify "hidden install --redux --tailwind warning stays on the install path" do
+      install_generator = install_generator_fixture(redux: true, tailwind: true)
+
+      install_generator.send(:add_legacy_redux_install_warning)
+      output_text = GeneratorMessages.messages.join("\n")
+
+      expect(output_text).to include("Redux with Tailwind")
+      expect(output_text).to include("bundle exec rails generate react_on_rails:install --redux --tailwind")
+      expect(output_text).not_to include("react_on_rails:react_with_redux")
+    end
+
     specify "shakapacker gemfile error preserves original install flags" do
       # ignore_warnings: true is required so handle_shakapacker_gemfile_error logs
       # the error instead of raising Thor::Error, which lets this example inspect output.
@@ -4643,7 +4683,8 @@ class ActiveSupport::TestCase
       expect(error_text).to include(
         "standalone react_on_rails:react_with_redux generator does not support --tailwind"
       )
-      expect(error_text).to include("rails generate react_on_rails:install --redux --tailwind")
+      expect(error_text).to include("bundle exec rails generate react_on_rails:install --redux --tailwind")
+      expect(error_text).to include("bundle exec rails generate react_on_rails:install --tailwind")
     end
 
     it "allows Redux Tailwind setup when invoked by the install generator" do
@@ -4655,6 +4696,18 @@ class ActiveSupport::TestCase
         "standalone react_on_rails:react_with_redux generator does not support --tailwind"
       )
     end
+
+    it "warns that direct standalone Redux generation is legacy" do
+      redux_generator = redux_generator_fixture
+      allow(redux_generator).to receive(:print_generator_messages)
+
+      redux_generator.add_redux_specific_messages
+
+      message_text = GeneratorMessages.messages.join("\n")
+      expect(message_text).to include("legacy Redux generator path")
+      expect(message_text).to match(/not\s+recommended for new React on Rails apps/)
+      expect(redux_generator).to have_received(:print_generator_messages)
+    end
   end
 
   describe "#create_css_module_types" do