react_on_rails 15.0.0.rc.2 → 16.0.0

data/TODO.md

@@ -0,0 +1,135 @@
+# React on Rails TODO
+
+## Generator Improvements
+
+### HelloWorld Component Structure
+
+- [x] Fix bad import in HelloWorld.server.jsx (server importing from client)
+- [x] Simplify to single HelloWorld.jsx file with documentation
+- [ ] **Consider alternative approach**: Create second example component showing client/server split
+  - Add `client_server_different.jsx` in sibling directory like `/examples/` or `/advanced/`
+  - Show real-world use case (React Router, styled-components, etc.)
+  - Keep HelloWorld simple for beginners
+
+### File Organization
+
+- [x] **Improved ror_components directory structure**
+  - Documentation now suggests moving shared components to `../components/` directory
+  - Keeps ror_components clean for React on Rails specific entry points
+  - Recommended structure:
+    ```
+    src/HelloWorld/
+    ├── components/
+    │   └── HelloWorld.jsx          # Shared component implementation
+    └── ror_components/
+        ├── HelloWorld.client.jsx   # Client entry point (when needed)
+        └── HelloWorld.server.jsx   # Server entry point (when needed)
+    ```
+- [ ] **Consider adding generator flag to create this structure automatically**
+
+### Generator Options
+
+- [ ] **Add generator flags for different patterns**
+  - `--simple` (default): Single component file
+  - `--split`: Generate client/server split example
+  - `--example-name`: Customize component name beyond HelloWorld
+
+## Documentation Improvements
+
+### Component Architecture Guide
+
+- [ ] **Add comprehensive docs on client/server patterns**
+  - When to use single vs split files
+  - Common libraries requiring server setup (React Router, styled-components, Apollo)
+  - Migration path from simple to split architecture
+  - Auto-registration behavior explanation
+
+### Code Comments
+
+- [x] Add inline documentation to HelloWorld.jsx explaining split pattern
+- [ ] Add JSDoc comments for better IDE support
+- [ ] Include links to relevant documentation sections
+
+## Testing Infrastructure
+
+- [ ] **Test generator output for both simple and split patterns**
+- [ ] **Validate that auto-registration works correctly**
+- [ ] **Add integration tests for client/server rendering differences**
+
+## Developer Experience
+
+- [ ] **bin/dev help command enhancements**
+
+  - [x] Add emojis and colors for better readability
+  - [ ] Add section about component development patterns
+  - [ ] Include troubleshooting for client/server split issues
+
+- [ ] **Babel Configuration Conflict Detection**
+
+  - [ ] Add validation in generator/initializer to detect conflicting Babel configs
+  - [ ] Improve error messaging for duplicate preset issues
+  - [ ] Common conflict: babel.config.js + package.json "babel" section
+  - [ ] Specific guidance for yalc development workflow
+  - [ ] Add troubleshooting section for this common issue:
+
+    ```
+    ❌ BABEL CONFIGURATION CONFLICT DETECTED
+    Found duplicate Babel configurations:
+    • babel.config.js ✓ (recommended)
+    • package.json "babel" section ❌ (conflicting)
+
+    🔧 FIX: Remove the "babel" section from package.json
+    ```
+
+### IDE Support
+
+- [ ] **Improve TypeScript support**
+  - Add .d.ts files for better type inference
+  - Document TypeScript patterns for client/server split
+  - Consider TypeScript generator templates
+
+## Performance & Bundle Analysis
+
+- [ ] **Bundle splitting documentation**
+  - How React on Rails handles client/server bundles
+  - Best practices for code splitting
+  - webpack bundle analysis guidance
+
+## Real-World Examples
+
+- [ ] **Create example apps showing advanced patterns**
+  - React Router with SSR
+  - styled-components with server-side rendering
+  - Apollo Client hydration
+  - Next.js-style patterns
+
+## Migration Guide
+
+- [ ] **Document upgrade paths**
+  - Converting from Webpacker to Shakapacker
+  - Migrating from single to split components
+  - Updating existing projects to new patterns
+
+## Community & Ecosystem
+
+- [ ] **Plugin ecosystem considerations**
+  - Standard patterns for community components
+  - Guidelines for React on Rails compatible libraries
+  - Template repository for component patterns
+
+---
+
+## Current Known Issues
+
+- Generator installer still has remaining issues (mentioned in context)
+- Version mismatch warnings with yalc during development
+- Need clearer documentation on when to use different patterns
+- **Babel configuration conflicts** - Common during yalc development when package.json and babel.config.js both define presets
+
+## Priority Order
+
+1. Fix remaining generator installer issues
+2. Improve HelloWorld component documentation
+3. Add alternative example showing client/server split
+4. Create comprehensive architecture documentation
+5. Add generator flags for different patterns

data/eslint.config.ts

@@ -152,6 +152,8 @@ const config = tsEslint.config([
       'import/no-unresolved': 'off',
       // We have `const [name, setName] = useState(props.name)` so can't just destructure props
       'react/destructuring-assignment': 'off',
+      // React 19 doesn't need PropTypes - we're targeting modern React
+      'react/prop-types': 'off',
     },
   },
   {

data/lib/generators/USAGE

@@ -1,9 +1,8 @@
 Description:
 
-The react_on_rails:install generator integrates Webpack with Rails with ease. You
-can pass the redux option if you'd like to have redux setup for you automatically.
+The react_on_rails:install generator integrates a React frontend, including SSR, with Rails.
 
-* Redux
+* Redux (Optional)
 
     Passing the --redux generator option causes the generated Hello World example
     to integrate the Redux state container framework. The necessary node modules
@@ -13,11 +12,11 @@ can pass the redux option if you'd like to have redux setup for you automaticall
 
 After running the generator, you will want to:
 
-    bundle && yarn
+    bundle && npm install     # or yarn install, or pnpm install
 
 Then you may run
 
-    foreman start -f Procfile.dev
+    ./bin/dev
 
 More Details:
 

data/lib/generators/react_on_rails/base_generator.rb

@@ -1,12 +1,14 @@
 # frozen_string_literal: true
 
 require "rails/generators"
+require "fileutils"
 require_relative "generator_messages"
 require_relative "generator_helper"
 module ReactOnRails
   module Generators
     class BaseGenerator < Rails::Generators::Base
       include GeneratorHelper
+
       Rails::Generators.hide_namespace(namespace)
       source_root(File.expand_path("templates", __dir__))
 
@@ -14,7 +16,7 @@ module ReactOnRails
       class_option :redux,
                    type: :boolean,
                    default: false,
-                   desc: "Install Redux gems and Redux version of Hello World Example",
+                   desc: "Install Redux package and Redux version of Hello World Example",
                    aliases: "-R"
 
       def add_hello_world_route
@@ -22,17 +24,21 @@ module ReactOnRails
       end
 
       def create_react_directories
-        dirs = %w[components]
-        dirs.each { |name| empty_directory("app/javascript/bundles/HelloWorld/#{name}") }
+        # Create auto-registration directory structure for non-Redux components only
+        # Redux components handle their own directory structure
+        return if options.redux?
+
+        empty_directory("app/javascript/src/HelloWorld/ror_components")
       end
 
       def copy_base_files
         base_path = "base/base/"
         base_files = %w[app/controllers/hello_world_controller.rb
-                        app/views/layouts/hello_world.html.erb]
-        base_templates = %w[config/initializers/react_on_rails.rb
-                            Procfile.dev
-                            Procfile.dev-static]
+                        app/views/layouts/hello_world.html.erb
+                        Procfile.dev
+                        Procfile.dev-static-assets
+                        Procfile.dev-prod-assets]
+        base_templates = %w[config/initializers/react_on_rails.rb]
         base_files.each { |file| copy_file("#{base_path}#{file}", file) }
         base_templates.each do |file|
           template("#{base_path}/#{file}.tt", file, { packer_type: ReactOnRails::PackerUtils.packer_type })
@@ -41,9 +47,12 @@ module ReactOnRails
 
       def copy_js_bundle_files
         base_path = "base/base/"
-        base_files = %w[app/javascript/packs/server-bundle.js
-                        app/javascript/bundles/HelloWorld/components/HelloWorldServer.js
-                        app/javascript/bundles/HelloWorld/components/HelloWorld.module.css]
+        base_files = %w[app/javascript/packs/server-bundle.js]
+
+        # Only copy HelloWorld.module.css for non-Redux components
+        # Redux components handle their own CSS files
+        base_files << "app/javascript/src/HelloWorld/ror_components/HelloWorld.module.css" unless options.redux?
+
         base_files.each { |file| copy_file("#{base_path}#{file}", file) }
       end
 
@@ -57,15 +66,25 @@ module ReactOnRails
                         config/webpack/development.js
                         config/webpack/production.js
                         config/webpack/serverWebpackConfig.js
-                        config/webpack/webpack.config.js
-                        config/webpack/webpackConfig.js]
+                        config/webpack/generateWebpackConfigs.js]
         config = {
           message: "// The source code including full typescript support is available at:"
         }
         base_files.each { |file| template("#{base_path}/#{file}.tt", file, config) }
+
+        # Handle webpack.config.js separately with smart replacement
+        copy_webpack_main_config(base_path, config)
       end
 
       def copy_packer_config
+        # Skip copying if Shakapacker was just installed (to avoid conflicts)
+        # Check for a temporary marker file that indicates fresh Shakapacker install
+        if File.exist?(".shakapacker_just_installed")
+          puts "Skipping Shakapacker config copy (already installed by Shakapacker installer)"
+          File.delete(".shakapacker_just_installed") # Clean up marker
+          return
+        end
+
         puts "Adding Shakapacker #{ReactOnRails::PackerUtils.shakapacker_version} config"
         base_path = "base/base/"
         config = "config/shakapacker.yml"
@@ -77,39 +96,55 @@ module ReactOnRails
       end
 
       def add_js_dependencies
-        major_minor_patch_only = /\A\d+\.\d+\.\d+\z/
-        if ReactOnRails::VERSION.match?(major_minor_patch_only)
-          package_json.manager.add(["react-on-rails@#{ReactOnRails::VERSION}"])
-        else
-          # otherwise add latest
-          puts "Adding the latest react-on-rails NPM module. Double check this is correct in package.json"
-          package_json.manager.add(["react-on-rails"])
+        add_react_on_rails_package
+        add_react_dependencies
+        add_css_dependencies
+        add_dev_dependencies
+      end
+
+      def install_js_dependencies
+        # Detect which package manager to use
+        success = if File.exist?(File.join(destination_root, "yarn.lock"))
+                    run "yarn install"
+                  elsif File.exist?(File.join(destination_root, "pnpm-lock.yaml"))
+                    run "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
+                    run "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
 
-        puts "Adding React dependencies"
-        package_json.manager.add([
-                                   "react",
-                                   "react-dom",
-                                   "@babel/preset-react",
-                                   "prop-types",
-                                   "babel-plugin-transform-react-remove-prop-types",
-                                   "babel-plugin-macros"
-                                 ])
+        success
+      end
 
-        puts "Adding CSS handlers"
+      def update_gitignore_for_auto_registration
+        gitignore_path = File.join(destination_root, ".gitignore")
+        return unless File.exist?(gitignore_path)
 
-        package_json.manager.add(%w[
-                                   css-loader
-                                   css-minimizer-webpack-plugin
-                                   mini-css-extract-plugin
-                                   style-loader
-                                 ])
+        gitignore_content = File.read(gitignore_path)
+        return if gitignore_content.include?("**/generated/**")
 
-        puts "Adding dev dependencies"
-        package_json.manager.add([
-                                   "@pmmmwh/react-refresh-webpack-plugin",
-                                   "react-refresh"
-                                 ], type: :dev)
+        append_to_file ".gitignore" do
+          <<~GITIGNORE
+
+            # Generated React on Rails packs
+            **/generated/**
+          GITIGNORE
+        end
       end
 
       def append_to_spec_rails_helper
@@ -118,26 +153,70 @@ module ReactOnRails
           add_configure_rspec_to_compile_assets(rails_helper)
         else
           spec_helper = File.join(destination_root, "spec/spec_helper.rb")
-          if File.exist?(spec_helper)
-            add_configure_rspec_to_compile_assets(spec_helper)
-          else
-            # rubocop:disable Layout/EmptyLinesAroundArguments
-            GeneratorMessages.add_info(
-              <<-MSG.strip_heredoc
+          add_configure_rspec_to_compile_assets(spec_helper) if File.exist?(spec_helper)
+        end
+      end
 
-              We did not find a spec/rails_helper.rb or spec/spec_helper.rb to add
-              the React on Rails Test helper, which ensures that if we are running
-              js tests, then we are using latest webpack assets. You can later add
-              this to your rspec config:
+      def add_react_on_rails_package
+        major_minor_patch_only = /\A\d+\.\d+\.\d+\z/
 
-              # This will use the defaults of :js and :server_rendering meta tags
-              ReactOnRails::TestHelper.configure_rspec_to_compile_assets(config)
-              MSG
-            )
-            # rubocop:enable Layout/EmptyLinesAroundArguments
+        # 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
 
-          end
-        end
+        puts "Installing React on Rails package..."
+        return if add_npm_dependencies(react_on_rails_pkg)
+
+        puts "Using direct npm commands as fallback"
+        success = run "npm install #{react_on_rails_pkg.join(' ')}"
+        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
+        ]
+        return if add_npm_dependencies(react_deps)
+
+        success = run "npm install #{react_deps.join(' ')}"
+        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
+        ]
+        return if add_npm_dependencies(css_deps)
+
+        success = run "npm install #{css_deps.join(' ')}"
+        handle_npm_failure("CSS dependencies", css_deps) unless success
+      end
+
+      def add_dev_dependencies
+        puts "Installing development dependencies..."
+        dev_deps = %w[
+          @pmmmwh/react-refresh-webpack-plugin
+          react-refresh
+        ]
+        return if add_npm_dependencies(dev_deps, dev: true)
+
+        success = run "npm install --save-dev #{dev_deps.join(' ')}"
+        handle_npm_failure("development dependencies", dev_deps, dev: true) unless success
       end
 
       CONFIGURE_RSPEC_TO_COMPILE_ASSETS = <<-STR.strip_heredoc
@@ -145,10 +224,137 @@ module ReactOnRails
           # Ensure that if we are running js tests, we are using latest webpack assets
           # This will use the defaults of :js and :server_rendering meta tags
           ReactOnRails::TestHelper.configure_rspec_to_compile_assets(config)
+        end
       STR
 
       private
 
+      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
+
+      def copy_webpack_main_config(base_path, config)
+        webpack_config_path = "config/webpack/webpack.config.js"
+
+        if File.exist?(webpack_config_path)
+          existing_content = File.read(webpack_config_path)
+
+          # Check if it's the standard Shakapacker config that we can safely replace
+          if standard_shakapacker_config?(existing_content)
+            # Remove the file first to avoid conflict prompt, then recreate it
+            remove_file(webpack_config_path, verbose: false)
+            # Show what we're doing
+            puts "   #{set_color('replace', :green)}  #{webpack_config_path} " \
+                 "(auto-upgrading from standard Shakapacker to React on Rails config)"
+            template("#{base_path}/#{webpack_config_path}.tt", webpack_config_path, config)
+          elsif react_on_rails_config?(existing_content)
+            puts "   #{set_color('identical', :blue)}  #{webpack_config_path} " \
+                 "(already React on Rails compatible)"
+            # Skip - don't need to do anything
+          else
+            handle_custom_webpack_config(base_path, config, webpack_config_path)
+          end
+        else
+          # File doesn't exist, create it
+          template("#{base_path}/#{webpack_config_path}.tt", webpack_config_path, config)
+        end
+      end
+
+      def handle_custom_webpack_config(base_path, config, webpack_config_path)
+        # Custom config - ask user
+        puts "\n#{set_color('NOTICE:', :yellow)} Your webpack.config.js appears to be customized."
+        puts "React on Rails needs to replace it with an environment-specific loader."
+        puts "Your current config will be backed up to webpack.config.js.backup"
+
+        if yes?("Replace webpack.config.js with React on Rails version? (Y/n)")
+          # Create backup
+          backup_path = "#{webpack_config_path}.backup"
+          if File.exist?(webpack_config_path)
+            FileUtils.cp(webpack_config_path, backup_path)
+            puts "   #{set_color('create', :green)}  #{backup_path} (backup of your custom config)"
+          end
+
+          template("#{base_path}/#{webpack_config_path}.tt", webpack_config_path, config)
+        else
+          puts "   #{set_color('skip', :yellow)}  #{webpack_config_path}"
+          puts "   #{set_color('WARNING:', :red)} React on Rails may not work correctly " \
+               "without the environment-specific webpack config"
+        end
+      end
+
+      def standard_shakapacker_config?(content)
+        # Get the expected default config based on Shakapacker version
+        expected_configs = shakapacker_default_configs
+
+        # Check if the content matches any of the known default configurations
+        expected_configs.any? { |config| content_matches_template?(content, config) }
+      end
+
+      def content_matches_template?(content, template)
+        # Normalize whitespace and compare
+        normalize_config_content(content) == normalize_config_content(template)
+      end
+
+      def normalize_config_content(content)
+        # Remove comments, normalize whitespace, and clean up for comparison
+        content.gsub(%r{//.*$}, "")                    # Remove single-line comments
+               .gsub(%r{/\*.*?\*/}m, "")               # Remove multi-line comments
+               .gsub(/\s+/, " ")                       # Normalize whitespace
+               .strip
+      end
+
+      def shakapacker_default_configs
+        configs = []
+
+        # Shakapacker v7+ (generateWebpackConfig function)
+        configs << <<~CONFIG
+          // See the shakacode/shakapacker README and docs directory for advice on customizing your webpackConfig.
+          const { generateWebpackConfig } = require('shakapacker')
+
+          const webpackConfig = generateWebpackConfig()
+
+          module.exports = webpackConfig
+        CONFIG
+
+        # Shakapacker v6 (webpackConfig object)
+        configs << <<~CONFIG
+          const { webpackConfig } = require('shakapacker')
+
+          // See the shakacode/shakapacker README and docs directory for advice on customizing your webpackConfig.
+
+          module.exports = webpackConfig
+        CONFIG
+
+        # Also check without comments for variations
+        configs << <<~CONFIG
+          const { generateWebpackConfig } = require('shakapacker')
+          const webpackConfig = generateWebpackConfig()
+          module.exports = webpackConfig
+        CONFIG
+
+        configs << <<~CONFIG
+          const { webpackConfig } = require('shakapacker')
+          module.exports = webpackConfig
+        CONFIG
+
+        configs
+      end
+
+      def react_on_rails_config?(content)
+        # Check if it already has React on Rails environment-specific loading
+        content.include?("envSpecificConfig") || content.include?("env.nodeEnv")
+      end
+
       # From https://github.com/rails/rails/blob/4c940b2dbfb457f67c6250b720f63501d74a45fd/railties/lib/rails/generators/rails/app/app_generator.rb
       def app_name
         @app_name ||= (defined_app_const_base? ? defined_app_name : File.basename(destination_root))

data/lib/generators/react_on_rails/bin/dev

@@ -1,30 +1,46 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-def installed?(process)
-  IO.popen "#{process} -v"
-rescue Errno::ENOENT
-  false
-end
+# ReactOnRails Development Server
+#
+# This script provides a simple interface to the ReactOnRails development
+# server management. The core logic is implemented in ReactOnRails::Dev
+# classes for better maintainability and testing.
+#
+# Each command uses a specific Procfile for process management:
+# - bin/dev (default/hmr): Uses Procfile.dev
+# - bin/dev static: Uses Procfile.dev-static-assets
+# - bin/dev prod: Uses Procfile.dev-prod-assets
+#
+# To customize development environment:
+# 1. Edit the appropriate Procfile to modify which processes run
+# 2. Modify this script for project-specific command-line behavior
+# 3. Extend ReactOnRails::Dev classes in your Rails app for advanced customization
+# 4. Use classes directly: ReactOnRails::Dev::ServerManager.start(:development, "Custom.procfile")
 
-def run(process)
-  system "#{process} start -f Procfile.dev"
-rescue Errno::ENOENT
-  warn <<~MSG
-    ERROR:
-    Please ensure `Procfile.dev` exists in your project!
-  MSG
-  exit!
+begin
+  require "bundler/setup"
+  require "react_on_rails/dev"
+rescue LoadError
+  # Fallback for when gem is not yet installed
+  puts "Loading ReactOnRails development tools..."
+  require_relative "../../lib/react_on_rails/dev"
 end
 
-if installed? "overmind"
-  run "overmind"
-elsif installed? "foreman"
-  run "foreman"
+# Main execution
+case ARGV[0]
+when "production-assets", "prod"
+  ReactOnRails::Dev::ServerManager.start(:production_like)
+when "static"
+  ReactOnRails::Dev::ServerManager.start(:static, "Procfile.dev-static-assets")
+when "kill"
+  ReactOnRails::Dev::ServerManager.kill_processes
+when "help", "--help", "-h"
+  ReactOnRails::Dev::ServerManager.show_help
+when "hmr", nil
+  ReactOnRails::Dev::ServerManager.start(:development, "Procfile.dev")
 else
-  warn <<~MSG
-    NOTICE:
-    For this script to run, you need either 'overmind' or 'foreman' installed on your machine. Please try this script after installing one of them.
-  MSG
-  exit!
+  puts "Unknown argument: #{ARGV[0]}"
+  puts "Run 'bin/dev help' for usage information"
+  exit 1
 end

data/lib/generators/react_on_rails/dev_tests_generator.rb

@@ -7,6 +7,7 @@ module ReactOnRails
   module Generators
     class DevTestsGenerator < Rails::Generators::Base
       include GeneratorHelper
+
       Rails::Generators.hide_namespace(namespace)
       source_root(File.expand_path("templates/dev_tests", __dir__))