react_on_rails 16.1.2 → 16.2.0

data/lib/generators/react_on_rails/js_dependency_manager.rb

@@ -0,0 +1,383 @@
+# 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
+
+      # SWC transpiler dependencies (for Shakapacker 9.3.0+ default transpiler)
+      # SWC is ~20x faster than Babel and is the default for new Shakapacker installations
+      SWC_DEPENDENCIES = %w[
+        @swc/core
+        swc-loader
+      ].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?
+        # SWC dependencies are only added when SWC is the configured transpiler
+        add_swc_dependencies if using_swc?
+        # 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_swc_dependencies
+        puts "Installing SWC transpiler dependencies (20x faster than Babel)..."
+        return if add_packages(SWC_DEPENDENCIES, dev: true)
+
+        GeneratorMessages.add_warning(<<~MSG.strip)
+          ⚠️  Failed to add SWC dependencies.
+
+          SWC is the default JavaScript transpiler for Shakapacker 9.3.0+.
+          You can install them manually by running:
+            npm install --save-dev #{SWC_DEPENDENCIES.join(' ')}
+        MSG
+      rescue StandardError => e
+        GeneratorMessages.add_warning(<<~MSG.strip)
+          ⚠️  Error adding SWC dependencies: #{e.message}
+
+          You can install them manually by running:
+            npm install --save-dev #{SWC_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/.dev-services.yml.example

@@ -0,0 +1,76 @@
+# Service Dependencies Configuration
+#
+# This file defines external services that must be running before bin/dev starts.
+# Copy this file to .dev-services.yml and customize for your application.
+#
+# bin/dev will check each service before starting the development server.
+# If any service is not running, it will display helpful error messages with
+# instructions on how to start the service.
+#
+# ⚠️  SECURITY WARNING:
+# Commands in this file are executed during bin/dev startup. Only add commands
+# from trusted sources. This file should not be committed if it contains
+# sensitive information or custom paths specific to your machine. Consider
+# adding .dev-services.yml to .gitignore if it contains machine-specific config.
+#
+# Security best practices:
+# - Commands are executed without shell expansion (shell metacharacters won't work)
+# - Use simple, single commands (e.g., "redis-cli ping", "pg_isready")
+# - Do NOT use shell features: &&, ||, |, $, ;, backticks, etc. will fail
+# - Only include services you trust
+# - Keep commands simple and focused on service health checks
+# - Consider adding .dev-services.yml to .gitignore (commit .example instead)
+#
+# Example configuration:
+#
+# services:
+#   redis:
+#     check_command: "redis-cli ping"
+#     expected_output: "PONG"
+#     start_command: "redis-server"
+#     install_hint: "brew install redis (macOS) or apt-get install redis-server (Linux)"
+#     description: "Redis (for caching and background jobs)"
+#
+#   postgresql:
+#     check_command: "pg_isready"
+#     expected_output: "accepting connections"
+#     start_command: "pg_ctl -D /usr/local/var/postgres start"
+#     install_hint: "brew install postgresql (macOS) or apt-get install postgresql (Linux)"
+#     description: "PostgreSQL database"
+#
+#   elasticsearch:
+#     check_command: "curl -s http://localhost:9200"
+#     expected_output: "cluster_name"
+#     start_command: "brew services start elasticsearch-full"
+#     install_hint: "brew install elasticsearch-full"
+#     description: "Elasticsearch (for search)"
+#
+# Field descriptions:
+#   check_command:    Shell command to check if service is running (required)
+#   expected_output:  String that must appear in command output (optional)
+#   start_command:    Command to start the service (shown in error messages)
+#   install_hint:     How to install the service if not found
+#   description:      Human-readable description of the service
+#
+# To use this file:
+# 1. Copy to .dev-services.yml: cp .dev-services.yml.example .dev-services.yml
+# 2. Uncomment and configure the services your app needs
+# 3. Add .dev-services.yml to .gitignore if it contains sensitive info
+# 4. Run bin/dev - it will check services before starting
+
+services:
+  # Uncomment and configure the services your application requires:
+
+  # redis:
+  #   check_command: "redis-cli ping"
+  #   expected_output: "PONG"
+  #   start_command: "redis-server"
+  #   install_hint: "brew install redis (macOS) or apt-get install redis-server (Linux)"
+  #   description: "Redis (for caching and background jobs)"
+
+  # postgresql:
+  #   check_command: "pg_isready"
+  #   expected_output: "accepting connections"
+  #   start_command: "pg_ctl -D /usr/local/var/postgres start"  # macOS; Linux: sudo service postgresql start
+  #   install_hint: "brew install postgresql (macOS) or apt-get install postgresql (Linux)"
+  #   description: "PostgreSQL database"

data/lib/generators/react_on_rails/templates/base/base/bin/shakapacker-precompile-hook

@@ -0,0 +1,30 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Shakapacker precompile hook for React on Rails
+#
+# This script runs before webpack compilation to generate pack files
+# for auto-bundled components. It's called automatically by Shakapacker
+# when configured in config/shakapacker.yml:
+#   precompile_hook: 'bin/shakapacker-precompile-hook'
+#
+# Emoji Scheme:
+#   🔄 = Running/in-progress
+#   ✅ = Success
+#   ❌ = Error
+
+# Skip validation during precompile hook execution
+# The hook runs early in the build process, potentially before full Rails initialization,
+# and doesn't need package version validation since it's part of the build itself
+ENV["REACT_ON_RAILS_SKIP_VALIDATION"] = "true"
+
+require_relative "../config/environment"
+
+begin
+  puts Rainbow("🔄 Running React on Rails precompile hook...").cyan
+  ReactOnRails::PacksGenerator.instance.generate_packs_if_stale
+rescue StandardError => e
+  warn Rainbow("❌ Error in precompile hook: #{e.message}").red
+  warn e.backtrace.first(5).join("\n")
+  exit 1
+end

data/lib/generators/react_on_rails/templates/base/base/bin/switch-bundler

@@ -0,0 +1,141 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "fileutils"
+require "yaml"
+require "json"
+
+# Script to switch between webpack and rspack bundlers
+class BundlerSwitcher
+  WEBPACK_DEPS = {
+    dependencies: %w[webpack webpack-assets-manifest webpack-merge],
+    dev_dependencies: %w[webpack-cli webpack-dev-server @pmmmwh/react-refresh-webpack-plugin]
+  }.freeze
+
+  RSPACK_DEPS = {
+    dependencies: %w[@rspack/core rspack-manifest-plugin],
+    dev_dependencies: %w[@rspack/cli @rspack/plugin-react-refresh]
+  }.freeze
+
+  def initialize(target_bundler)
+    @target_bundler = target_bundler.to_s.downcase
+    @shakapacker_config = "config/shakapacker.yml"
+    validate_bundler!
+  end
+
+  def switch!
+    puts "🔄 Switching to #{@target_bundler}..."
+
+    update_shakapacker_config
+    update_dependencies
+    install_dependencies
+
+    puts "✅ Successfully switched to #{@target_bundler}!"
+    puts "\nNext steps:"
+    puts "  1. Review your webpack configuration files in config/webpack/"
+    puts "  2. Restart your development server"
+  end
+
+  private
+
+  def validate_bundler!
+    return if %w[webpack rspack].include?(@target_bundler)
+
+    abort "❌ Invalid bundler: #{@target_bundler}. Use 'webpack' or 'rspack'"
+  end
+
+  def update_shakapacker_config
+    abort "❌ #{@shakapacker_config} not found" unless File.exist?(@shakapacker_config)
+
+    puts "📝 Updating #{@shakapacker_config}..."
+    config = YAML.load_file(@shakapacker_config)
+
+    config["default"] ||= {}
+    config["default"]["assets_bundler"] = @target_bundler
+
+    # Update webpack_loader based on bundler
+    # Rspack works best with SWC, webpack typically uses babel
+    config["default"]["webpack_loader"] = @target_bundler == "rspack" ? "swc" : "babel"
+
+    File.write(@shakapacker_config, YAML.dump(config))
+    puts "✅ Updated assets_bundler to '#{@target_bundler}'"
+  end
+
+  def update_dependencies
+    puts "📦 Updating package.json dependencies..."
+
+    package_json_path = "package.json"
+    unless File.exist?(package_json_path)
+      puts "⚠️  package.json not found, skipping dependency updates"
+      return
+    end
+
+    package_json = JSON.parse(File.read(package_json_path))
+
+    remove_deps = @target_bundler == "rspack" ? WEBPACK_DEPS : RSPACK_DEPS
+
+    # Remove old bundler dependencies
+    remove_deps[:dependencies].each do |dep|
+      package_json["dependencies"]&.delete(dep)
+    end
+    remove_deps[:dev_dependencies].each do |dep|
+      package_json["devDependencies"]&.delete(dep)
+    end
+
+    puts "✅ Removed #{@target_bundler == 'rspack' ? 'webpack' : 'rspack'} dependencies"
+    File.write(package_json_path, JSON.pretty_generate(package_json))
+  end
+
+  def install_dependencies
+    puts "📥 Installing #{@target_bundler} dependencies..."
+
+    deps = @target_bundler == "rspack" ? RSPACK_DEPS : WEBPACK_DEPS
+
+    # Detect package manager
+    package_manager = detect_package_manager
+
+    # Install dependencies using array form to prevent command injection
+    success = case package_manager
+              when "yarn"
+                system("yarn", "add", *deps[:dependencies])
+              when "pnpm"
+                system("pnpm", "add", *deps[:dependencies])
+              else
+                system("npm", "install", *deps[:dependencies])
+              end
+
+    abort("❌ Failed to install dependencies") unless success
+
+    # Install dev dependencies using array form to prevent command injection
+    success = case package_manager
+              when "yarn"
+                system("yarn", "add", "-D", *deps[:dev_dependencies])
+              when "pnpm"
+                system("pnpm", "add", "-D", *deps[:dev_dependencies])
+              else
+                system("npm", "install", "--save-dev", *deps[:dev_dependencies])
+              end
+
+    abort("❌ Failed to install dev dependencies") unless success
+
+    puts "✅ Installed #{@target_bundler} dependencies"
+  end
+
+  def detect_package_manager
+    return "yarn" if File.exist?("yarn.lock")
+    return "pnpm" if File.exist?("pnpm-lock.yaml")
+
+    "npm"
+  end
+end
+
+# Main execution
+if ARGV.empty?
+  puts "Usage: bin/switch-bundler [webpack|rspack]"
+  puts "\nExamples:"
+  puts "  bin/switch-bundler rspack   # Switch to Rspack"
+  puts "  bin/switch-bundler webpack  # Switch to Webpack"
+  exit 1
+end
+
+BundlerSwitcher.new(ARGV[0]).switch!