react_on_rails 17.0.0.rc.2 → 17.0.0.rc.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5610a42464b29a2f8066e2a91d342838cdd1f3734c3965864e0a5bd0d18e4c8a
-  data.tar.gz: 551fc429af6eea0798b929d0aece8b417b4646dfed702c1dcd39ae26d52084ad
+  metadata.gz: 1a437fef821bdc1e6bd3b289e1b627bafc9a5c5850dc1f830c15d683dc1593e2
+  data.tar.gz: 4a5679fea3c1f2b24dbbf7b6325690e0e95222b03452c9e6cca211fdf149e83d
 SHA512:
-  metadata.gz: 4b1df35fc94bc088e6a9afe96ca54ec651951149ae82415e55d1db023ef582089fb58f9536db698d0971633678b3d2d70188c0ca355217fd9f6a854ead1f177c
-  data.tar.gz: c1371c43729036f9f9dbb78d68b85be81919a98a16fb8d3d4185b94c0f48c92506404bedb6e1a7a804b52596ae784b4f60487cc4bad8333f0933e38aa005551a
+  metadata.gz: 5c905725d516131bbc94c8103953d0522a62611428c692d414b0f029299d29641f4239d4e88c054bb29aa3dfd6091133dc7c360912ba84ee5fc060540c5d26e3
+  data.tar.gz: 3b0af40fdd4fe98d75ec7fa198fd44bdafcc6f529364624e8bf42669e55d01833142698249c3d41b6587b4e65d2fbac69d96105c65667d36c58f117375529998

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    react_on_rails (17.0.0.rc.2)
+    react_on_rails (17.0.0.rc.4)
       addressable
       connection_pool
       execjs (~> 2.5)

data/lib/generators/USAGE

@@ -8,6 +8,12 @@ The react_on_rails:install generator integrates a React frontend, including SSR,
     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
+    the PostCSS plugin for Webpack or Rspack, and styles the generated
+    server-rendered Hello World example.
+
 *******************************************************************************
 
 After running the generator, you will want to:

data/lib/generators/react_on_rails/base_generator.rb

@@ -41,6 +41,12 @@ module ReactOnRails
                    type: :boolean,
                    desc: "Use Webpack as the bundler (alias for --no-rspack; --no-webpack is equivalent to --rspack)"
 
+      # --tailwind
+      class_option :tailwind,
+                   type: :boolean,
+                   default: false,
+                   desc: "Install Tailwind CSS v4 and style the generated SSR example"
+
       # --pro
       class_option :pro,
                    type: :boolean,
@@ -106,6 +112,10 @@ module ReactOnRails
           generator.__send__(:use_rsc?)
         end
 
+        def use_tailwind?
+          generator.__send__(:use_tailwind?)
+        end
+
         def shakapacker_version_9_or_higher?
           generator.__send__(:shakapacker_version_9_or_higher?)
         end
@@ -228,7 +238,7 @@ module ReactOnRails
         base_files = %w[app/javascript/packs/server-bundle.js]
 
         # Skip HelloWorld CSS for Redux (uses HelloWorldApp) or RSC (uses HelloServer)
-        unless options.redux? || use_rsc?
+        unless options.redux? || use_rsc? || use_tailwind?
           base_files << "app/javascript/src/HelloWorld/ror_components/HelloWorld.module.css"
         end
 
@@ -259,6 +269,14 @@ module ReactOnRails
         copy_webpack_main_config(base_path, config)
       end
 
+      def copy_tailwind_files
+        return unless use_tailwind?
+
+        base_path = "base/tailwind/"
+        copy_file("#{base_path}app/javascript/stylesheets/application.css",
+                  "app/javascript/stylesheets/application.css")
+      end
+
       def copy_packer_config
         base_path = "base/base/"
         config = "config/shakapacker.yml"
@@ -970,7 +988,7 @@ module ReactOnRails
           # Note: files originally generated with --pro or --rsc will not match when the
           # current run omits those options; in that case, we preserve the directory.
           # Templates rely on config[:message] plus a small helper subset exposed by
-          # TemplateRenderContext (add_documentation_reference, use_pro?, use_rsc?,
+          # TemplateRenderContext (add_documentation_reference, use_pro?, use_rsc?, use_tailwind?,
           # shakapacker_version_9_or_higher?, rsc_plugin_class_name, rsc_plugin_import_path).
           # Missing method delegates raise NoMethodError and are caught below, treating the
           # file as non-removable.

data/lib/generators/react_on_rails/dev_tests_generator.rb

@@ -8,6 +8,16 @@ module ReactOnRails
     class DevTestsGenerator < Rails::Generators::Base
       include GeneratorHelper
 
+      ESLINT_DEV_DEPENDENCIES = {
+        "@eslint/js" => "^9.0.0",
+        "eslint" => "^9.0.0",
+        "eslint-config-prettier" => "^10.0.0",
+        "eslint-plugin-import" => "^2.29.0",
+        "eslint-plugin-react" => "^7.37.5",
+        "eslint-plugin-react-hooks" => "^6.1.1",
+        "globals" => "^16.0.0"
+      }.freeze
+
       Rails::Generators.hide_namespace(namespace)
       source_root(File.expand_path("templates/dev_tests", __dir__))
 
@@ -24,7 +34,7 @@ module ReactOnRails
                    desc: "Include React Server Components test (hello_server_spec.rb)"
 
       def copy_rspec_files
-        %w[.eslintrc
+        %w[eslint.config.mjs
            spec/spec_helper.rb
            spec/rails_helper.rb
            spec/simplecov_helper.rb
@@ -69,6 +79,15 @@ module ReactOnRails
 
         File.open(package_json, "w+") { |f| f.puts JSON.pretty_generate(contents) }
       end
+
+      def add_internal_eslint_dev_dependencies
+        package_json = File.join(destination_root, "package.json")
+        contents = JSON.parse(File.read(package_json))
+        contents["devDependencies"] ||= {}
+        contents["devDependencies"].merge!(ESLINT_DEV_DEPENDENCIES)
+
+        File.open(package_json, "w+") { |f| f.puts JSON.pretty_generate(contents) }
+      end
     end
   end
 end

data/lib/generators/react_on_rails/generator_helper.rb

@@ -121,6 +121,13 @@ module GeneratorHelper
     options[:rsc]
   end
 
+  # Check if Tailwind CSS should be installed and wired into the generated example.
+  #
+  # @return [Boolean] true if --tailwind is set
+  def use_tailwind?
+    options[:tailwind]
+  end
+
   # Determine if the project is using rspack as the bundler.
   #
   # Detection priority:

data/lib/generators/react_on_rails/install_generator.rb

@@ -43,6 +43,12 @@ module ReactOnRails
                    desc: "Generate TypeScript files and install TypeScript dependencies. Default: false",
                    aliases: "-T"
 
+      # --tailwind
+      class_option :tailwind,
+                   type: :boolean,
+                   default: false,
+                   desc: "Install Tailwind CSS v4 and style the generated SSR example. Default: false"
+
       # --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
       # only includes :rspack in the options hash when the flag is explicitly passed, which is how
@@ -66,6 +72,15 @@ module ReactOnRails
                    default: false,
                    desc: "Skip warnings. Default: false"
 
+      # --agent-files / --no-agent-files
+      # Emits consumer-scoped AI-agent guidance (AGENTS.md) plus thin editor pointer
+      # files (CLAUDE.md, .cursor/rules/react-on-rails.mdc, .github/copilot-instructions.md).
+      # Default ON; pass --no-agent-files to skip. Existing files are never overwritten.
+      class_option :agent_files,
+                   type: :boolean,
+                   default: true,
+                   desc: "Write AI-agent guidance files (AGENTS.md + editor pointers). Default: true"
+
       # --pro
       class_option :pro,
                    type: :boolean,
@@ -183,6 +198,7 @@ module ReactOnRails
           add_package_json_scripts
           add_ci_workflow
           add_bin_scripts
+          add_agent_files
           add_post_install_message
         else
           error = <<~MSG.strip
@@ -227,7 +243,7 @@ module ReactOnRails
         # --pretend/--force/--skip must be forwarded explicitly at each boundary.
         invoke "react_on_rails:base", [],
                { typescript: options.typescript?, redux: options.redux?, rspack: using_rspack?,
-                 pro: use_pro?, rsc: use_rsc?, new_app: options.new_app?,
+                 pro: use_pro?, rsc: use_rsc?, tailwind: use_tailwind?, new_app: options.new_app?,
                  shakapacker_just_installed: shakapacker_just_installed?,
                  force: options[:force], skip: options[:skip], pretend: options[:pretend] }
 
@@ -237,6 +253,7 @@ module ReactOnRails
         # - Without --rsc: Normal behavior (HelloWorld or HelloWorldApp based on --redux)
         if options.redux?
           invoke "react_on_rails:react_with_redux", [], { typescript: options.typescript?,
+                                                          tailwind: use_tailwind?,
                                                           invoked_by_install: true,
                                                           new_app: options.new_app?,
                                                           rsc: use_rsc?,
@@ -246,6 +263,7 @@ module ReactOnRails
           # Only generate HelloWorld if RSC is not enabled
           # For RSC, HelloServer replaces HelloWorld as the example component
           invoke "react_on_rails:react_no_redux", [], { typescript: options.typescript?,
+                                                        tailwind: use_tailwind?,
                                                         new_app: options.new_app?,
                                                         force: options[:force], skip: options[:skip],
                                                         pretend: options[:pretend] }
@@ -265,6 +283,7 @@ module ReactOnRails
 
         invoke "react_on_rails:rsc", [], { typescript: options.typescript?, invoked_by_install: true,
                                            new_app: options.new_app?, redux: options.redux?,
+                                           tailwind: use_tailwind?,
                                            force: options[:force], skip: options[:skip],
                                            pretend: options[:pretend] }
       end
@@ -622,6 +641,40 @@ module ReactOnRails
         File.chmod(0o755, *files_to_become_executable)
       end
 
+      # Consumer-scoped AI-agent guidance written into the generated app. The canonical
+      # AGENTS.md content lives in templates/agent_files/ and is the single source of truth;
+      # create-react-on-rails-app gets it for free because it delegates to this generator.
+      # Each file is copied only when absent so we never clobber an app's existing agent files.
+      AGENT_FILES = %w[
+        AGENTS.md
+        CLAUDE.md
+        .cursor/rules/react-on-rails.mdc
+        .github/copilot-instructions.md
+      ].freeze
+      private_constant :AGENT_FILES
+
+      def add_agent_files
+        return unless options.agent_files?
+
+        # AGENTS.md is the canonical file the editor pointers (CLAUDE.md, Cursor, Copilot) all
+        # reference. If the app already has its own AGENTS.md, it may document unrelated
+        # conventions, so leave it untouched AND skip the pointer files rather than emit editor
+        # guidance pointing at an AGENTS.md we did not write.
+        if File.exist?(File.join(destination_root, "AGENTS.md"))
+          say_status :skip, "AGENTS.md already exists; leaving it and the editor pointer files untouched", :yellow
+          return
+        end
+
+        AGENT_FILES.each do |relative_path|
+          if File.exist?(File.join(destination_root, relative_path))
+            say_status :skip, "#{relative_path} already exists; leaving it untouched", :yellow
+            next
+          end
+
+          copy_file("templates/agent_files/#{relative_path}", relative_path)
+        end
+      end
+
       def replace_stock_rails_bin_dev!
         @preserve_existing_bin_dev = false
 
@@ -722,6 +775,10 @@ module ReactOnRails
           flags << "--pro"
         end
 
+        # Preserve an explicit agent-files opt-out so the suggested re-run doesn't emit
+        # AGENTS.md/editor files a user deliberately skipped (--agent-files defaults to on).
+        flags << "--no-agent-files" unless options.agent_files?
+
         ["rails generate react_on_rails:install", *flags].join(" ")
       end
 

data/lib/generators/react_on_rails/js_dependency_manager.rb

@@ -83,6 +83,15 @@ module ReactOnRails
         style-loader@^4.0.0
       ].freeze
 
+      # Tailwind v4 CSS-first setup. The patch-level floors match published
+      # releases verified with the generator's SSR smoke app.
+      TAILWIND_DEPENDENCIES = %w[
+        tailwindcss@^4.3.0
+        @tailwindcss/postcss@^4.3.0
+        postcss@^8.5.15
+        postcss-loader@^8.2.1
+      ].freeze
+
       # Development-only dependencies for hot reloading (Webpack)
       # Both packages are pre-1.0, so left bare (see pinning note above).
       DEV_DEPENDENCIES = %w[
@@ -103,6 +112,7 @@ module ReactOnRails
       # @rspack/cli uses ^2.0.0-0 to match @rspack/core's prerelease range.
       RSPACK_DEV_DEPENDENCIES = %w[
         @rspack/cli@^2.0.0-0
+        @rspack/dev-server@^2.0.0
         @rspack/plugin-react-refresh@^2.0.0
         react-refresh
       ].freeze
@@ -175,6 +185,7 @@ module ReactOnRails
         add_react_on_rails_package unless using_pro
         add_react_dependencies
         add_css_dependencies
+        add_tailwind_dependencies_if_requested
         add_rspack_dependencies if using_rspack?
         add_transpiler_dependencies
         add_pro_dependencies if using_pro
@@ -290,6 +301,32 @@ module ReactOnRails
         MSG
       end
 
+      def add_tailwind_dependencies
+        say "Installing Tailwind CSS v4 dependencies..."
+        return if add_packages(TAILWIND_DEPENDENCIES)
+
+        GeneratorMessages.add_warning(<<~MSG.strip)
+          ⚠️  Failed to add Tailwind CSS dependencies.
+
+          You can install them manually by running:
+            #{manual_add_packages_command(TAILWIND_DEPENDENCIES)}
+        MSG
+      rescue StandardError => e
+        GeneratorMessages.add_warning(<<~MSG.strip)
+          ⚠️  Error adding Tailwind CSS dependencies: #{e.message}
+
+          You can install them manually by running:
+            #{manual_add_packages_command(TAILWIND_DEPENDENCIES)}
+        MSG
+      end
+
+      def add_tailwind_dependencies_if_requested
+        # use_tailwind? is provided by GeneratorHelper, included alongside this module.
+        return unless use_tailwind?
+
+        add_tailwind_dependencies
+      end
+
       def add_rspack_dependencies
         say "Installing Rspack core dependencies..."
         return if add_packages(RSPACK_DEPENDENCIES)

data/lib/generators/react_on_rails/react_no_redux_generator.rb

@@ -18,6 +18,11 @@ module ReactOnRails
                    default: false,
                    desc: "Generate TypeScript files"
 
+      class_option :tailwind,
+                   type: :boolean,
+                   default: false,
+                   desc: "Style the generated HelloWorld example with Tailwind CSS v4"
+
       class_option :new_app,
                    type: :boolean,
                    default: false,
@@ -25,17 +30,24 @@ module ReactOnRails
 
       def copy_base_files
         base_js_path = "base/base"
+        tailwind_js_path = "base/tailwind"
+        ext = component_extension(options)
 
         # Determine which component files to copy based on TypeScript option
-        component_files = [
-          "app/javascript/src/HelloWorld/ror_components/HelloWorld.client.#{component_extension(options)}",
-          "app/javascript/src/HelloWorld/ror_components/HelloWorld.server.#{component_extension(options)}",
-          "app/javascript/src/HelloWorld/ror_components/HelloWorld.module.css"
-        ]
-
-        component_files.each do |file|
-          copy_file("#{base_js_path}/#{file}", file)
+        client_component =
+          "app/javascript/src/HelloWorld/ror_components/HelloWorld.client.#{ext}"
+        server_component =
+          "app/javascript/src/HelloWorld/ror_components/HelloWorld.server.#{ext}"
+
+        if use_tailwind?
+          copy_file("#{tailwind_js_path}/#{client_component}", client_component)
+        else
+          copy_file("#{base_js_path}/#{client_component}", client_component)
+          copy_file("#{base_js_path}/app/javascript/src/HelloWorld/ror_components/HelloWorld.module.css",
+                    "app/javascript/src/HelloWorld/ror_components/HelloWorld.module.css")
         end
+
+        copy_file("#{base_js_path}/#{server_component}", server_component)
       end
 
       def create_appropriate_templates

data/lib/generators/react_on_rails/react_with_redux_generator.rb

@@ -35,6 +35,11 @@ module ReactOnRails
                    default: false,
                    hide: true
 
+      class_option :tailwind,
+                   type: :boolean,
+                   default: false,
+                   hide: true
+
       def create_redux_directories
         # Create auto-bundling directory structure for Redux
         empty_directory("app/javascript/src/HelloWorldApp/ror_components")
@@ -53,18 +58,33 @@ module ReactOnRails
                   "app/javascript/src/HelloWorldApp/ror_components/HelloWorldApp.client.#{ext}")
         copy_file("#{base_js_path}/app/javascript/bundles/HelloWorld/startup/HelloWorldApp.server.#{ext}",
                   "app/javascript/src/HelloWorldApp/ror_components/HelloWorldApp.server.#{ext}")
-        copy_file("#{base_js_path}/app/javascript/bundles/HelloWorld/components/HelloWorld.module.css",
-                  "app/javascript/src/HelloWorldApp/components/HelloWorld.module.css")
+
+        unless use_tailwind?
+          copy_file("#{base_js_path}/app/javascript/bundles/HelloWorld/components/HelloWorld.module.css",
+                    "app/javascript/src/HelloWorldApp/components/HelloWorld.module.css")
+        end
 
         # Update import paths in client component
         ror_client_file = "app/javascript/src/HelloWorldApp/ror_components/HelloWorldApp.client.#{ext}"
         gsub_file(ror_client_file, "../store/helloWorldStore", "../store/helloWorldStore")
         gsub_file(ror_client_file, "../containers/HelloWorldContainer",
                   "../containers/HelloWorldContainer")
+        return unless use_tailwind?
+
+        stylesheet_import = "import '../../../stylesheets/application.css';\n"
+        ror_client_file_path = File.join(destination_root, ror_client_file)
+        if options[:pretend]
+          say_status :pretend, "Would add Tailwind stylesheet import to #{ror_client_file}", :yellow
+          return
+        end
+        return if File.read(ror_client_file_path).include?(stylesheet_import)
+
+        prepend_to_file(ror_client_file, stylesheet_import)
       end
 
       def copy_base_redux_files
         base_hello_world_path = "redux/base/app/javascript/bundles/HelloWorld"
+        tailwind_hello_world_path = "redux/tailwind/app/javascript/bundles/HelloWorld"
         redux_extension = options.typescript? ? "ts" : "js"
 
         # Copy Redux infrastructure files with appropriate extension
@@ -72,11 +92,15 @@ module ReactOnRails
            containers/HelloWorldContainer.#{redux_extension}
            constants/helloWorldConstants.#{redux_extension}
            reducers/helloWorldReducer.#{redux_extension}
-           store/helloWorldStore.#{redux_extension}
-           components/HelloWorld.#{component_extension(options)}].each do |file|
+           store/helloWorldStore.#{redux_extension}].each do |file|
              copy_file("#{base_hello_world_path}/#{file}",
                        "app/javascript/src/HelloWorldApp/#{file}")
            end
+
+        component_file = "components/HelloWorld.#{component_extension(options)}"
+        component_source_path = use_tailwind? ? tailwind_hello_world_path : base_hello_world_path
+        copy_file("#{component_source_path}/#{component_file}",
+                  "app/javascript/src/HelloWorldApp/#{component_file}")
       end
 
       def create_appropriate_templates

data/lib/generators/react_on_rails/rsc_generator.rb

@@ -42,6 +42,11 @@ module ReactOnRails
                    default: false,
                    hide: true
 
+      class_option :tailwind,
+                   type: :boolean,
+                   default: false,
+                   hide: true
+
       def run_generator
         # When invoked by install_generator, skip prerequisites (parent already validated)
         if options[:invoked_by_install] || prerequisites_met?

data/lib/generators/react_on_rails/rsc_setup.rb

@@ -206,7 +206,13 @@ module ReactOnRails
         # Check if HelloServer already exists (check both jsx and tsx)
         if File.exist?(File.join(destination_root, "#{ror_components_dir}/HelloServer.jsx")) ||
            File.exist?(File.join(destination_root, "#{ror_components_dir}/HelloServer.tsx"))
-          say "ℹ️  HelloServer component already exists, skipping", :yellow
+          tailwind_import_added = add_tailwind_import_to_rsc_client_component(components_dir)
+          message = if tailwind_import_added
+                      "ℹ️  HelloServer component already exists; added Tailwind stylesheet import to LikeButton"
+                    else
+                      "ℹ️  HelloServer component already exists, skipping"
+                    end
+          say message, :yellow
           return
         end
 
@@ -223,10 +229,38 @@ module ReactOnRails
                   "#{components_dir}/HelloServer.#{ext}")
         copy_file("templates/rsc/base/app/javascript/src/HelloServer/components/LikeButton.#{ext}",
                   "#{components_dir}/LikeButton.#{ext}")
+        add_tailwind_import_to_rsc_client_component(components_dir)
 
         say "✅ Created HelloServer component", :green
       end
 
+      def add_tailwind_import_to_rsc_client_component(components_dir)
+        return false unless use_tailwind?
+
+        candidate_entry_paths = %w[jsx tsx].map do |extension|
+          "#{components_dir}/LikeButton.#{extension}"
+        end
+
+        relative_entry_path = candidate_entry_paths.find do |entry_path|
+          File.exist?(File.join(destination_root, entry_path))
+        end
+        return false unless relative_entry_path
+
+        # Path is relative to app/javascript/src/HelloServer/components/.
+        stylesheet_import = "import '../../../stylesheets/application.css';"
+        entry_path = File.join(destination_root, relative_entry_path)
+        entry_content = File.read(entry_path)
+        return false if entry_content.include?(stylesheet_import)
+
+        client_directive_pattern = /\A\s*['"]use client['"];?[^\S\r\n]*(?:\r?\n|$)/
+        if entry_content.match?(client_directive_pattern)
+          insert_into_file(relative_entry_path, "#{stylesheet_import}\n", after: client_directive_pattern)
+        else
+          prepend_to_file(relative_entry_path, "#{stylesheet_import}\n")
+        end
+        true
+      end
+
       def create_hello_server_controller
         controller_path = "app/controllers/hello_server_controller.rb"
 

data/lib/generators/react_on_rails/templates/agent_files/.cursor/rules/react-on-rails.mdc

@@ -0,0 +1,11 @@
+---
+description: React on Rails conventions for this app (components, react_component helper, SSR bundles, errors)
+globs:
+alwaysApply: true
+---
+
+This app uses **React on Rails**. For React on Rails conventions — adding and
+registering components, the `react_component` view helper, `.client`/`.server`
+bundle rules, the `ReactOnRails` JS API, common errors and fixes, and the
+`bin/rails react_on_rails:doctor` diagnostic — read **AGENTS.md** in the project
+root.

data/lib/generators/react_on_rails/templates/agent_files/.github/copilot-instructions.md

@@ -0,0 +1,7 @@
+# GitHub Copilot instructions
+
+This app uses **React on Rails**. For React on Rails conventions — adding and
+registering components, the `react_component` view helper, `.client`/`.server`
+bundle rules, the `ReactOnRails` JS API, common errors and fixes, and the
+`bin/rails react_on_rails:doctor` diagnostic — read **AGENTS.md** in the project
+root.