react_on_rails 16.2.0.beta.8 → 16.2.0.beta.11

data/lib/generators/react_on_rails/generator_helper.rb

@@ -95,4 +95,33 @@ module GeneratorHelper
   def component_extension(options)
     options.typescript? ? "tsx" : "jsx"
   end
+
+  # Check if Shakapacker 9.0 or higher is available
+  # Returns true if Shakapacker >= 9.0, false otherwise
+  #
+  # This method is used during code generation to determine which configuration
+  # patterns to use in generated files (e.g., config.privateOutputPath vs hardcoded paths).
+  #
+  # @return [Boolean] true if Shakapacker 9.0+ is available or likely to be installed
+  #
+  # @note Default behavior: Returns true when Shakapacker is not yet installed
+  #   Rationale: During fresh installations, we optimistically assume users will install
+  #   the latest Shakapacker version. This ensures new projects get best-practice configs.
+  #   If users later install an older version, the generated webpack config includes
+  #   fallback logic (e.g., `config.privateOutputPath || hardcodedPath`) that prevents
+  #   breakage, and validation warnings guide them to fix any misconfigurations.
+  def shakapacker_version_9_or_higher?
+    return @shakapacker_version_9_or_higher if defined?(@shakapacker_version_9_or_higher)
+
+    @shakapacker_version_9_or_higher = begin
+      # If Shakapacker is not available yet (fresh install), default to true
+      # since we're likely installing the latest version
+      return true unless defined?(ReactOnRails::PackerUtils)
+
+      ReactOnRails::PackerUtils.shakapacker_version_requirement_met?("9.0.0")
+    rescue StandardError
+      # If we can't determine version, assume latest
+      true
+    end
+  end
 end

data/lib/generators/react_on_rails/install_generator.rb

@@ -4,12 +4,14 @@ require "rails/generators"
 require "json"
 require_relative "generator_helper"
 require_relative "generator_messages"
+require_relative "js_dependency_manager"
 
 module ReactOnRails
   module Generators
     # rubocop:disable Metrics/ClassLength
     class InstallGenerator < Rails::Generators::Base
       include GeneratorHelper
+      include JsDependencyManager
 
       # fetch USAGE file for details generator description
       source_root(File.expand_path(__dir__))
@@ -113,10 +115,7 @@ module ReactOnRails
       end
 
       def setup_react_dependencies
-        @added_dependencies_to_package_json ||= false
-        @ran_direct_installs ||= false
-        add_js_dependencies
-        install_js_dependencies if @added_dependencies_to_package_json && !@ran_direct_installs
+        setup_js_dependencies
       end
 
       # NOTE: other requirements for existing files such as .gitignore or application.
@@ -366,29 +365,8 @@ module ReactOnRails
 
       def install_typescript_dependencies
         puts Rainbow("📝 Installing TypeScript dependencies...").yellow
-
-        # Install TypeScript and React type definitions
-        typescript_packages = %w[
-          typescript
-          @types/react
-          @types/react-dom
-          @babel/preset-typescript
-        ]
-
-        # Try using GeneratorHelper first (package manager agnostic)
-        return if add_npm_dependencies(typescript_packages, dev: true)
-
-        # Fallback to npm if GeneratorHelper fails
-        success = system("npm", "install", "--save-dev", *typescript_packages)
-        return if success
-
-        warning = <<~MSG.strip
-          ⚠️  Failed to install TypeScript dependencies automatically.
-
-          Please run manually:
-              npm install --save-dev #{typescript_packages.join(' ')}
-        MSG
-        GeneratorMessages.add_warning(warning)
+        # Delegate to shared module for consistent dependency management
+        add_typescript_dependencies
       end
 
       def create_css_module_types
@@ -450,159 +428,6 @@ module ReactOnRails
         puts Rainbow("✅ Created tsconfig.json").green
       end
 
-      def add_js_dependencies
-        add_react_on_rails_package
-        add_react_dependencies
-        add_css_dependencies
-        add_rspack_dependencies if options.rspack?
-        add_dev_dependencies
-      end
-
-      def add_react_on_rails_package
-        major_minor_patch_only = /\A\d+\.\d+\.\d+\z/
-
-        # Try to use package_json gem first, fall back to direct npm commands
-        react_on_rails_pkg = if ReactOnRails::VERSION.match?(major_minor_patch_only)
-                               ["react-on-rails@#{ReactOnRails::VERSION}"]
-                             else
-                               puts "Adding the latest react-on-rails NPM module. " \
-                                    "Double check this is correct in package.json"
-                               ["react-on-rails"]
-                             end
-
-        puts "Installing React on Rails package..."
-        if add_npm_dependencies(react_on_rails_pkg)
-          @added_dependencies_to_package_json = true
-          return
-        end
-
-        puts "Using direct npm commands as fallback"
-        success = system("npm", "install", *react_on_rails_pkg)
-        @ran_direct_installs = true if success
-        handle_npm_failure("react-on-rails package", react_on_rails_pkg) unless success
-      end
-
-      def add_react_dependencies
-        puts "Installing React dependencies..."
-        react_deps = %w[
-          react
-          react-dom
-          @babel/preset-react
-          prop-types
-          babel-plugin-transform-react-remove-prop-types
-          babel-plugin-macros
-        ]
-        if add_npm_dependencies(react_deps)
-          @added_dependencies_to_package_json = true
-          return
-        end
-
-        success = system("npm", "install", *react_deps)
-        @ran_direct_installs = true if success
-        handle_npm_failure("React dependencies", react_deps) unless success
-      end
-
-      def add_css_dependencies
-        puts "Installing CSS handling dependencies..."
-        css_deps = %w[
-          css-loader
-          css-minimizer-webpack-plugin
-          mini-css-extract-plugin
-          style-loader
-        ]
-        if add_npm_dependencies(css_deps)
-          @added_dependencies_to_package_json = true
-          return
-        end
-
-        success = system("npm", "install", *css_deps)
-        @ran_direct_installs = true if success
-        handle_npm_failure("CSS dependencies", css_deps) unless success
-      end
-
-      def add_rspack_dependencies
-        puts "Installing Rspack core dependencies..."
-        rspack_deps = %w[
-          @rspack/core
-          rspack-manifest-plugin
-        ]
-        if add_npm_dependencies(rspack_deps)
-          @added_dependencies_to_package_json = true
-          return
-        end
-
-        success = system("npm", "install", *rspack_deps)
-        @ran_direct_installs = true if success
-        handle_npm_failure("Rspack dependencies", rspack_deps) unless success
-      end
-
-      def add_dev_dependencies
-        puts "Installing development dependencies..."
-        dev_deps = if options.rspack?
-                     %w[
-                       @rspack/cli
-                       @rspack/plugin-react-refresh
-                       react-refresh
-                     ]
-                   else
-                     %w[
-                       @pmmmwh/react-refresh-webpack-plugin
-                       react-refresh
-                     ]
-                   end
-        if add_npm_dependencies(dev_deps, dev: true)
-          @added_dependencies_to_package_json = true
-          return
-        end
-
-        success = system("npm", "install", "--save-dev", *dev_deps)
-        @ran_direct_installs = true if success
-        handle_npm_failure("development dependencies", dev_deps, dev: true) unless success
-      end
-
-      def install_js_dependencies
-        # Detect which package manager to use
-        success = if File.exist?(File.join(destination_root, "yarn.lock"))
-                    system("yarn", "install")
-                  elsif File.exist?(File.join(destination_root, "pnpm-lock.yaml"))
-                    system("pnpm", "install")
-                  elsif File.exist?(File.join(destination_root, "package-lock.json")) ||
-                        File.exist?(File.join(destination_root, "package.json"))
-                    # Use npm for package-lock.json or as default fallback
-                    system("npm", "install")
-                  else
-                    true # No package manager detected, skip
-                  end
-
-        unless success
-          GeneratorMessages.add_warning(<<~MSG.strip)
-            ⚠️  JavaScript dependencies installation failed.
-
-            This could be due to network issues or missing package manager.
-            You can install dependencies manually later by running:
-            • npm install (if using npm)
-            • yarn install (if using yarn)
-            • pnpm install (if using pnpm)
-          MSG
-        end
-
-        success
-      end
-
-      def handle_npm_failure(dependency_type, packages, dev: false)
-        install_command = dev ? "npm install --save-dev" : "npm install"
-        GeneratorMessages.add_warning(<<~MSG.strip)
-          ⚠️  Failed to install #{dependency_type}.
-
-          The following packages could not be installed automatically:
-          #{packages.map { |pkg| "  • #{pkg}" }.join("\n")}
-
-          This could be due to network issues or missing package manager.
-          You can install them manually later by running:
-            #{install_command} #{packages.join(' ')}
-        MSG
-      end
-
       # Removed: Shakapacker auto-installation logic (now explicit dependency)
 
       # Removed: Shakapacker 8+ is now required as explicit dependency

data/lib/generators/react_on_rails/js_dependency_manager.rb

@@ -0,0 +1,354 @@
+# frozen_string_literal: true
+
+require_relative "generator_messages"
+
+# rubocop:disable Metrics/ModuleLength
+module ReactOnRails
+  module Generators
+    # Shared module for managing JavaScript dependencies across generators
+    # This module provides common functionality for adding and installing
+    # JS dependencies to avoid code duplication between generators.
+    #
+    # Since react_on_rails requires shakapacker, and shakapacker includes
+    # package_json as a dependency, the package_json gem is always available.
+    #
+    # == Required Methods
+    # Including classes must include GeneratorHelper module which provides:
+    # - add_npm_dependencies(packages, dev: false): Add packages via package_json gem
+    # - package_json: Access to PackageJson instance (always available via shakapacker)
+    # - destination_root: Generator destination directory
+    #
+    # == Optional Methods
+    # Including classes may define:
+    # - options.rspack?: Returns true if --rspack flag is set (for Rspack support)
+    # - options.typescript?: Returns true if --typescript flag is set (for TypeScript support)
+    #
+    # == Installation Behavior
+    # The module ALWAYS runs package manager install after adding dependencies.
+    # This is safe because package_json gem's install method is idempotent - it only
+    # installs what's actually needed from package.json. This prevents edge cases
+    # where package.json was modified but dependencies weren't installed.
+    #
+    # == Error Handling Philosophy
+    # All dependency addition methods use a graceful degradation approach:
+    # - Methods return false on failure instead of raising exceptions
+    # - StandardError is caught at the lowest level (add_package) and higher levels (add_*_dependencies)
+    # - Failures trigger user-facing warnings via GeneratorMessages
+    # - Warnings provide clear manual installation instructions
+    #
+    # This ensures the generator ALWAYS completes successfully, even when:
+    # - Network connectivity issues prevent package downloads
+    # - Package manager (npm/yarn/pnpm) has permission errors
+    # - package_json gem encounters unexpected states
+    #
+    # Users can manually run package installation commands after generator completion.
+    # This is preferable to generator crashes that leave Rails apps in incomplete states.
+    #
+    # == Usage
+    # Include this module in generator classes and call setup_js_dependencies
+    # to handle all JS dependency installation via package_json gem.
+    module JsDependencyManager
+      # Core React dependencies required for React on Rails
+      # Note: @babel/preset-react and babel plugins are NOT included here because:
+      # - Shakapacker handles JavaScript transpiler configuration (babel, swc, or esbuild)
+      # - Users configure their preferred transpiler via shakapacker.yml javascript_transpiler setting
+      # - SWC is now the default and doesn't need Babel presets
+      # - For Babel users, shakapacker will install babel-loader and its dependencies
+      REACT_DEPENDENCIES = %w[
+        react
+        react-dom
+        prop-types
+      ].freeze
+
+      # CSS processing dependencies for webpack
+      CSS_DEPENDENCIES = %w[
+        css-loader
+        css-minimizer-webpack-plugin
+        mini-css-extract-plugin
+        style-loader
+      ].freeze
+
+      # Development-only dependencies for hot reloading (Webpack)
+      DEV_DEPENDENCIES = %w[
+        @pmmmwh/react-refresh-webpack-plugin
+        react-refresh
+      ].freeze
+
+      # Rspack core dependencies (only installed when --rspack flag is used)
+      RSPACK_DEPENDENCIES = %w[
+        @rspack/core
+        rspack-manifest-plugin
+      ].freeze
+
+      # Rspack development dependencies for hot reloading
+      RSPACK_DEV_DEPENDENCIES = %w[
+        @rspack/cli
+        @rspack/plugin-react-refresh
+        react-refresh
+      ].freeze
+
+      # TypeScript dependencies (only installed when --typescript flag is used)
+      # Note: @babel/preset-typescript is NOT included because:
+      # - SWC is now the default javascript_transpiler (has built-in TypeScript support)
+      # - Shakapacker handles the transpiler configuration via shakapacker.yml
+      # - If users choose javascript_transpiler: 'babel', they should manually add @babel/preset-typescript
+      #   and configure it in their babel.config.js
+      TYPESCRIPT_DEPENDENCIES = %w[
+        typescript
+        @types/react
+        @types/react-dom
+      ].freeze
+
+      private
+
+      def setup_js_dependencies
+        add_js_dependencies
+
+        # Always run install to ensure all dependencies are properly installed.
+        # The package_json gem's install method is idempotent and safe to call
+        # even if packages were already added - it will only install what's needed.
+        # This ensures edge cases where package.json was modified but install wasn't
+        # run are handled correctly.
+        install_js_dependencies
+      end
+
+      def add_js_dependencies
+        add_react_on_rails_package
+        add_react_dependencies
+        add_css_dependencies
+        # Rspack dependencies are only added when --rspack flag is used
+        add_rspack_dependencies if respond_to?(:options) && options&.rspack?
+        # Dev dependencies vary based on bundler choice
+        add_dev_dependencies
+      end
+
+      def add_react_on_rails_package
+        # Use exact version match between gem and npm package for all versions including pre-releases
+        # Ruby gem versions use dots (16.2.0.beta.10) but npm requires hyphens (16.2.0-beta.10)
+        # This method converts between the two formats.
+        #
+        # The regex matches:
+        # - Stable: 16.2.0
+        # - Beta (Ruby): 16.2.0.beta.10 or (npm): 16.2.0-beta.10
+        # - RC (Ruby): 16.1.0.rc.1 or (npm): 16.1.0-rc.1
+        # - Alpha (Ruby): 16.0.0.alpha.5 or (npm): 16.0.0-alpha.5
+        # This ensures beta/rc versions use the exact version instead of "latest" which would
+        # install the latest stable release and cause version mismatches.
+
+        # Accept both dot and hyphen separators for pre-release versions
+        version_with_optional_prerelease = /\A(\d+\.\d+\.\d+)([-.]([a-zA-Z0-9.]+))?\z/
+
+        react_on_rails_pkg = if (match = ReactOnRails::VERSION.match(version_with_optional_prerelease))
+                               base_version = match[1]
+                               prerelease = match[3]
+
+                               # Convert Ruby gem format (dot) to npm semver format (hyphen)
+                               npm_version = if prerelease
+                                               "#{base_version}-#{prerelease}"
+                                             else
+                                               base_version
+                                             end
+
+                               "react-on-rails@#{npm_version}"
+                             else
+                               puts "WARNING: Unrecognized version format #{ReactOnRails::VERSION}. " \
+                                    "Adding the latest react-on-rails NPM module. " \
+                                    "Double check this is correct in package.json"
+                               "react-on-rails"
+                             end
+
+        puts "Installing React on Rails package..."
+        return if add_package(react_on_rails_pkg)
+
+        GeneratorMessages.add_warning(<<~MSG.strip)
+          ⚠️  Failed to add react-on-rails package.
+
+          You can install it manually by running:
+            npm install #{react_on_rails_pkg}
+        MSG
+      rescue StandardError => e
+        GeneratorMessages.add_warning(<<~MSG.strip)
+          ⚠️  Error adding react-on-rails package: #{e.message}
+
+          You can install it manually by running:
+            npm install #{react_on_rails_pkg}
+        MSG
+      end
+
+      def add_react_dependencies
+        puts "Installing React dependencies..."
+        return if add_packages(REACT_DEPENDENCIES)
+
+        GeneratorMessages.add_warning(<<~MSG.strip)
+          ⚠️  Failed to add React dependencies.
+
+          You can install them manually by running:
+            npm install #{REACT_DEPENDENCIES.join(' ')}
+        MSG
+      rescue StandardError => e
+        GeneratorMessages.add_warning(<<~MSG.strip)
+          ⚠️  Error adding React dependencies: #{e.message}
+
+          You can install them manually by running:
+            npm install #{REACT_DEPENDENCIES.join(' ')}
+        MSG
+      end
+
+      def add_css_dependencies
+        puts "Installing CSS handling dependencies..."
+        return if add_packages(CSS_DEPENDENCIES)
+
+        GeneratorMessages.add_warning(<<~MSG.strip)
+          ⚠️  Failed to add CSS dependencies.
+
+          You can install them manually by running:
+            npm install #{CSS_DEPENDENCIES.join(' ')}
+        MSG
+      rescue StandardError => e
+        GeneratorMessages.add_warning(<<~MSG.strip)
+          ⚠️  Error adding CSS dependencies: #{e.message}
+
+          You can install them manually by running:
+            npm install #{CSS_DEPENDENCIES.join(' ')}
+        MSG
+      end
+
+      def add_rspack_dependencies
+        puts "Installing Rspack core dependencies..."
+        return if add_packages(RSPACK_DEPENDENCIES)
+
+        GeneratorMessages.add_warning(<<~MSG.strip)
+          ⚠️  Failed to add Rspack dependencies.
+
+          You can install them manually by running:
+            npm install #{RSPACK_DEPENDENCIES.join(' ')}
+        MSG
+      rescue StandardError => e
+        GeneratorMessages.add_warning(<<~MSG.strip)
+          ⚠️  Error adding Rspack dependencies: #{e.message}
+
+          You can install them manually by running:
+            npm install #{RSPACK_DEPENDENCIES.join(' ')}
+        MSG
+      end
+
+      def add_typescript_dependencies
+        puts "Installing TypeScript dependencies..."
+        return if add_packages(TYPESCRIPT_DEPENDENCIES, dev: true)
+
+        GeneratorMessages.add_warning(<<~MSG.strip)
+          ⚠️  Failed to add TypeScript dependencies.
+
+          You can install them manually by running:
+            npm install --save-dev #{TYPESCRIPT_DEPENDENCIES.join(' ')}
+        MSG
+      rescue StandardError => e
+        GeneratorMessages.add_warning(<<~MSG.strip)
+          ⚠️  Error adding TypeScript dependencies: #{e.message}
+
+          You can install them manually by running:
+            npm install --save-dev #{TYPESCRIPT_DEPENDENCIES.join(' ')}
+        MSG
+      end
+
+      def add_dev_dependencies
+        puts "Installing development dependencies..."
+
+        # Use Rspack-specific dev dependencies if --rspack flag is set
+        dev_deps = if respond_to?(:options) && options&.rspack?
+                     RSPACK_DEV_DEPENDENCIES
+                   else
+                     DEV_DEPENDENCIES
+                   end
+
+        return if add_packages(dev_deps, dev: true)
+
+        GeneratorMessages.add_warning(<<~MSG.strip)
+          ⚠️  Failed to add development dependencies.
+
+          You can install them manually by running:
+            npm install --save-dev #{dev_deps.join(' ')}
+        MSG
+      rescue StandardError => e
+        GeneratorMessages.add_warning(<<~MSG.strip)
+          ⚠️  Error adding development dependencies: #{e.message}
+
+          You can install them manually by running:
+            npm install --save-dev #{dev_deps.join(' ')}
+        MSG
+      end
+
+      # Add a single dependency using package_json gem
+      #
+      # This method is used internally for adding the react-on-rails package
+      # with version-specific handling (react-on-rails@VERSION).
+      # For batch operations, use add_packages instead.
+      #
+      # The exact: true flag ensures version pinning aligns with the gem version,
+      # preventing version mismatches between the Ruby gem and NPM package.
+      #
+      # @param package [String] Package specifier (e.g., "react-on-rails@16.0.0")
+      # @param dev [Boolean] Whether to add as dev dependency
+      # @return [Boolean] true if successful, false otherwise
+      def add_package(package, dev: false)
+        pj = package_json
+        return false unless pj
+
+        begin
+          # Ensure package is in array format for package_json gem
+          packages_array = [package]
+          if dev
+            pj.manager.add(packages_array, type: :dev, exact: true)
+          else
+            pj.manager.add(packages_array, exact: true)
+          end
+          true
+        rescue StandardError
+          # Return false to trigger warning in calling method
+          false
+        end
+      end
+
+      # Add multiple dependencies at once using package_json gem
+      #
+      # This method delegates to GeneratorHelper's add_npm_dependencies for
+      # better package manager abstraction and batch processing efficiency.
+      #
+      # @param packages [Array<String>] Package names to add
+      # @param dev [Boolean] Whether to add as dev dependencies
+      # @return [Boolean] true if successful, false otherwise
+      def add_packages(packages, dev: false)
+        # Use the add_npm_dependencies helper from GeneratorHelper
+        add_npm_dependencies(packages, dev: dev)
+      end
+
+      def install_js_dependencies
+        # Use package_json gem's install method (always available via shakapacker)
+        # package_json is guaranteed to be available because:
+        # 1. react_on_rails gemspec requires shakapacker
+        # 2. shakapacker gemspec requires package_json
+        # 3. GeneratorHelper provides package_json method
+        pj = package_json
+        unless pj
+          GeneratorMessages.add_warning("package_json not available, skipping dependency installation")
+          return false
+        end
+
+        pj.manager.install
+        true
+      rescue StandardError => e
+        GeneratorMessages.add_warning(<<~MSG.strip)
+          ⚠️  JavaScript dependencies installation failed: #{e.message}
+
+          This could be due to network issues or package manager problems.
+          You can install dependencies manually later by running:
+          • npm install (if using npm)
+          • yarn install (if using yarn)
+          • pnpm install (if using pnpm)
+        MSG
+        false
+      end
+    end
+  end
+end
+# rubocop:enable Metrics/ModuleLength

data/lib/generators/react_on_rails/templates/base/base/config/initializers/react_on_rails.rb.tt

@@ -12,6 +12,25 @@ ReactOnRails.configure do |config|
   # Set to "" if you're not using server rendering
   config.server_bundle_js_file = "server-bundle.js"
 
+  # ⚠️ RECOMMENDED: Use Shakapacker 9.0+ private_output_path instead
+  #
+  # If using Shakapacker 9.0+, add to config/shakapacker.yml:
+  #   private_output_path: ssr-generated
+  #
+  # React on Rails will auto-detect this value, eliminating the need to set it here.
+  # This keeps your webpack and Rails configs in sync automatically.
+  #
+  # For older Shakapacker versions or custom setups, manually configure:
+  # config.server_bundle_output_path = "ssr-generated"
+  #
+  # The path is relative to Rails.root and should point to a private directory
+  # (outside of public/) for security. Run 'rails react_on_rails:doctor' to verify.
+
+  # Enforce that server bundles are only loaded from private (non-public) directories.
+  # When true, server bundles will only be loaded from the configured server_bundle_output_path.
+  # This is recommended for production to prevent server-side code from being exposed.
+  config.enforce_private_server_bundles = true
+
   ################################################################################
   # Test Configuration (Optional)
   ################################################################################

data/lib/generators/react_on_rails/templates/base/base/config/{shakapacker.yml → shakapacker.yml.tt}

@@ -29,6 +29,15 @@ default: &default
   # Location for manifest.json, defaults to {public_output_path}/manifest.json if unset
   # manifest_path: public/packs/manifest.json
 
+  # Location for private server-side bundles (e.g., for SSR)
+  # These bundles are not served publicly, unlike public_output_path
+  # Shakapacker 9.0+ feature - automatically detected by React on Rails
+<% if shakapacker_version_9_or_higher? -%>
+  private_output_path: ssr-generated
+<% else -%>
+  # private_output_path: ssr-generated  # Uncomment to enable (requires Shakapacker 9.0+)
+<% end -%>
+
   # Additional paths webpack should look up modules
   # ['app/assets', 'engine/foo/app/assets']
   additional_paths: []
@@ -36,8 +45,15 @@ default: &default
   # Reload manifest.json on all requests so we reload latest compiled packs
   cache_manifest: false
 
-  # Select loader to use, available options are 'babel' (default), 'swc' or 'esbuild'
-  webpack_loader: 'babel'
+  # Select JavaScript transpiler to use
+  # Available options: 'swc' (default, 20x faster), 'babel', 'esbuild', or 'none'
+  # Use 'none' when providing a completely custom webpack configuration
+  # Note: When using rspack, swc is used automatically regardless of this setting
+  javascript_transpiler: "swc"
+
+  # Select assets bundler to use
+  # Available options: 'webpack' (default) or 'rspack'
+  assets_bundler: "webpack"
 
   # Raises an error if there is a mismatch in the shakapacker gem and npm package being used
   ensure_consistent_versioning: true