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

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

@@ -0,0 +1,165 @@
+# 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,
+  https://github.com/shakacode/react_on_rails/blob/main/llms-full.txt (OSS), and
+  https://github.com/shakacode/react_on_rails/blob/main/llms-full-pro.txt (Pro)

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.

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

@@ -16,7 +16,12 @@ class BundlerSwitcher
 
   RSPACK_DEPS = {
     dependencies: %w[@rspack/core@^2.0.0-0 rspack-manifest-plugin@^5.0.0],
-    dev_dependencies: %w[@rspack/cli@^2.0.0-0 @rspack/plugin-react-refresh@^2.0.0]
+    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
 
   def initialize(target_bundler)

data/lib/generators/react_on_rails/templates/base/base/config/webpack/commonWebpackConfig.js.tt

@@ -11,7 +11,87 @@ const commonOptions = {
   },
 };
 
+<% if use_tailwind? -%>
+const tailwindPostcssPlugin = require('@tailwindcss/postcss');
+
+const tailwindPostcssLoader = {
+  loader: 'postcss-loader',
+  options: {
+    postcssOptions: {
+      plugins: [tailwindPostcssPlugin],
+    },
+  },
+};
+
+const loaderName = (loader) => {
+  if (typeof loader === 'string') return loader;
+  if (loader && typeof loader.loader === 'string') return loader.loader;
+  return '';
+};
+
+const postcssLoaderUsesTailwind = (loader) => {
+  const plugins = loader?.options?.postcssOptions?.plugins || [];
+  const tailwindPluginName = tailwindPostcssPlugin.postcssPlugin || tailwindPostcssPlugin.name;
+
+  return plugins.some((plugin) => {
+    if (plugin === tailwindPostcssPlugin) return true;
+    if (!tailwindPluginName) return false;
+
+    return plugin?.postcssPlugin === tailwindPluginName || plugin?.name === tailwindPluginName;
+  });
+};
+
+const mergeTailwindPostcssLoader = (loader) => {
+  if (typeof loader === 'string') return tailwindPostcssLoader;
+  if (postcssLoaderUsesTailwind(loader)) return loader;
+
+  const existingOptions = loader.options || {};
+  const existingPostcssOptions = existingOptions.postcssOptions || {};
+  const existingPlugins = existingPostcssOptions.plugins || [];
+
+  return {
+    ...loader,
+    options: {
+      ...existingOptions,
+      postcssOptions: {
+        ...existingPostcssOptions,
+        plugins: [...existingPlugins, tailwindPostcssPlugin],
+      },
+    },
+  };
+};
+
+const addTailwindPostcssLoader = (webpackConfig) => {
+  const rules = webpackConfig.module?.rules;
+  if (!Array.isArray(rules)) return webpackConfig;
+
+  rules.forEach((rule) => {
+    if (!Array.isArray(rule.use)) return;
+
+    const postcssLoaderIndex = rule.use.findIndex((loader) => loaderName(loader).includes('postcss-loader'));
+    if (postcssLoaderIndex !== -1) {
+      rule.use[postcssLoaderIndex] = mergeTailwindPostcssLoader(rule.use[postcssLoaderIndex]);
+      return;
+    }
+
+    const cssLoaderIndex = rule.use.findIndex((loader) => loaderName(loader).includes('css-loader'));
+    if (cssLoaderIndex === -1) return;
+
+    rule.use.splice(cssLoaderIndex + 1, 0, tailwindPostcssLoader);
+  });
+
+  return webpackConfig;
+};
+
+<% end -%>
 // Copy the object using merge b/c the baseClientWebpackConfig and commonOptions are mutable globals
-const commonWebpackConfig = () => merge({}, baseClientWebpackConfig, commonOptions);
+const commonWebpackConfig = () => {
+  const webpackConfig = merge({}, baseClientWebpackConfig, commonOptions);
+<% if use_tailwind? -%>
+  return addTailwindPostcssLoader(webpackConfig);
+<% else -%>
+  return webpackConfig;
+<% end -%>
+};
 
 module.exports = commonWebpackConfig;

data/lib/generators/react_on_rails/templates/base/base/config/webpack/development.js.tt

@@ -10,8 +10,8 @@ const developmentEnvOnly = (clientWebpackConfig, _serverWebpackConfig) => {
     // eslint-disable-next-line global-require
     if (config.assets_bundler === 'rspack') {
       // Rspack uses @rspack/plugin-react-refresh for React Fast Refresh
-      const ReactRefreshPlugin = require('@rspack/plugin-react-refresh');
-      clientWebpackConfig.plugins.push(new ReactRefreshPlugin());
+      const { ReactRefreshRspackPlugin } = require('@rspack/plugin-react-refresh');
+      clientWebpackConfig.plugins.push(new ReactRefreshRspackPlugin());
     } else {
       // Webpack uses @pmmmwh/react-refresh-webpack-plugin
       const ReactRefreshWebpackPlugin = require('@pmmmwh/react-refresh-webpack-plugin');

data/lib/generators/react_on_rails/templates/base/tailwind/app/javascript/src/HelloWorld/ror_components/HelloWorld.client.jsx

@@ -0,0 +1,30 @@
+import React, { useState } from 'react';
+import '../../../stylesheets/application.css';
+
+const HelloWorld = (props) => {
+  const [name, setName] = useState(props.name);
+
+  return (
+    <section className="mx-auto max-w-xl rounded-lg border border-slate-200 bg-white p-6 text-slate-900 shadow-sm">
+      <p className="text-sm font-semibold uppercase text-sky-600">React on Rails + Tailwind CSS</p>
+      <h3 className="mt-2 text-2xl font-bold">Hello, {name}!</h3>
+      <p className="mt-3 text-sm leading-6 text-slate-600">
+        This component is server-rendered by Rails and styled by Tailwind CSS v4.
+      </p>
+      <form className="mt-5">
+        <label className="block text-sm font-medium text-slate-700" htmlFor="name">
+          Say hello to:
+          <input
+            id="name"
+            className="mt-2 w-full rounded-md border border-slate-300 px-3 py-2 shadow-sm focus:border-sky-500 focus:outline-hidden focus:ring-2 focus:ring-sky-200"
+            type="text"
+            value={name}
+            onChange={(e) => setName(e.target.value)}
+          />
+        </label>
+      </form>
+    </section>
+  );
+};
+
+export default HelloWorld;

data/lib/generators/react_on_rails/templates/base/tailwind/app/javascript/src/HelloWorld/ror_components/HelloWorld.client.tsx

@@ -0,0 +1,34 @@
+import React, { useState } from 'react';
+import '../../../stylesheets/application.css';
+
+interface HelloWorldProps {
+  name: string;
+}
+
+const HelloWorld: React.FC<HelloWorldProps> = (props) => {
+  const [name, setName] = useState(props.name);
+
+  return (
+    <section className="mx-auto max-w-xl rounded-lg border border-slate-200 bg-white p-6 text-slate-900 shadow-sm">
+      <p className="text-sm font-semibold uppercase text-sky-600">React on Rails + Tailwind CSS</p>
+      <h3 className="mt-2 text-2xl font-bold">Hello, {name}!</h3>
+      <p className="mt-3 text-sm leading-6 text-slate-600">
+        This component is server-rendered by Rails and styled by Tailwind CSS v4.
+      </p>
+      <form className="mt-5">
+        <label className="block text-sm font-medium text-slate-700" htmlFor="name">
+          Say hello to:
+          <input
+            id="name"
+            className="mt-2 w-full rounded-md border border-slate-300 px-3 py-2 shadow-sm focus:border-sky-500 focus:outline-hidden focus:ring-2 focus:ring-sky-200"
+            type="text"
+            value={name}
+            onChange={(e) => setName(e.target.value)}
+          />
+        </label>
+      </form>
+    </section>
+  );
+};
+
+export default HelloWorld;

data/lib/generators/react_on_rails/templates/base/tailwind/app/javascript/stylesheets/application.css

@@ -0,0 +1 @@
+@import "tailwindcss";

data/lib/generators/react_on_rails/templates/dev_tests/eslint.config.mjs

@@ -0,0 +1,50 @@
+import js from '@eslint/js';
+import prettier from 'eslint-config-prettier';
+import importPlugin from 'eslint-plugin-import';
+import react from 'eslint-plugin-react';
+import reactHooks from 'eslint-plugin-react-hooks';
+import globals from 'globals';
+
+const reactHooksRecommendedLatest = reactHooks.configs['recommended-latest'];
+const reactHooksRecommendedLatestConfigs = Array.isArray(reactHooksRecommendedLatest)
+  ? reactHooksRecommendedLatest
+  : [reactHooksRecommendedLatest];
+
+export default [
+  js.configs.recommended,
+  react.configs.flat.recommended,
+  importPlugin.flatConfigs.recommended,
+  ...reactHooksRecommendedLatestConfigs,
+  {
+    files: ['**/*.{js,jsx,mjs,cjs}'],
+    languageOptions: {
+      ecmaVersion: 'latest',
+      sourceType: 'module',
+      globals: {
+        ...globals.browser,
+        ...globals.node,
+        ...globals.mocha,
+        __DEBUG_SERVER_ERRORS__: true,
+        __SERVER_ERRORS__: true,
+      },
+    },
+    settings: {
+      react: {
+        version: 'detect',
+      },
+    },
+    rules: {
+      'no-console': 'off',
+
+      // https://github.com/import-js/eslint-plugin-import/issues/340
+      'import/no-extraneous-dependencies': 'off',
+
+      // The internal generated examples use local workspace packages during tests.
+      'import/no-unresolved': 'off',
+
+      'react/prop-types': 'off',
+      semi: 'off',
+    },
+  },
+  prettier,
+];

data/lib/generators/react_on_rails/templates/redux/tailwind/app/javascript/bundles/HelloWorld/components/HelloWorld.jsx

@@ -0,0 +1,25 @@
+import React from 'react';
+
+const HelloWorld = ({ name, updateName }) => (
+  <section className="mx-auto max-w-xl rounded-lg border border-slate-200 bg-white p-6 text-slate-900 shadow-sm">
+    <p className="text-sm font-semibold uppercase text-sky-600">React on Rails + Redux + Tailwind CSS</p>
+    <h3 className="mt-2 text-2xl font-bold">Hello, {name}!</h3>
+    <p className="mt-3 text-sm leading-6 text-slate-600">
+      This Redux-backed component is server-rendered by Rails and styled by Tailwind CSS v4.
+    </p>
+    <div className="mt-5">
+      <label className="block text-sm font-medium text-slate-700" htmlFor="name">
+        Say hello to:
+        <input
+          id="name"
+          className="mt-2 w-full rounded-md border border-slate-300 px-3 py-2 shadow-sm focus:border-sky-500 focus:outline-hidden focus:ring-2 focus:ring-sky-200"
+          type="text"
+          value={name}
+          onChange={(e) => updateName(e.target.value)}
+        />
+      </label>
+    </div>
+  </section>
+);
+
+export default HelloWorld;

data/lib/generators/react_on_rails/templates/redux/tailwind/app/javascript/bundles/HelloWorld/components/HelloWorld.tsx

@@ -0,0 +1,29 @@
+import React from 'react';
+import type { PropsFromRedux } from '../containers/HelloWorldContainer';
+
+// Component props are inferred from Redux container
+type HelloWorldProps = PropsFromRedux;
+
+const HelloWorld: React.FC<HelloWorldProps> = ({ name, updateName }) => (
+  <section className="mx-auto max-w-xl rounded-lg border border-slate-200 bg-white p-6 text-slate-900 shadow-sm">
+    <p className="text-sm font-semibold uppercase text-sky-600">React on Rails + Redux + Tailwind CSS</p>
+    <h3 className="mt-2 text-2xl font-bold">Hello, {name}!</h3>
+    <p className="mt-3 text-sm leading-6 text-slate-600">
+      This Redux-backed component is server-rendered by Rails and styled by Tailwind CSS v4.
+    </p>
+    <div className="mt-5">
+      <label className="block text-sm font-medium text-slate-700" htmlFor="name">
+        Say hello to:
+        <input
+          id="name"
+          className="mt-2 w-full rounded-md border border-slate-300 px-3 py-2 shadow-sm focus:border-sky-500 focus:outline-hidden focus:ring-2 focus:ring-sky-200"
+          type="text"
+          value={name}
+          onChange={(e) => updateName(e.target.value)}
+        />
+      </label>
+    </div>
+  </section>
+);
+
+export default HelloWorld;

data/lib/react_on_rails/controller/form_responders.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module ReactOnRails
+  module Controller
+    # Opt-in controller helpers for responding to `useRailsForm` submissions
+    # (packages/react-on-rails/src/useRailsForm.ts).
+    #
+    # The hook posts JSON and expects model validation failures as HTTP 422 with
+    # the body shape `{ "errors": { "field_name": ["message", ...] } }`. This
+    # concern renders exactly that shape from any object exposing ActiveModel
+    # errors, so a controller action can stay a plain Rails action:
+    #
+    #   class ContactMessagesController < ApplicationController
+    #     include ReactOnRails::Controller::FormResponders
+    #
+    #     def create
+    #       contact_message = ContactMessage.new(contact_message_params)
+    #       if contact_message.save
+    #         render json: { message: "Thanks!" }, status: :created
+    #       else
+    #         render_model_errors(contact_message)
+    #       end
+    #     end
+    #   end
+    #
+    # Including this concern is optional — `useRailsForm` works against any
+    # endpoint that returns the documented shape.
+    module FormResponders
+      # Renders the validation errors of an ActiveModel/ActiveRecord object as
+      # JSON in the shape `useRailsForm` maps onto per-field errors.
+      #
+      # record: any object responding to `errors` with `ActiveModel::Errors`
+      #         (or anything whose `errors` responds to `messages`).
+      # status: Numeric HTTP status for the response. Defaults to 422
+      #         (Unprocessable Content), which is what the hook's error mapping
+      #         keys on. Numeric statuses sidestep Rack/Rails status-symbol
+      #         renames such as :unprocessable_entity to :unprocessable_content.
+      # SECURITY: ActiveModel error messages are sent to the browser verbatim.
+      # Review custom validations for internal IDs, admin-only details, or
+      # security-sensitive wording before using this on a model.
+      def render_model_errors(record, status: 422)
+        unless status.is_a?(Integer)
+          raise ArgumentError, "render_model_errors status must be an Integer HTTP status code"
+        end
+
+        unless record.respond_to?(:errors)
+          raise ArgumentError, "render_model_errors record must respond to errors.messages"
+        end
+
+        errors = record.errors
+        unless errors.respond_to?(:messages)
+          raise ArgumentError, "render_model_errors record must respond to errors.messages"
+        end
+
+        render json: { errors: errors.messages }, status:
+      end
+    end
+  end
+end

data/lib/react_on_rails/dev/server_manager.rb

@@ -515,7 +515,7 @@ module ReactOnRails
           when "webpack"
             "config/webpack/development.js: ReactRefreshWebpackPlugin (enabled when WEBPACK_SERVE=true)"
           when "rspack"
-            "config/rspack/development.js: @rspack/plugin-react-refresh / ReactRefreshPlugin " \
+            "config/rspack/development.js: @rspack/plugin-react-refresh / ReactRefreshRspackPlugin " \
             "(enabled for the dev server)"
           else
             "Check your bundler's React Refresh plugin documentation"