react_on_rails 17.0.0.rc.2 → 17.0.0.rc.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5610a42464b29a2f8066e2a91d342838cdd1f3734c3965864e0a5bd0d18e4c8a
-  data.tar.gz: 551fc429af6eea0798b929d0aece8b417b4646dfed702c1dcd39ae26d52084ad
+  metadata.gz: 0630c2730fc7389d31e1f99d88e8df8dc6eb18b670e2909afd25e1e71b0c50ab
+  data.tar.gz: 6db462a802556e23085ae038585dd7c310c7710fd41a0a336d350383e85b9333
 SHA512:
-  metadata.gz: 4b1df35fc94bc088e6a9afe96ca54ec651951149ae82415e55d1db023ef582089fb58f9536db698d0971633678b3d2d70188c0ca355217fd9f6a854ead1f177c
-  data.tar.gz: c1371c43729036f9f9dbb78d68b85be81919a98a16fb8d3d4185b94c0f48c92506404bedb6e1a7a804b52596ae784b4f60487cc4bad8333f0933e38aa005551a
+  metadata.gz: 395e61f25e352b69df2788554dd0fcba85834df3e2f42bd768b6c2a81c8579e2d2504da1a47417abcc8ee5369181260c54f828e206f36dba409cbeef5a5818a9
+  data.tar.gz: 5ee8406c0ce296a4dca6e38299c1274fd2e5b6dde7f62f83f9790122dfc44cf88c0ca2cc093a9da7089265e53ed08ded28a018efc1929828c3a3ced000ba41c4

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.3)
       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/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[
@@ -175,6 +184,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 +300,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.

data/lib/generators/react_on_rails/templates/agent_files/AGENTS.md

@@ -0,0 +1,164 @@
+# AGENTS.md — React on Rails (for AI coding agents working IN this app)
+
+This app uses **React on Rails** to render React components from Rails views, with
+optional server-side rendering (SSR). This file teaches an AI agent the conventions
+it needs to add, register, and render a component correctly on the first try.
+
+It is intentionally short. For the full reference, see the links at the bottom.
+
+> This file describes an app that **uses** React on Rails. It is not the
+> contributor guide for the React on Rails framework itself.
+
+## 1. Adding a component (auto-bundling — the default)
+
+Place a component under any directory named `ror_components`. React on Rails
+auto-bundles it, so **no manual registration is needed**:
+
+```
+app/javascript/src/<Name>/ror_components/<Name>.tsx   # or .jsx
+```
+
+The component file **must `export default`** the React component. Example:
+
+```tsx
+// app/javascript/src/SimpleCounter/ror_components/SimpleCounter.tsx
+import React, { useState } from 'react';
+
+const SimpleCounter = (props: { initialCount?: number }) => {
+  const [count, setCount] = useState(props.initialCount ?? 0);
+  return <button onClick={() => setCount((c) => c + 1)}>Count: {count}</button>;
+};
+
+export default SimpleCounter; // default export is required
+```
+
+### Manual registration (alternative)
+
+If you are not using the `ror_components/` auto-bundling convention, register the
+component explicitly from a pack/entry file, importing from the `react-on-rails`
+npm package:
+
+```ts
+import ReactOnRails from 'react-on-rails';
+import SimpleCounter from './SimpleCounter';
+
+ReactOnRails.register({ SimpleCounter });
+```
+
+The key (`SimpleCounter`) is the name you pass to `react_component` in the Rails view.
+
+## 2. Rendering it from a Rails view
+
+Use the `react_component` view helper in any `.html.erb` view (e.g.
+`app/views/<controller>/<action>.html.erb`). The first argument is the registered
+component name; it must match the file/registration name exactly (case-sensitive).
+
+```erb
+<%= react_component("SimpleCounter", props: { initialCount: 5 }, prerender: true) %>
+```
+
+- `props:` — a Ruby Hash serialized to JSON and passed to the component.
+- `prerender:` — `true` renders the component on the server (SSR) then hydrates on
+  the client; `false` renders only on the client. Set `prerender: false` to isolate
+  SSR issues while debugging.
+
+## 3. `.client` vs `.server` (and plain) bundles — what runs where
+
+When a component name resolves to multiple files, React on Rails picks by suffix:
+
+- `<Name>.client.tsx` — runs in the **browser** only. May use `window`, `document`,
+  browser-only APIs, and client-side hooks/effects.
+- `<Name>.server.tsx` — runs during **server-side rendering** (Node, no DOM). It
+  **must not** use browser-only globals (`window`, `document`, `localStorage`).
+  Often it just re-exports the client component for SSR.
+- `<Name>.tsx` (plain, no suffix) — used for **both** server and client. Keep it
+  isomorphic: guard any browser-only code with `if (typeof window !== 'undefined')`.
+
+Rule of thumb: if `prerender: true`, the code path must run in Node without a DOM.
+
+## 4. The `ReactOnRails` JS API you will actually touch
+
+Import from the `react-on-rails` npm package:
+
+```ts
+import ReactOnRails from 'react-on-rails';
+```
+
+- `ReactOnRails.register({ Name })` — register one or more components by name.
+- `ReactOnRails.registerStore({ name })` / `ReactOnRails.getStore(name)` — register
+  and retrieve a Redux store (only if this app uses Redux).
+- `ReactOnRails.reactOnRailsPageLoaded()` — rarely needed; React on Rails wires
+  client hydration automatically.
+
+You usually only need `register` (and only when not using `ror_components/`).
+
+## 5. Top errors and fixes
+
+These messages come straight from React on Rails' runtime errors. When you hit one,
+apply the matching fix.
+
+### `Component '<Name>' Not Registered`
+
+The component name in the view does not match a registered/auto-bundled component.
+
+- Recommended (auto-bundling): put the component file directly inside a
+  `ror_components/` directory, e.g.
+  `app/javascript/src/<Name>/ror_components/<Name>.client.tsx`, with a `default`
+  export, then regenerate packs: `bin/rails react_on_rails:generate_packs`.
+- Or register manually: `ReactOnRails.register({ <Name>: <Name> });` and
+  `import <Name> from './components/<Name>';`.
+- Check the name matches the `react_component("<Name>", ...)` call exactly (case-sensitive).
+
+### `Auto-loaded Bundle Missing`
+
+The component is set up for auto-loading but its bundle is missing.
+
+1. Run the pack generation task: `bin/rails react_on_rails:generate_packs`.
+2. Ensure the component is in the correct directory under `app/javascript`.
+3. Check naming conventions: file is `<Name>.jsx` or `<Name>.tsx` and `export default`s.
+4. Verify nested entries are enabled in your Shakapacker/webpack config.
+
+### `Hydration Mismatch`
+
+Server-rendered HTML doesn't match what React rendered on the client.
+
+1. **Random IDs or timestamps**: use props or deterministic values, not
+   `Math.random()` / `Date.now()`.
+2. **Browser-only APIs**: guard with `if (typeof window !== 'undefined') { ... }`.
+3. **Different data**: ensure props/`railsContext`/store init are identical on
+   server and client.
+4. Temporarily set `prerender: false` to isolate the issue.
+
+### `Server Rendering Failed`
+
+An error occurred while server-rendering a component.
+
+1. Check JS console output in the Rails log: `tail -f log/development.log | grep 'React on Rails'`.
+2. Common causes: missing Node dependencies, syntax errors, or browser-only APIs in
+   server code.
+3. Set `config.trace = true` and check `config.server_bundle_js_file` points at the
+   correct file.
+
+### `Redux Store Not Found`
+
+A Redux store wasn't registered before a component that depends on it rendered.
+
+1. Register the store: `ReactOnRails.registerStore({ <store> });`.
+2. Initialize it in the view before the component: `<%= redux_store('<store>', props: {}) %>`.
+3. Declare the dependency: `store_dependencies: ['<store>']`.
+
+## 6. Diagnose your setup
+
+Before guessing, run the doctor — it checks configuration, bundles, and dependencies:
+
+```bash
+bin/rails react_on_rails:doctor
+```
+
+## 7. Where the full reference lives
+
+- Hosted docs: https://reactonrails.com/docs/
+- Getting-started tutorial: https://reactonrails.com/docs/getting-started/tutorial/
+- Machine-readable route map / expanded reference (for agents):
+  https://github.com/shakacode/react_on_rails/blob/main/llms.txt and
+  https://github.com/shakacode/react_on_rails/blob/main/llms-full.txt

data/lib/generators/react_on_rails/templates/agent_files/CLAUDE.md

@@ -0,0 +1,8 @@
+# CLAUDE.md
+
+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](./AGENTS.md)**.
+
+Follow any project-specific instructions elsewhere in this file or repository.