`. The first specification of the React component is just the same. [Diagram: The same HelloWorld component rendered three ways. Client-only (prerender: false) ships an empty wrapper div plus a props script that the browser fills in. Server-rendered (prerender: true) ships the same wrapper now containing fully-rendered HTML, visible before any JavaScript runs. Hydration, the second half of server rendering, reads the props script and attaches event handlers to the already-painted HTML to make it interactive.] ## Different Server-Side Rendering Code (and a Server-Specific Bundle) You may want different code for your server-rendered components running server-side versus client-side. For example, if you have an animation that runs when a component is displayed, you might need to turn that off when server rendering. One way to handle this is conditional code like `if (window) { doClientOnlyCode() }`. Another way is to use a separate Webpack configuration file that can use a different server-side entry file, like `serverRegistration.js` as opposed to `clientRegistration.js`. That would set up different code for server rendering. For details on techniques to use different code for client and server rendering, see: [How to use different versions of a file for client and server rendering](https://forum.shakacode.com/t/how-to-use-different-versions-of-a-file-for-client-and-server-rendering/1352). _Requires creating a free account._ ================================================================================ PAGE: https://reactonrails.com/docs/core-concepts/react-server-rendering SOURCE: docs/oss/core-concepts/react-server-rendering.md ================================================================================ # React Server Rendering See also [Client vs. Server Rendering](../core-concepts/client-vs-server-rendering.md). ## What is the easiest way to set up a Webpack configuration for server-side-rendering? See the maintained SSR + HMR tutorial repo and related evaluation apps in [Examples and migration references](../getting-started/examples-and-references.md). ## What is Server Rendering? Here's a [decent article to introduce you to server rendering](https://medium.freecodecamp.org/server-side-rendering-your-react-app-in-three-simple-steps-7a82b95db82e). Note, React on Rails takes care of calling the methods in [ReactDOMServer](https://reactjs.org/docs/react-dom-server.html). During the Rails rendering of HTML per a browser request, the Rails server will execute some JavaScript to create a string of HTML used for React server rendering. This resulting HTML is placed with in your Rails view's output. The default JavaScript interpreter is [ExecJS](https://github.com/rails/execjs). If you want to maximize the performance of your server rendering, then you want to use React on Rails Pro which uses NodeJS to do the server rendering. See the [docs for React on Rails Pro](../../pro/react-on-rails-pro.md). See [this note](../core-concepts/client-vs-server-rendering.md). ## How do you do Server Rendering with React on Rails? 1. The `react_component` view helper method provides the `prerender:` option to switch on or off server rendering. 1. Configure your Webpack setup to create a different server bundle per your needs. While you may reuse the same bundle as for client rendering, this is not common in larger apps for many reasons, such as code splitting, handling CSS and images, different code paths for React Router on the server vs. client, etc. 1. You need to configure `config.server_bundle_js_file = "server-bundle.js"` in your `config/initializers/react_on_rails.rb` 1. You should **_not_** put a hash on the server-bundle so that you can easily use the webpack-dev-server for client bundles and have the server bundle generated by a watch process. ## Do you need server rendering? Server rendering is used for either SEO or performance reasons. ## Considerations for what code can run on in server rendering 1. Never access `window`. Animations, globals on window, etc. just don't make sense when you're trying to run some JavaScript code to output a string of HTML. 2. JavaScript calls to `setTimeout`, `setInterval`, and `clearInterval` similarly don't make sense when server rendering. 3. Promises and file system access don't work when server rendering with ExecJS. Instead, you can use the Node renderer or [React on Rails Pro](../../pro/react-on-rails-pro.md). For a comprehensive list of ExecJS constraints, see [ExecJS Limitations](./execjs-limitations.md). :::tip Pro Upgrade React on Rails Pro includes a [dedicated Node.js renderer](../../pro/node-renderer.md) that eliminates ExecJS limitations and improves SSR performance by 3-10x. It also supports [streaming SSR](../../pro/streaming-ssr.md) with React 18/19's `renderToPipeableStream` for faster Time to First Byte. [Learn more →](../../pro/upgrading-to-pro.md) ::: ================================================================================ PAGE: https://reactonrails.com/docs/core-concepts/render-functions-and-railscontext SOURCE: docs/oss/core-concepts/render-functions-and-railscontext.md ================================================================================ # Render-Functions and the Rails Context ## Render-Functions When you use a render-function to create React components (or `renderedHtml` on the server), or you register legacy or advanced shared Redux stores, React on Rails passes two params to the function it calls: 1. `props`: Props that you pass in the view helper of either `react_component` or `redux_store` 2. `railsContext`: Rails contextual information, such as the current pathname. You can customize this in your config file. **Note**: The `railsContext` is not related to the concept of a ["context" for React components](https://react.dev/reference/react/useContext). These parameters (`props` and `railsContext`) will be the same for client- and server-side rendering, except for the property `railsContext.serverSide` which tells you which one it is. While you could manually configure your Rails code to pass the "`railsContext` information" with the rest of your "props", the `railsContext` is a convenience because it's passed consistently to all invocations of Render-Functions. For example, suppose you create a "render-function" called `MyAppComponent`. ```js import React from 'react'; const MyAppComponent = (props, railsContext) => // NOTE: need to wrap in a function so this is a proper React function component that can use hooks // the props get passed again, but we ignore since we use a closure // or should we () => ( ); export default MyAppComponent; ``` --- _This would be an alternate API where you have to call `React.createElement` and the React on Rails code doesn't do that._ ```js import React from 'react'; const MyAppComponent = (props, railsContext) => // NOTE: need to wrap in a function so this is proper React function component that can use // hooks React.createElement( () => ( ), props, ); export default MyAppComponent; ``` --- > [!NOTE] > You will get a React browser console warning if you try to render this on the server since the value of `serverSide` will be different for server rendering. So if you register your render-function `MyAppComponent`, it will get called like: ```js reactComponent = MyAppComponent(props, railsContext); ``` Similarly, any Redux store is always initialized with 2 parameters: ```js reduxStore = MyReduxStore(props, railsContext); ``` > [!NOTE] > You never make these calls. React on Rails makes these calls when it does either client or server rendering. You will define functions that take these 2 params and return a React component or a Redux Store. Naturally, you do not have to use second parameter, `railsContext`, if you do not need it. If you don't take a second parameter, then you're probably defining a React function component and you will simply return a React Element, often just JSX. > [!NOTE] > See [Redux Store](../api-reference/redux-store-api.md#multiple-react-islands-on-a-page-with-one-store) on how to set up Redux stores that allow multiple React roots to talk to the same store. The `railsContext` has: (see the implementation in [ReactOnRails::Helper](https://github.com/shakacode/react_on_rails/blob/main/react_on_rails/lib/react_on_rails/helper.rb), method `rails_context` for the definitive list). ```ruby { railsEnv: Rails.env, inMailer: in_mailer?, # Locale settings i18nLocale: I18n.locale, i18nDefaultLocale: I18n.default_locale, rorVersion: ReactOnRails::VERSION, # True if the React on Rails Pro gem is installed (does not indicate license validity) rorPro: ReactOnRails::Utils.react_on_rails_pro?, # URL settings href: request.original_url, location: "#{uri.path}#{uri.query.present? ? "?#{uri.query}": ""}", scheme: uri.scheme, # http host: uri.host, # foo.com port: uri.port, pathname: uri.path, # /posts search: uri.query, # id=30&limit=5 httpAcceptLanguage: request.env["HTTP_ACCEPT_LANGUAGE"], # Other serverSide: boolean, # Are we being called on the server or client? Note: if you conditionally # render something different on the server than the client, then React will only show the # server version! } ``` Plus, you can add your customizations to this. See "rendering extension" below. > **RSC Note:** When using React on Rails Pro with RSC, `railsContext` also includes functions like `addPostSSRHook` and `getRSCPayloadStream`. These **cannot** be passed from Server Components to Client Components across the RSC boundary. Strip them before passing: `const { addPostSSRHook, getRSCPayloadStream, ...serializableContext } = railsContext;`. See [RSC Troubleshooting](../migrating/rsc-troubleshooting.md#common-error-railscontext-contains-functions). ## Rails Context The `railsContext` is a second param passed to your render-functions for React components. This is in addition to the props that are passed from the `react_component` Rails helper. For example: ERB view file: ```erb # Rails View <%= react_component("HelloWorld", props: { name: "Stranger" }) %> ``` This is what your HelloWorld.js file might contain. The railsContext is always available for any parameters that you _always_ want available for your React components. It has _nothing_ to do with the concept of the [React Context](https://reactjs.org/docs/context.html). ```js import React from 'react'; export default (props, railsContext) => { // Note, wrap in a function so this is React function component return () => ( ); }; ``` ## Why is the railsContext only passed to render-functions? There's no reason that the railsContext would ever get passed to your React component unless the value is explicitly put into the props used for rendering. If you create a React component, rather than a render-function, for use by React on Rails, then you get whatever props are passed in from the view helper, which **does not include the Rails Context**. It's trivial to wrap your component in a "render-function" to return a new component that takes both: ```js import React from 'react'; import AppComponent from './AppComponent'; const AppComponentWithRailsContext = (props, railsContext) => // Create a React Function Component so you can // use the React Hooks API in this React Function Component () => ; export default AppComponentWithRailsContext; ``` Consider this line in depth: ```js ``` The outer `{...` is for the [JSX spread operator for attributes](https://legacy.reactjs.org/docs/jsx-in-depth.html#spread-attributes) and the inner `{...` is for the [Spread in object literals](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_operator#Spread_in_object_literals). ## Use Cases ### Heroku Preboot Considerations [Heroku Preboot](https://devcenter.heroku.com/articles/preboot) is a feature on Heroku that allows for faster deploy times. When you promote your staging app to production, Preboot simply switches the production server to point at the staging app's container. This means it can deploy much faster since it doesn't have to rebuild anything. However, this means that if you use the [Define Plugin](https://github.com/webpack/docs/wiki/list-of-plugins#defineplugin) to provide the Rails environment to your client code as a variable, that variable will erroneously still have a value of `Staging` instead of `Production`. The `Rails.env` provided at runtime in the railsContext is, however, accurate. ### Needing the current URL path for server rendering Suppose you want to display a nav bar with the current navigation link highlighted by the URL. When you server-render the code, your code will need to know the current URL/path. The new `railsContext` has this information. Your application will apply something like an "active" class on the server rendering. ### Configuring different code for server side rendering Suppose you want to turn off animation when doing server side rendering. The `serverSide` value is just what you need. ## Customization of the Rails context You can customize the values passed in the `railsContext` in your `config/initializers/react_on_rails.rb`. Here's how. Set the config value for the `rendering_extension`: ```ruby config.rendering_extension = RenderingExtension ``` Implement it like this above in the same file. Create a class method on the module called `custom_context` that takes the `view_context` for a param. See [spec/dummy/config/initializers/react_on_rails.rb](https://github.com/shakacode/react_on_rails/blob/main/react_on_rails/spec/dummy/config/initializers/react_on_rails.rb) for a detailed example. ```ruby module RenderingExtension # Return a Hash that contains custom values from the view context that will get merged with # the standard rails_context values and passed to all calls to render-functions used by the # react_component and redux_store view helpers def self.custom_context(view_context) { somethingUseful: view_context.session[:something_useful] } end end ``` In this case, a prop and value for `somethingUseful` will go into the `railsContext` passed to all `react_component` and `redux_store` calls. You may set any values available in the view rendering context. ================================================================================ PAGE: https://reactonrails.com/docs/core-concepts/render-functions SOURCE: docs/oss/core-concepts/render-functions.md ================================================================================ # React on Rails Render-Functions: Usage Guide This guide explains how render-functions work in React on Rails and how to use them with Ruby helper methods. ## Component types supported by React on Rails Before diving into render-functions, it helps to know the three kinds of values you can register with `ReactOnRails.register`. React on Rails classifies each registered entry based on its shape, and the classification determines where it can run (server, client, or both) and which Ruby helpers can invoke it. | Type | Signature | Server (SSR) | Client | Detection rule | | --------------------- | ---------------------------------------------------------- | --------------- | ------ | ----------------------------------------------------------------------- | | **React Component** | `(props) => JSX` or class component | Yes | Yes | `Function.length <= 1` and no `renderFunction` flag | | **Render Function** | `(props, railsContext) => ...` | Yes | Yes | `Function.length >= 2` **or** `fn.renderFunction === true` | | **Renderer Function** | `(props, railsContext, domNodeId) => void \| { teardown }` | **No — throws** | Yes | A render function (detected first) with exactly `Function.length === 3` | A few important points about the detection: - **The detection is based on `Function.length`** (the number of declared parameters). Destructured parameters count as 1 — `({ name }) => ...` has length 1. - **Render functions return** a React component, a React element, a server-render hash object, or a promise that resolves to one of those. See [Types of Render-Functions and Their Return Values](#types-of-render-functions-and-their-return-values) below. - **Renderer functions may optionally return a teardown wrapper** — `{ teardown: () => void | Promise }`, or a promise resolving to one. They take control of mounting/hydration themselves by calling `ReactDOM.hydrateRoot` / `createRoot` against `domNodeId`. Because there is no DOM on the server, **registering a renderer function and then server-rendering it throws a descriptive error**. Renderer functions are strictly client-side. - **`fn.renderFunction = true` is an escape hatch** for render functions that don't need `railsContext` but still want to be treated as render functions (e.g., so they can return a hash). Without the flag, a one-parameter function is classified as a regular React component. ```jsx import ReactDOMClient from 'react-dom/client'; // Regular React Component — 0 or 1 params, renders normally const HelloMessage = (props) =>

Hello {props.name}

; // Render Function — 2 params, returns a React component or a hash const HelloWithContext = (props, railsContext) => { return () => (

Hello {props.name} from {railsContext.pathname}

); }; // Render Function via the renderFunction flag — 1 param but still a render function const HelloHash = (props) => { return { renderedHtml: { componentHtml: `

Hello ${props.name}

` } }; }; HelloHash.renderFunction = true; // Renderer Function — 3 params, handles hydration itself, CLIENT ONLY. // Optionally return a { teardown } wrapper, or a promise resolving to one. // React on Rails runs it on Turbo/Turbolinks navigation or same-id replacement. const LazyHydrate = (props, _railsContext, domNodeId) => whenVisible(domNodeId).then(() => { const domNode = document.getElementById(domNodeId); // Navigation may remove the node before visibility resolves, so there is no mounted root to clean up. if (!domNode) return undefined; const root = ReactDOMClient.hydrateRoot(domNode, ); return { teardown: () => root.unmount() }; }); ReactOnRails.register({ HelloMessage, HelloWithContext, HelloHash, LazyHydrate }); ``` `whenVisible` is a hypothetical helper that resolves when the element scrolls into view. The `LazyHydrate` example uses a concise-body arrow, so it returns the `whenVisible(...).then(...)` promise. If navigation removes the node before hydration runs, the callback returns nothing because there is no mounted root to clean up. If you switch the renderer to a `{ }` block body, add an explicit `return` or React on Rails will not receive the teardown wrapper. The rest of this document focuses on **render functions** — the most flexible of the three types, with the richest set of return values. For renderer functions (client-side mounting control), see [Renderer Functions](../api-reference/view-helpers-api.md#renderer-functions-function-that-will-call-reactdomrender-or-reactdomhydrate) in the view helpers reference. ### Compatibility matrix: component types and Ruby helpers The Ruby helper you use in your Rails view must be compatible with the component type you registered. Mismatches usually produce a clear server-side error, but it's faster to pick the right combination upfront: | Component type | `react_component` | `react_component_hash` | `stream_react_component` (Pro) | | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **React Component** (plain function / class) | ✅ Works (client-side rendering or SSR) | ❌ Raises — the helper requires a hash return, not a component | ✅ Works (streaming SSR) | | **Render Function returning a React component** | ✅ Works | ❌ Raises — must return a hash, not a component | ✅ Works | | **Render Function returning `{ renderedHtml: string }`** | ✅ Works | ❌ Raises — string is not a hash with `componentHtml` | ❌ Raises — streaming does not support server render hashes | | **Render Function returning `{ renderedHtml: ReactElement }`** | ✅ Works (calls `renderToString` on the element) | ❌ Raises — element is not a hash with `componentHtml` | ❌ Raises — streaming does not support server render hashes | | **Render Function returning a server-render hash** (`{ renderedHtml: { componentHtml, ... } }`) | ⚠️ Raises — tells you to use `react_component_hash` | ✅ Works (the designed use case) | ❌ Raises — streaming does not support server render hashes | | **Async Render Function** (returns a Promise) | ✅ Works with Pro Node renderer. ❌ ExecJS silently returns empty output — see [Async functions and ExecJS](#async-functions-and-execjs). | ✅ Only if the promise resolves to a server-render hash with `componentHtml`. Pro Node renderer only. | ✅ Only if the promise resolves to a React component. Promises resolving to strings or server-render hashes are rejected — streaming does not support server render hashes. | | **Renderer Function** (3 params) | ✅ Works with `prerender: false` (client-only). ❌ Throws with `prerender: true` — renderer functions cannot run on the server. | ❌ Raises — `react_component_hash` forces `prerender: true`, which is incompatible with renderer functions | ❌ Raises — streaming requires server rendering | **Key takeaways:** - `react_component_hash` is specifically for the "multiple HTML strings in one response" use case. If your render function returns a plain component, string, or React element, use `react_component` instead. - Renderer functions are a client-only optimization. Any helper that prerenders (`prerender: true`, `react_component_hash`, or `stream_react_component`) will throw when used with a renderer function. - Async render functions require the Pro Node renderer. On ExecJS, they fail silently — see the warning in the [Promises of Strings](#5-promises-of-strings) section. ## Types of Render-Functions and Their Return Values Render-functions take two parameters: 1. `props`: The props passed from the Ruby helper methods (via the `props:` parameter), which become available in your JavaScript. 2. `railsContext`: Rails contextual information like current pathname, locale, etc. See the [Render-Functions and the Rails Context](../core-concepts/render-functions-and-railscontext.md) documentation for more details. ### Identifying Render-Functions As shown in the [component types table](#component-types-supported-by-react-on-rails) above, React on Rails marks a function as a render function in two ways: 1. Accept two parameters in your function definition: `(props, railsContext)` — React on Rails will detect this signature (the parameter names don't matter). 2. Add a `renderFunction = true` property to your function — useful when your function doesn't need `railsContext`. Render-functions can return several types of values: ### 1. React Components ```jsx const MyComponent = (props, _railsContext) => { // The `props` parameter here is identical to the `props` passed from the Ruby helper methods (via the `props:` parameter). // Both `props` and `reactProps` refer to the same object. return (reactProps) =>

Hello {props.name}

; }; ``` > [!IMPORTANT] > **Return a React component (a function or class), not a React element.** That means `return MyComponent;` or `return () =>

…

;`, **not** `return ;` or `return

…

;`. Returning a React element directly is deprecated: React on Rails currently logs a `console.error` and still renders the element, but **hooks silently don't work**, and the behavior may change in a future release. If you need to return JSX from a render function, wrap it in a server-render hash — see [Return Type 3](#3-objects-with-renderedhtml-as-a-react-element) below. ### 2. Objects with `renderedHtml` string property ```jsx const MyComponent = (props, _railsContext) => { return { renderedHtml: `

Hello ${props.name}

`, }; }; ``` ### 3. Objects with `renderedHtml` as a React element This is the supported way to return JSX from a render function: wrap it in `{ renderedHtml: ... }`. React on Rails will call `renderToString` on the element and use the result as the server-rendered HTML. Unlike [returning a React element directly](#1-react-components), this form correctly satisfies React's Rules of Hooks — the element is rendered in a normal component tree context, so hooks that are SSR-compatible (e.g., `useState`, `useContext`) work as expected during server rendering. > **React 19 Alternative:** For metadata use cases (titles, meta tags), consider using [React 19 Native Metadata](../building-features/react-19-native-metadata.md) instead of this pattern. React 19 hoists ``, metaTags: ``, }, }; }; ``` ### 5. Promises of Strings This and other promise options below are only available in React on Rails Pro with the Node renderer. > **React on Rails note:** Async render functions should still receive application data from Rails as regular props. For streaming slow props behind Suspense boundaries, React on Rails Pro async props inject `getReactOnRailsAsyncProp` when the Rails view uses `stream_react_component_with_async_props`. That streaming setup requires the controller to `include ReactOnRailsPro::Stream`, render via `stream_view_containing_react_components`, and set `config.enable_rsc_support = true`. Keep authorization, database access, and cache-aware loading in Rails rather than fetching inside the render function. See [RSC data fetching](../migrating/rsc-data-fetching.md). The `async` keyword is intentional in these examples: it makes the render function return a Promise so the Pro Node renderer can await the resolved string, hash, or component return value. The data is still prepared by Rails and read from props. ```jsx const MyComponent = async (props, _railsContext) => { const data = props.data; return `

Hello ${data.name}

`; }; ``` #### Async functions and ExecJS > [!WARNING] > Async render functions **only work with the React on Rails Pro Node renderer**. When a promise-returning render function is used on ExecJS (the OSS default SSR runtime), React on Rails logs a `console.error` and returns an empty JSON object (`'{}'`) as the server-rendered output. **The Rails view ends up with empty content and no visible exception**, which can be hard to diagnose. If you use async render functions, make sure your server runtime is the Pro Node renderer. > > The exact error message logged to `console.error` is: `Your render function returned a Promise, which is only supported by the React on Rails Pro Node renderer, not ExecJS.` ### 6. Promises of server-side hash ```jsx const MyComponent = async (props, _railsContext) => { const data = props.data; return { componentHtml: `

Hello ${data.name}

`, title: ``, metaTags: ``, }; }; ``` ### 7. Promises of React Components ```jsx const MyComponent = async (props, _railsContext) => { const data = props.data; return () =>

Hello {data.name}

; }; ``` ### 8. Redirect Information (Legacy) > [!WARNING] > **These fields have significant limitations.** They originated from React Router v3/v4 integrations but are still supported at the runtime level: > > - `redirectLocation` does **not** trigger an actual server-side HTTP redirect — Rails still returns the full response with an empty `

`. The redirect only takes effect once the client-side router renders. > - `routeError` only triggers `raise_on_prerender_error` behavior (if enabled) — it does not produce a user-facing error page. > - Modern React Router v6 Declarative Mode (`StaticRouter`) has no mechanism to produce these values. > - React Router v6 Data Mode (`createStaticHandler`) handles redirects via `Response` objects, not these fields. > > **Modern alternatives:** > > - For redirects during SSR, handle them in your Rails controller (e.g., check auth before rendering and call `redirect_to`). > - For client-side redirects, use React Router's `` (note: this is a [no-op during SSR](../building-features/react-router.md#navigate-component-ssr-behavior)). > - For route errors, use React Router's `errorElement` or an `ErrorBoundary`. ```jsx // Legacy pattern — prefer modern alternatives above const MyComponent = (props, _railsContext) => { return { redirectLocation: { pathname: '/new-path', search: '' }, routeError: null, }; }; ``` ## Important Rendering Behavior Take a look at [serverRenderReactComponent.test.ts](https://github.com/shakacode/react_on_rails/blob/main/packages/react-on-rails/tests/serverRenderReactComponent.test.ts): 1. **Direct String Returns Don't Work** - Returning a raw HTML string directly from a render function causes an error. Always wrap HTML strings in `{ renderedHtml: '...' }`. 2. **Objects Require Specific Properties** - Non-promise objects must include a `renderedHtml` property to be valid when used with `react_component`. 3. **Which object keys trigger "server render hash" processing** — React on Rails treats a returned object as a server render hash if it contains **any** of these keys: `renderedHtml`, `redirectLocation`, `routeError`, or `error`. If none of those keys are present, the object is passed through unchanged (which typically fails validation elsewhere). > [!WARNING] > **The `error` key is a landmine.** If your render function accidentally returns `{ error: someError }` — for example from a `try/catch` block — the framework routes it through server-render-hash handling, which produces **empty HTML output** (because `renderedHtml` is missing). Note that `hasErrors` is _not_ set — only `routeError` sets the error flag, so no `PrerenderError` is raised regardless of `raise_on_prerender_error`. If you want to signal failure, throw an error instead of returning one in a plain object. 4. **Async Functions Support Server Render Hashes** - When using the React on Rails Pro Node renderer, async render-functions can return React components, strings, or full server render hashes, including `clientProps`, `redirectLocation`, and `routeError`. See [8. Redirect Information (Legacy)](#8-redirect-information-legacy). 5. **`clientProps` are merged back into hydration props** - If a server render result includes `clientProps`, React on Rails merges those keys into the client hydration props generated by `react_component`. - Use this to pass server-only computed hydration data (for example router dehydrated state). - Merge order is `original_props.merge(clientProps)`, so keys from `clientProps` override matching original keys. - This merge requires your original `props:` to be a Ruby `Hash` or a JSON string representing an object. If you pass any other type (including `nil`), the helper raises an error with a message pointing to this requirement. - **Symbol vs string keys:** If your original props use a symbol key (`:locale`) and `clientProps` returns the same name as a string (`"locale"`), the merge writes to the existing symbol key to preserve its type. If your original props contain **both** forms of the same key (`:locale` and `"locale"`), the merge raises an error rather than guessing which one you meant. ## Ruby Helper Functions ### 1. react_component The `react_component` helper renders a single React component in your view. ```ruby <%= react_component("MyComponent", props: { name: "John" }) %> ``` This helper accepts render-functions that return React components, objects with a `renderedHtml` property, or promises that resolve to React components, strings, or server-side hash objects. If your render-function returns `clientProps`, this helper also injects those values into the generated client hydration payload. #### When to use - When you need to render a single component - When you're rendering client-side only - When your render function returns a single HTML string #### Not suitable for - When your render function returns an object with multiple HTML strings - When you need to insert content in different parts of the page, such as meta tags & style tags ### 2. react_component_hash The `react_component_hash` helper is used when your render function returns an object with multiple HTML strings. It allows you to place different parts of the rendered output in different parts of your layout. ```ruby # With a render function that returns an object with multiple HTML properties <% helmet_data = react_component_hash("HelmetComponent", props: { title: "My Page", description: "Page description" }) %> <% content_for :head do %> <%= helmet_data["title"] %> <%= helmet_data["metaTags"] %> <% end %>

<%= helmet_data["componentHtml"] %>

``` This helper accepts render-functions that return objects with a `renderedHtml` property containing `componentHtml` and any other necessary properties. It also supports promises that resolve to a server-side hash. #### When to use - When your render function returns multiple HTML strings in an object - When you need to insert rendered content in different parts of your page - For SEO-related rendering like meta tags and title tags - When working with libraries like React Helmet #### Not suitable for - Simple component rendering - Client-side only rendering (always uses server rendering) - Renderer functions (3-parameter functions) — these are client-only and incompatible with forced server rendering #### Requirements - The render function MUST return an object with shape `{ renderedHtml: { componentHtml, ...otherKeys } }` - The `renderedHtml` object MUST include a `componentHtml` key — missing it raises `ReactOnRails::Error` - All other keys inside `renderedHtml` are optional and can be accessed in your Rails view as `result["keyName"]` ## Examples with Appropriate Helper Methods ### Return Type 1: React Component ```jsx const SimpleComponent = (props, _railsContext) => () =>

Hello {props.name}

; ReactOnRails.register({ SimpleComponent }); ``` ```erb <%# Ruby %> <%= react_component("SimpleComponent", props: { name: "John" }) %> ``` ### Return Type 2: Object with renderedHtml ```jsx const RenderedHtmlComponent = (props, _railsContext) => { return { renderedHtml: `

Hello ${props.name}

` }; }; ReactOnRails.register({ RenderedHtmlComponent }); ``` ```erb <%# Ruby %> <%= react_component("RenderedHtmlComponent", props: { name: "John" }) %> ``` ### Return Type 3: Object with `renderedHtml` React element ```jsx const ElementHtmlComponent = (props, _railsContext) => { return { renderedHtml:

Hello {props.name}

, }; }; ElementHtmlComponent.renderFunction = true; ReactOnRails.register({ ElementHtmlComponent }); ``` ```erb <%# Ruby %> <%= react_component("ElementHtmlComponent", props: { name: "John" }, prerender: true) %> ``` ### Return Type 4: Object with server-side hash ```jsx const HelmetComponent = (props) => { const componentHtml = renderToString(

Hello {props.name}

); return { renderedHtml: { componentHtml, title: ``, metaTags: ``, }, }; }; // The render function should either: // 1. Accept two arguments: (props, railsContext) // 2. Have a property `renderFunction` set to true HelmetComponent.renderFunction = true; ReactOnRails.register({ HelmetComponent }); ``` ```erb <%# Ruby - MUST use react_component_hash %> <% helmet_data = react_component_hash("HelmetComponent", props: { name: "John", title: "My Page", description: "Page description" }) %> <% content_for :head do %> <%= helmet_data["title"] %> <%= helmet_data["metaTags"] %> <% end %>

<%= helmet_data["componentHtml"] %>

``` ### Return Type 5: Promise of String ```jsx const AsyncStringComponent = async (props) => { const data = props.data; return `

Hello ${data.name}

`; }; AsyncStringComponent.renderFunction = true; ReactOnRails.register({ AsyncStringComponent }); ``` ```erb <%# Ruby %> <%= react_component("AsyncStringComponent", props: { data: { name: @user.name } }) %> ``` ### Return Type 6: Promise of server-side hash ```jsx const AsyncObjectComponent = async (props) => { const data = props.data; return { componentHtml: `

Hello ${data.name}

`, title: ``, metaTags: ``, }; }; AsyncObjectComponent.renderFunction = true; ReactOnRails.register({ AsyncObjectComponent }); ``` ```erb <%# Ruby - MUST use react_component_hash %> <% helmet_data = react_component_hash("AsyncObjectComponent", props: { data: { name: @user.name, title: "#{@user.name}'s Profile", description: @user.bio } }) %> <% content_for :head do %> <%= helmet_data["title"] %> <%= helmet_data["metaTags"] %> <% end %>

<%= helmet_data["componentHtml"] %>

``` ### Return Type 7: Promise of React Component ```jsx const AsyncReactComponent = async (props) => { const data = props.data; return () =>

Hello {data.name}

; }; AsyncReactComponent.renderFunction = true; ReactOnRails.register({ AsyncReactComponent }); ``` ```erb <%# Ruby %> <%= react_component("AsyncReactComponent", props: { data: { name: @user.name } }) %> ``` ### Return Type 8: Redirect Object (Legacy) ```jsx const RedirectComponent = (props, railsContext) => { if (!railsContext.currentUser) { return { redirectLocation: { pathname: '/login', search: '' }, }; } return { renderedHtml:

Welcome {railsContext.currentUser.name}

, }; }; RedirectComponent.renderFunction = true; ReactOnRails.register({ RedirectComponent }); ``` ```erb <%# Ruby %> <%= react_component("RedirectComponent") %> ``` ### Return Type 9: Server-rendered `clientProps` for hydration ```jsx const RouterShell = (props, railsContext) => { const componentHtml = renderToString(); return { renderedHtml: componentHtml, clientProps: { routerDehydratedState: { url: railsContext.location }, }, }; }; RouterShell.renderFunction = true; ReactOnRails.register({ RouterShell }); ``` ```erb <%# Ruby: pass a Hash or a JSON object string so clientProps can merge correctly %> <%= react_component("RouterShell", props: { locale: I18n.locale }, prerender: true) %> ``` By understanding these return types and which helper to use with each, you can create sophisticated server-rendered React components that fully integrate with your Rails views. ================================================================================ PAGE: https://reactonrails.com/docs/core-concepts/auto-bundling SOURCE: docs/oss/core-concepts/auto-bundling-file-system-based-automated-bundle-generation.md ================================================================================ # Auto-Bundling: File-System-Based Automated Bundle Generation To use the automated bundle generation feature introduced in React on Rails v13.1.0, please upgrade to use [Shakapacker v6.5.1](https://github.com/shakacode/shakapacker/tree/v6.5.1) at least. If you are currently using Webpacker, please follow the migration steps available [v6 upgrade](https://github.com/shakacode/shakapacker/blob/master/docs/v6_upgrade.md). Then upgrade to Shakapacker 7 using [v7 upgrade](https://github.com/shakacode/shakapacker/blob/master/docs/v7_upgrade.md) guide. ## Configuration ### Enable nested_entries for Shakapacker To use the automated bundle generation feature, set `nested_entries: true` in the `shakapacker.yml` file like this. The generated files will go in a nested directory. ```yml default: ... nested_entries: true ``` For more details, see [Configuration and Code](https://github.com/shakacode/shakapacker#configuration-and-code) section in [shakapacker](https://github.com/shakacode/shakapacker/). > Example (dummy app): `nested_entries: true` with a different `source_path: client/app`. See `config/shakapacker.yml` in the dummy app. > [Dummy shakapacker.yml](https://github.com/shakacode/react_on_rails/blob/main/react_on_rails/spec/dummy/config/shakapacker.yml) ### Configure Components Subdirectory `components_subdirectory` is the name of the matched directories containing components that will be automatically registered for use by the view helpers. For example, configure `config/initializers/react_on_rails` to set the name for `components_subdirectory`: ```rb config.components_subdirectory = "ror_components" ``` Now all React components inside the directories called `ror_components` will automatically be registered for usage with [`react_component`](../api-reference/view-helpers-api.md#react_component) and [`react_component_hash`](../api-reference/view-helpers-api.md#react_component_hash) helper methods provided by React on Rails. > Example (dummy app): the configured components subdirectory is named `startup` instead of `ror_components`. > [Dummy initializer](https://github.com/shakacode/react_on_rails/blob/main/react_on_rails/spec/dummy/config/initializers/react_on_rails.rb) ### Configure `auto_load_bundle` Option For automated component registry, [`react_component`](../api-reference/view-helpers-api.md#react_component) and [`react_component_hash`](../api-reference/view-helpers-api.md#react_component_hash) view helper method tries to load generated bundle for component from the generated directory automatically per `auto_load_bundle` option. `auto_load_bundle` option in `config/initializers/react_on_rails` configures the default value that will be passed to component helpers. The default is `false`, and the parameter can be passed explicitly for each call. You can change the value in `config/initializers/react_on_rails` by updating it as follows: ```rb config.auto_load_bundle = true ``` > Example (dummy app): `auto_load_bundle` is set to `true` in the same initializer. > [Dummy initializer](https://github.com/shakacode/react_on_rails/blob/main/react_on_rails/spec/dummy/config/initializers/react_on_rails.rb) ### Location of generated files Generated files will go to the following two directories: - Pack files for entrypoint components will be generated in the `{Shakapacker.config.source_entry_path}/generated` directory. - The interim server bundle file, which is only generated if you already have a server bundle entrypoint and have not set `make_generated_server_bundle_the_entrypoint` to `true`, will be generated in the `{Pathname(Shakapacker.config.source_entry_path).parent}/generated` directory. ### Update `.gitignore` file To avoid committing generated files to your version control system, please update `.gitignore` to include: ```gitignore # Generated React on Rails packs **/generated/** ``` ### Commit changes to server bundle entrypoint If you already have an existing server bundle entrypoint and have not set `make_generated_server_bundle_the_entrypoint` to `true`, then pack generation will add an import statement to your existing server bundle entrypoint similar to: ```javascript // import statement added by react_on_rails:generate_packs rake task import '../generated/server-bundle-generated.js'; ``` We recommend committing this import statement to your version control system. > Example (dummy app): see the server bundle entrypoint import. > [Dummy `server-bundle.ts`](../../../react_on_rails/spec/dummy/client/app/packs/server-bundle.ts) ## Usage ### Basic usage #### Background If the `shakapacker.yml` file is configured as instructed in the [Shakapacker configuration guide](https://github.com/shakacode/shakapacker#configuration-and-code), with the following configurations ```yml default: &default source_path: app/javascript source_entry_path: packs public_root_path: public public_output_path: packs nested_entries: true # And more ``` the directory structure will look like this ```text app/javascript: └── packs: # sets up webpack entries │ └── application.js # references FooComponentOne.jsx, BarComponentOne.jsx and BarComponentTwo.jsx in `../src` └── src: # any directory name is fine. Referenced files need to be under source_path │ └── Foo │ │ └── ... │ │ └── FooComponentOne.jsx │ └── Bar │ │ └── ... │ │ └── BarComponentOne.jsx │ │ └── BarComponentTwo.jsx └── stylesheets: │ └── my_styles.css └── images: └── logo.svg ``` Previously, many applications would use one pack (webpack entrypoint) for many components. In this example, the`application.js` file manually registers server components, `FooComponentOne`, `BarComponentOne` and `BarComponentTwo`. ```jsx import ReactOnRails from 'react-on-rails'; import FooComponentOne from '../src/Foo/FooComponentOne'; import BarComponentOne from '../src/Foo/BarComponentOne'; import BarComponentTwo from '../src/Foo/BarComponentTwo'; ReactOnRails.register({ FooComponentOne, BarComponentOne, BarComponentTwo }); ``` Your layout would contain: ```erb <%= javascript_pack_tag 'application' %> <%= stylesheet_pack_tag 'application' %> ``` #### Manual bundle splitting (pre-auto-bundling pattern) The single-pack approach above loads **every** component's JavaScript on **every** page, even pages that only render one or two components. To avoid shipping unused code, you can split the bundle manually by giving each component its own pack file. Each pack file imports one component and registers it — webpack treats each pack as a separate entry point and produces a separate bundle. ```text app/javascript/ ├── packs/ # each file here is a webpack entry point │ ├── FooComponentOne.jsx # imports FooComponentOne, calls ReactOnRails.register({ FooComponentOne }) │ ├── BarComponentOne.jsx # imports BarComponentOne, calls ReactOnRails.register({ BarComponentOne }) │ └── BarComponentTwo.jsx # imports BarComponentTwo, calls ReactOnRails.register({ BarComponentTwo }) └── src/ # shared source; any directory name works as long as it's under source_path ├── Foo/ │ └── FooComponentOne.jsx # the actual component implementation └── Bar/ ├── BarComponentOne.jsx └── BarComponentTwo.jsx ``` Each pack file is typically a one-liner that imports the component and registers it: ```jsx // app/javascript/packs/FooComponentOne.jsx import ReactOnRails from 'react-on-rails'; import FooComponentOne from '../src/Foo/FooComponentOne'; ReactOnRails.register({ FooComponentOne }); ``` The tricky part with this manual approach is telling each Rails view which bundles to load. [Shakapacker's `append_javascript_pack_tag` and `append_stylesheet_pack_tag` view helpers](https://github.com/shakacode/shakapacker#view-helper-append_javascript_pack_tag-and-append_stylesheet_pack_tag) let each view declare the packs it needs, which the layout's `javascript_pack_tag` and `stylesheet_pack_tag` calls then render. Auto-bundling (described in the next section) automates both steps: it generates these per-component pack files for you, and the `react_component` view helper automatically appends the right pack tags at render time. #### Solution File-system-based automated pack generation simplifies this process with a new option for the view helpers. [Diagram: Manual bundle splitting versus auto-bundling. With manual splitting you hand-write a one-line pack file that imports and registers each component, and every Rails view must declare which packs it needs with append_javascript_pack_tag — easy to forget. With auto-bundling you drop components into the ror_components convention directory and React on Rails generates the per-component pack files and bundles for you, while the react_component view helper appends the right pack tags automatically, giving per-page code splitting with no boilerplate.] > Note: In the Background examples above, we used `BarComponentTwo`. In the Solution below, we refer to the same component as `SpecialComponentNotToAutoLoadBundle` to emphasize that it is excluded from auto-loading. You do not need to rename your files. For example, if you wanted to utilize our file-system based entrypoint generation for `FooComponentOne` and `BarComponentOne`, but not `SpecialComponentNotToAutoLoadBundle` (formerly `BarComponentTwo`) (for whatever reason), then... 1. Remove generated entrypoints from parameters passed directly to `javascript_pack_tag` and `stylesheet_pack_tag`. 2. Remove generated entrypoints from parameters passed directly to `append_javascript_pack_tag` and `append_stylesheet_pack_tag`. Your layout would now contain: ```erb <%= javascript_pack_tag('SpecialComponentNotToAutoLoadBundle') %> <%= stylesheet_pack_tag('SpecialComponentNotToAutoLoadBundle') %> ``` 3. Create a directory structure where the components that you want to be auto-generated are within `ReactOnRails.configuration.components_subdirectory`, which should be a subdirectory of `Shakapacker.config.source_path`: ```text app/javascript: └── packs: │ └── SpecialComponentNotToAutoLoadBundle.jsx # Internally uses ReactOnRails.register └── src: │ └── Foo │ │ └── ... │ │ └── ror_components # configured as `components_subdirectory` │ │ └── FooComponentOne.jsx │ └── Bar │ │ └── ... │ │ └── ror_components # configured as `components_subdirectory` │ │ │ └── BarComponentOne.jsx │ │ └── something_else │ │ │ └── SpecialComponentNotToAutoLoadBundle.jsx ``` 4. You no longer need to register the React components within the `ReactOnRails.configuration.components_subdirectory` nor directly add their bundles. For example, you can have a Rails view using three components: ```erb <%= react_component("FooComponentOne", {}, auto_load_bundle: true) %> <%= react_component("BarComponentOne", {}, auto_load_bundle: true) %> <% append_javascript_pack_tag('SpecialComponentNotToAutoLoadBundle') %> <%= react_component("SpecialComponentNotToAutoLoadBundle", {}) %> ``` If a component uses multiple HTML strings for server rendering, the [`react_component_hash`](../api-reference/view-helpers-api.md#react_component_hash) view helper can be used on the Rails view, as illustrated below. ```erb <% foo_component_one_data = react_component_hash( "FooComponentOne", prerender: true, auto_load_bundle: true, props: {} ) %> <% content_for :title do %> <%= foo_component_one_data["title"] %> <% end %> <%= foo_component_one_data["componentHtml"] %> ``` The default value of the `auto_load_bundle` parameter can be specified by setting `config.auto_load_bundle` in `config/initializers/react_on_rails.rb` and thus removed from each call to `react_component`. ### Layout Integration with Auto-Loading When using `auto_load_bundle: true`, your Rails layout needs to include empty pack tag placeholders where React on Rails will inject the component-specific CSS and JavaScript bundles automatically: ```erb <%= csrf_meta_tags %> <%= csp_meta_tag %> <%= stylesheet_pack_tag %> <%= javascript_pack_tag %> <%= yield %> ``` **How it works:** 1. **Component calls automatically append bundles**: When you use `<%= react_component("ComponentName", props, auto_load_bundle: true) %>` in a view, React on Rails automatically calls `append_javascript_pack_tag "generated/ComponentName"` and `append_stylesheet_pack_tag "generated/ComponentName"` (in static/production modes). 2. **Layout renders appended bundles**: The empty `<%= stylesheet_pack_tag %>` and `<%= javascript_pack_tag %>` calls in your layout are where the appended component bundles get rendered. 3. **No manual bundle management**: You don't need to manually specify which bundles to load - React on Rails handles this automatically based on which components are used in each view. **Example with multiple components:** If your view contains: ```erb <%= react_component("HelloWorld", @hello_world_props, auto_load_bundle: true) %> <%= react_component("HeavyMarkdownEditor", @editor_props, auto_load_bundle: true) %> ``` React on Rails automatically generates HTML equivalent to: ```erb <%= stylesheet_pack_tag "generated/HelloWorld" %> <%= stylesheet_pack_tag "generated/HeavyMarkdownEditor" %> <%= javascript_pack_tag "generated/HelloWorld" %> <%= javascript_pack_tag "generated/HeavyMarkdownEditor" %> ``` This enables optimal bundle splitting where each page only loads the CSS and JavaScript needed for the components actually used on that page. > [!TIP] > React on Rails Pro RSC static shells can keep the shared Rails layout and global CSS while opting > out of an app-wide global JavaScript pack on selected pages. See > [Page-Level Global JavaScript Opt-Out for Static Shells](../../pro/react-server-components/static-shell-global-js-opt-out.md). ## Complete Working Example Here's a step-by-step example showing how to set up file-system-based automated bundle generation from scratch: ### 1. Configure Shakapacker In `config/shakapacker.yml`: ```yml default: &default source_path: app/javascript source_entry_path: packs public_root_path: public public_output_path: packs nested_entries: true # Required for auto-generation cache_manifest: false ``` ### 2. Configure React on Rails In `config/initializers/react_on_rails.rb`: ```rb ReactOnRails.configure do |config| config.components_subdirectory = "ror_components" # Directory name for auto-registered components config.auto_load_bundle = true # Enable automatic bundle loading config.server_bundle_js_file = "server-bundle.js" end ``` ### 3. Directory Structure Set up your directory structure like this: ```text app/javascript/ └── src/ ├── HelloWorld/ │ ├── HelloWorld.module.css # Component styles │ └── ror_components/ # Auto-registration directory │ └── HelloWorld.jsx # React component └── HeavyMarkdownEditor/ ├── HeavyMarkdownEditor.module.css # Component styles └── ror_components/ # Auto-registration directory └── HeavyMarkdownEditor.jsx # React component ``` ### 4. Component Implementation `app/javascript/src/HelloWorld/ror_components/HelloWorld.jsx`: ```jsx import React from 'react'; import styles from '../HelloWorld.module.css'; const HelloWorld = ({ name }) => (

Hello {name}!

Welcome to React on Rails with auto-registration!

); export default HelloWorld; ``` `app/javascript/src/HeavyMarkdownEditor/ror_components/HeavyMarkdownEditor.jsx`: ```jsx import React, { useState, useEffect } from 'react'; import styles from '../HeavyMarkdownEditor.module.css'; const HeavyMarkdownEditor = ({ initialContent = '# Hello\n\nStart editing!' }) => { const [content, setContent] = useState(initialContent); const [ReactMarkdown, setReactMarkdown] = useState(null); const [remarkGfm, setRemarkGfm] = useState(null); // Dynamic imports for SSR compatibility useEffect(() => { const loadMarkdown = async () => { const [{ default: ReactMarkdown }, { default: remarkGfm }] = await Promise.all([ import('react-markdown'), import('remark-gfm'), ]); setReactMarkdown(() => ReactMarkdown); setRemarkGfm(() => remarkGfm); }; loadMarkdown(); }, []); if (!ReactMarkdown) { return

Loading editor...

; } return (

Markdown Input:

setContent(e.target.value)} className={styles.textarea} /> </div> <div className={styles.output}> <h3>Preview:</h3> <div className={styles.preview}> <ReactMarkdown remarkPlugins={[remarkGfm]}>{content}</ReactMarkdown> </div> </div> </div> ); }; export default HeavyMarkdownEditor; ``` ### 5. Rails Layout `app/views/layouts/application.html.erb`: ```erb <!DOCTYPE html> <html> <head> <title>React on Rails Auto-Registration Demo</title> <meta name="viewport" content="width=device-width,initial-scale=1"> <%= csrf_meta_tags %> <%= csp_meta_tag %> <!-- Empty pack tags - React on Rails injects component CSS/JS here --> <%= stylesheet_pack_tag %> <%= javascript_pack_tag %> </head> <body> <%= yield %> </body> </html> ``` ### 6. Rails Views and Controller `app/controllers/hello_world_controller.rb`: ```rb class HelloWorldController < ApplicationController def index @hello_world_props = { name: 'Auto-Registration' } end def editor @editor_props = { initialContent: "# Welcome to the Heavy Editor\n\nThis component demonstrates:\n- Dynamic imports for SSR\n- Bundle splitting\n- Automatic CSS loading" } end end ``` `app/views/hello_world/index.html.erb`: ```erb <%= react_component("HelloWorld", @hello_world_props, prerender: true) %> ``` `app/views/hello_world/editor.html.erb`: ```erb <%= react_component("HeavyMarkdownEditor", @editor_props, prerender: true) %> ``` ### 7. Generate Bundles Run the pack generation command: ```bash bundle exec rake react_on_rails:generate_packs ``` This creates: - `app/javascript/packs/generated/HelloWorld.js` - `app/javascript/packs/generated/HeavyMarkdownEditor.js` ### 8. Update .gitignore ```gitignore # Generated React on Rails packs **/generated/** ``` ### 9. Start the Server Now when you visit your pages, React on Rails automatically: - Loads only the CSS and JS needed for components on each page - Registers components without manual `ReactOnRails.register()` calls - Enables optimal bundle splitting and caching **Bundle sizes in this example (measured from browser dev tools):** - **HelloWorld**: 1.1MB total resources (50KB component-specific code + shared React runtime) - HelloWorld.js: 10.0 kB - HelloWorld.css: 2.5 kB - Shared runtime: ~1.1MB (React, webpack runtime) - **HeavyMarkdownEditor**: 2.2MB total resources (2.7MB with markdown libraries) - HeavyMarkdownEditor.js: 26.5 kB - HeavyMarkdownEditor.css: 5.5 kB - Markdown libraries: 1,081 kB additional - Shared runtime: ~1.1MB (React, webpack runtime) **Bundle splitting benefit**: Each page loads only its required components - the HelloWorld page doesn't load the heavy markdown libraries, saving ~1.1MB (50% reduction)! #### Performance Screenshots **HelloWorld (Lightweight Component):**  **HeavyMarkdownEditor (Heavy Component):**  _Screenshots show browser dev tools network analysis demonstrating the dramatic difference in bundle sizes and load times between the two components._ ### Server Rendering and Client Rendering Components If server rendering is enabled, the component will be registered for usage both in server and client rendering. To have separate definitions for client and server rendering, name the component files `ComponentName.server.jsx` and `ComponentName.client.jsx`. The `ComponentName.server.jsx` file will be used for server rendering and the `ComponentName.client.jsx` file for client rendering. If you don't want the component rendered on the server, you should only have the `ComponentName.client.jsx` file. > Example (dummy app): paired files such as [`ReduxApp.client.tsx`](../../../react_on_rails/spec/dummy/client/app/startup/ReduxApp.client.tsx) and [`ReduxApp.server.tsx`](../../../react_on_rails/spec/dummy/client/app/startup/ReduxApp.server.tsx), and [`RouterApp.client.tsx`](../../../react_on_rails/spec/dummy/client/app/startup/RouterApp.client.tsx) and [`RouterApp.server.tsx`](../../../react_on_rails/spec/dummy/client/app/startup/RouterApp.server.tsx). Once generated, all server entrypoints will be imported into a file named `[ReactOnRails.configuration.server_bundle_js_file]-generated.js`, which in turn will be imported into a source file named the same as `ReactOnRails.configuration.server_bundle_js_file`. If your server bundling logic is such that your server bundle source entrypoint is not named the same as your `ReactOnRails.configuration.server_bundle_js_file` and changing it would be difficult, please let us know. > [!IMPORTANT] > When specifying separate definitions for client and server rendering, you need to delete the generalized `ComponentName.jsx` file. > [!IMPORTANT] > **Not related to React Server Components.** The `.client.` and `.server.` file suffixes control **which webpack bundle** imports the file — a React on Rails auto-bundling concept that predates React Server Components. If you are using RSC, classification of a component as a server component is controlled separately by the `'use client'` directive, and the rules for using these suffixes with RSC are covered in [Auto-Bundling with React Server Components](#auto-bundling-with-react-server-components) below. ### Auto-Bundling with React Server Components > **Pro Feature.** React Server Components (RSC) require [React on Rails Pro](../../pro/react-server-components/index.md) with the Node renderer. This section assumes you already have RSC enabled in your project — see [Create a React Server Component](../../pro/react-server-components/create-without-ssr.md) and [Preparing your app for RSC](../migrating/rsc-preparing-app.md) for setup. When React Server Components are enabled, the auto-bundling system understands two kinds of components and chooses the correct registration function for each: - **Server Components** — files **without** a `'use client'` directive at the top. Their code runs only on the server; their output is serialized to an RSC payload. - **Client Components** — files **with** a `'use client'` directive at the top. Their code runs in the browser (and during SSR) and hydrates as normal React components. The presence or absence of `'use client'` is the **only** signal the generator uses to classify a file as a server or client component. File suffixes (`.client.jsx` / `.server.jsx`) have a different meaning (see [below](#when-to-use-client--server-variants-with-rsc)). #### How the packs generator classifies components For every file inside `components_subdirectory`, the generator: 1. Reads the file contents and checks for a `'use client'` directive on the first non-comment line. 2. If the directive is present → generates a client-bundle pack that imports the component and calls `ReactOnRails.register({ ComponentName })`, and imports the component into the aggregated server bundle with `ReactOnRails.register({ ComponentName })`. 3. If the directive is absent → generates a client-bundle pack that calls `registerServerComponent("ComponentName")` (without importing the component), and imports the component into the aggregated server bundle with `registerServerComponent({ ComponentName })`. You don't call `registerServerComponent` yourself when using auto-bundling — the generator writes these calls for you based on the classification above. > [!IMPORTANT] > If you forget the `'use client'` directive on a component that needs it, the generator classifies the file as a Server Component and wires it up with `registerServerComponent`. The packs generator does scan for common client-side patterns (hooks like `useState`, `useEffect`; event handlers like `onClick`, `onChange`; class components extending `React.Component`) and logs a warning if it detects them in a file classified as a Server Component. However, not all client-only code triggers this heuristic — always double-check that client components start with `'use client'`. #### The two `registerServerComponent` signatures `registerServerComponent` has two different shapes depending on which bundle you import it from: | Bundle | Import | Signature | Why | | ------ | --------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Client | `react-on-rails-pro/registerServerComponent/client` | `registerServerComponent(...names: string[])` | Takes only component names because the server component's code stays on the server. The client fetches the RSC payload when the component renders (or uses the payload already embedded in the HTML if the page was server-rendered). | | Server | `react-on-rails-pro/registerServerComponent/server` | `registerServerComponent(components: { [name]: Component })` | Takes an object with the actual component references because the code needs to be bundled into the server and RSC bundles for RSC payload generation. | Auto-bundling uses both forms under the hood: the per-component client packs use the client form, and the aggregated server bundle file uses the server form. #### File layout for RSC projects A typical `components_subdirectory` for an RSC-enabled project mixes server and client components in the same directory: ```text app/javascript/src/ └── ror_components/ ├── Dashboard.jsx # Server Component (no 'use client') ├── Profile.jsx # Server Component (no 'use client') ├── LikeButton.jsx # Client Component ('use client' at top) └── CommentForm.jsx # Client Component ('use client' at top) ``` Each file produces its own generated pack, and pages only load the packs for the components they render. You don't need to separate server and client components into subdirectories — the `'use client'` directive is the classifier, not the location. #### What the generator produces For the layout above, running `bin/rails react_on_rails:generate_packs` produces: **Per-component client packs** (one webpack entry point each): ```js // packs/generated/Dashboard.js (server component — no component import) import registerServerComponent from 'react-on-rails-pro/registerServerComponent/client'; registerServerComponent('Dashboard'); ``` ```js // packs/generated/LikeButton.js (client component — imported and registered normally) import ReactOnRails from 'react-on-rails-pro/client'; import LikeButton from '../../ror_components/LikeButton.jsx'; ReactOnRails.register({ LikeButton }); ``` Because each is a separate entry point, a view that calls `react_component("LikeButton", ...)` only loads the `LikeButton` pack; it never loads the `Dashboard` pack or any code for server components it doesn't render. **Aggregated server bundle file** (one file for all components): ```js // generated/server-bundle-generated.js import ReactOnRails from 'react-on-rails-pro'; import Dashboard from '../ror_components/Dashboard.jsx'; import Profile from '../ror_components/Profile.jsx'; import LikeButton from '../ror_components/LikeButton.jsx'; import CommentForm from '../ror_components/CommentForm.jsx'; import registerServerComponent from 'react-on-rails-pro/registerServerComponent/server'; registerServerComponent({ Dashboard, Profile }); ReactOnRails.register({ LikeButton, CommentForm }); ``` Your existing `packs/server-bundle.js` or `packs/server-bundle.ts` entry file doesn't need manual changes — the packs generator adds one import line at the top pointing to the aggregated file: ```js // packs/server-bundle.js or packs/server-bundle.ts import '../generated/server-bundle-generated.js'; // added by react_on_rails:generate_packs // ... your own custom server-side code continues here ``` #### When to use `.client` / `.server` variants with RSC The `.client.jsx` / `.server.jsx` suffixes that auto-bundling supports for splitting client components into separate client-side and server-side rendering definitions are **unrelated** to the `'use client'` directive. The suffixes control **which webpack bundle imports the file**; the directive controls **whether the file is a React Server Component**. These are orthogonal concepts. **Rules for using variants with RSC:** 1. **Never apply `.client` / `.server` suffixes to actual server components.** A server component's code exists only in the RSC bundle — there is no client-side version to split. `Dashboard.jsx` should stay as `Dashboard.jsx`, not become `Dashboard.client.jsx` or `Dashboard.server.jsx`. Using these suffixes on a server component causes the wrong variant (the server one) to be loaded in the browser via the client manifest. See [troubleshooting item #8](#8-component-with-serverclient-variants-used-with-rsc). 2. **Use variants only for client components that need different client-side vs server-side rendering logic** — for example, a client component that uses `BrowserRouter` in the browser and `StaticRouter` during SSR. In that case, both `.client.tsx` and `.server.tsx` must start with `'use client'`, since both are client components (they just use different imports). 3. **Use variants for the `wrapServerComponentRenderer` wrapper pattern.** When a client component contains `RSCRoute` and needs to be wrapped with `wrapServerComponentRenderer`, the wrappers are authored as `.client.tsx` and `.server.tsx` variants. See [Embedding Server Components in Client Components](../../pro/react-server-components/inside-client-components.md) for the full walkthrough. #### Compiled-to-JS languages and RSC client references For RSC builds, React on Rails only sees the JavaScript modules that webpack or rspack compile. If a component is authored in a language that emits JavaScript, such as ReScript, the RSC client-reference pipeline must discover the compiled JavaScript module that the RSC bundle will import, not the original source file. Use one of these patterns: 1. **Prefer a thin JavaScript/TypeScript wrapper for each RSC boundary.** Put the wrapper in `components_subdirectory`, import the compiled output, and make the wrapper the module that server components import. ```text app/javascript/src/Comments/ ├── ReScriptLikeButton.bs.js └── ror_components/ └── ReScriptLikeButton.jsx ``` ```jsx // app/javascript/src/Comments/ror_components/ReScriptLikeButton.jsx 'use client'; import ReScriptLikeButton from '../ReScriptLikeButton.bs.js'; export default ReScriptLikeButton; ``` Server components should import the wrapper path, not the compiled `.bs.js` file directly. That keeps the `'use client'` directive, auto-bundled pack, RSC client-reference manifest key, and runtime module resolution aligned on the same JavaScript module. The same wrapper also satisfies the component-naming requirement covered in [Transpiled Languages (ReScript, Reason, etc.)](#transpiled-languages-rescript-reason-etc) below, so you do not need a second wrapper file. 2. **If the compiled output is the boundary module, make the compiled JavaScript discoverable.** The generated RSC configs read client references from the file named by `RSC_MANIFEST_CLIENT_REFERENCES_JSON`, or from the default path `ssr-generated/rsc-client-references.json` when the env var is not set. That JSON must have this shape: ```json { "refs": ["app/javascript/src/Comments/ReScriptLikeButton.bs.js"] } ``` The `refs` entries must match the compiled module paths that webpack/rspack resolve in the RSC build; use paths relative to the Rails root (webpack's cwd at build time), not absolute paths or module-specifier aliases. Do not list the original `.res` source path unless that is the module actually imported by the RSC bundle through a loader. > [!IMPORTANT] > The compiled JavaScript file must carry a `'use client'` directive at the top, either emitted by the compiler or injected by a loader, so the RSC plugin classifies it as a client boundary. If your toolchain cannot guarantee this, use the wrapper-file pattern above instead. 3. **Keep the discovery manifest fresh.** `bin/shakapacker-precompile-hook` runs the RSC client-reference discovery build and writes the default manifest. A long-running webpack/rspack watch process reads that manifest at startup, so restart the watch after adding a new compiled-language client boundary. If the manifest is older than the server-component registration entry, webpack logs a `[react_on_rails] ... is older than the server component registration entry; RSC client references may be stale` warning at startup; re-run the precompile hook and restart the watch when you see that warning. For direct compiled-output integration, the loader or build step for that language must preserve or inject the client boundary (the `'use client'` directive) before the RSC loader/plugin scans it. If that is not practical, use the wrapper-file pattern above; it is explicit and keeps the React on Rails generated files on the supported path. #### Related RSC documentation - [Create a React Server Component](../../pro/react-server-components/create-without-ssr.md) — step-by-step tutorial for setting up RSC and authoring your first server component. - [Preparing your app for RSC](../migrating/rsc-preparing-app.md) — infrastructure setup when migrating an existing app to RSC. - [RSC Component Patterns](../migrating/rsc-component-patterns.md) — migration patterns for restructuring your component tree as you adopt RSC. - [Embedding Server Components in Client Components](../../pro/react-server-components/inside-client-components.md) — the `RSCRoute` + `wrapServerComponentRenderer` pattern for rendering server components inside a client component tree. - [RSC Troubleshooting](../migrating/rsc-troubleshooting.md) — common errors and fixes. ### Transpiled Languages (ReScript, Reason, etc.) Components compiled by transpiled languages like ReScript produce output files with extensions that include the transpiler identifier (e.g., `.bs.js`, `.res.js`). Auto-bundling discovers these files because they end in `.js`, but it extracts the component name from the full extension — so `MyComponent.bs.js` becomes `MyComponent.bs` instead of `MyComponent`. #### Symptoms If you see errors like: - `Could not find component registered with name MyComponent.bs` - Component renders as `MyComponent.bs` instead of `MyComponent` in error messages Then you likely need the wrapper pattern described below. #### Solution: Wrapper File The simplest solution is a thin wrapper file in your `ror_components` directory: ```text app/javascript/src/Comments/ ├── ReScriptShow.bs.js # ReScript compiler output └── ror_components/ └── ReScriptShow.jsx # Wrapper for auto-registration ``` ```jsx // app/javascript/src/Comments/ror_components/ReScriptShow.jsx import ReScriptShow from '../ReScriptShow.bs.js'; export default ReScriptShow; ``` This pattern works for any transpiled language and requires no gem configuration changes. The wrapper file can use `.js`, `.jsx`, `.ts`, or `.tsx` depending on your project setup. If this wrapper is also an RSC client boundary, put the `'use client'` directive at the top as described in [Compiled-to-JS languages and RSC client references](#compiled-to-js-languages-and-rsc-client-references). > [!NOTE] > While it's possible to add gem-level configuration for additional extensions, the wrapper-file pattern is recommended because it: > > - Works immediately with no configuration changes > - Makes the component registration explicit and visible in the file tree > - Avoids coupling your build pipeline to gem internals that may change between versions ### Using Automated Bundle Generation Feature with already defined packs As of version 13.3.4, bundles inside directories that match `config.components_subdirectory` will be automatically added as entrypoints, while bundles outside those directories need to be manually added to the `Shakapacker.config.source_entry_path` or Webpack's `entry` rules. ## Redux Store Auto-Registration > [!NOTE] > Most applications use React components without Redux. If you don't maintain a legacy Redux app or an advanced multi-island shared store, you can skip this section entirely. In addition to components, React on Rails can automatically register Redux stores based on file system conventions. This eliminates manual `ReactOnRails.registerStore()` calls and generates individual packs for each store. The feature works the same way as component auto-registration. ### Configure Stores Subdirectory Add `stores_subdirectory` to your React on Rails initializer: ```rb config.stores_subdirectory = "ror_stores" ``` This requires `auto_load_bundle` to be enabled (either globally or per helper call) and `nested_entries: true` in `shakapacker.yml`, just like component auto-registration. ### Directory Structure Place store files inside directories matching your configured `stores_subdirectory`: ```text app/javascript/ └── src/ ├── Comments/ │ └── ror_stores/ │ └── commentsStore.js └── Router/ └── ror_stores/ └── routerStore.ts # TypeScript is supported ``` ### Store File Format Each store file must export a store generator function as its default export: ```js // app/javascript/src/Comments/ror_stores/commentsStore.js import { createStore } from 'redux'; import commentsReducer from '../reducers/commentsReducer'; const commentsStore = (props, railsContext) => { return createStore(commentsReducer, props); }; export default commentsStore; ``` ### Usage in Rails Views Use the `redux_store` helper with `auto_load_bundle`: ```erb <%# The store pack is loaded automatically when auto_load_bundle is enabled %> <%= redux_store("commentsStore", props: { comments: @comments }) %> <%= react_component("CommentsContainer", auto_load_bundle: true) %> ``` If `auto_load_bundle` is set globally to `true`, you can omit it from each call: ```erb <%= redux_store("commentsStore", props: { comments: @comments }) %> <%= react_component("CommentsContainer") %> ``` ### Generated Files Running `bundle exec rake react_on_rails:generate_packs` generates: **Client pack** (`app/javascript/packs/generated/commentsStore.js`): ```js import ReactOnRails from 'react-on-rails/client'; import commentsStore from '../../src/Comments/ror_stores/commentsStore.js'; ReactOnRails.registerStore({ commentsStore }); ``` **Server bundle** — stores are also automatically included in the generated server bundle, so server-side rendering with Redux works without manual configuration. ### Name Conflict Detection Component and store names must be unique across both registries. If a component and a store share the same name, pack generation will raise an error: ```text **ERROR** ReactOnRails: The following names are used for both components and stores: myName. This would cause pack file conflicts in the generated directory. Please rename your components or stores to have unique names. ``` Duplicate store names (two store files with the same name in different directories) are also detected and raise an error. ### Server/Client Variants Like components, store files support `.client` and `.server` suffixes. For example, `commentsStore.client.js` will only be used for client-side rendering, and the suffix is stripped from the registered name. ## Troubleshooting ### Common Issues and Solutions #### 1. "Component not found" errors **Problem**: `react_component` helper throws "Component not found" error. **Solutions**: - Ensure your component is in a `ror_components` directory (or your configured `components_subdirectory`) - Run `rake react_on_rails:generate_packs` to generate the component bundles - Check that your component exports a default export: `export default MyComponent;` - Verify the component name matches the directory structure - If using a transpiled language (ReScript, Reason, etc.), see [Transpiled Languages](#transpiled-languages-rescript-reason-etc) — files like `MyComponent.bs.js` register as `MyComponent.bs` instead of `MyComponent` #### 2. CSS not loading (FOUC - Flash of Unstyled Content) **Problem**: Components load but CSS styles are missing or delayed, particularly with server-side rendering and `auto_load_bundle = true`. **Root Cause**: When using `auto_load_bundle = true`, `react_component` calls automatically invoke `append_stylesheet_pack_tag` during rendering. However, Shakapacker requires these appends to execute BEFORE the main `stylesheet_pack_tag` in your layout's `<head>`. Since Rails renders the layout's `<head>` before the `<body>` (where `react_component` calls typically occur), the appends happen too late, causing FOUC. **Solution**: Use the `content_for :body_content` pattern documented in Shakapacker's [Preventing FOUC guide](https://github.com/shakacode/shakapacker/blob/master/docs/preventing_fouc.md#the-content_for-body_content-pattern). This pattern renders your body content first, ensuring all `react_component` auto-appends execute before the `<head>` renders: ```erb <%# Step 1: This block executes first, capturing content AND triggering auto-appends %> <% content_for :body_content do %> <%= react_component "NavigationBarApp", prerender: true %> <div class="container"> <%= yield %> </div> <%= react_component "Footer", prerender: true %> <% end %> <!DOCTYPE html> <html> <head> <%= csrf_meta_tags %> <%= csp_meta_tag %> <%# Step 2: Head renders with all accumulated stylesheet/JS appends %> <%= stylesheet_pack_tag(media: 'all') %> <%= javascript_pack_tag(defer: true) %> </head> <body> <%# Step 3: Finally, the captured body_content is rendered here %> <%= yield :body_content %> </body> </html> ``` **Note**: While defining body content before `<!DOCTYPE html>` may seem counter-intuitive, Rails processes the `content_for` block first (capturing content and triggering appends), then renders the HTML in proper document order. **Alternative**: If the `content_for` pattern doesn't fit your needs, disable auto-loading and manually specify packs: ```ruby # config/initializers/react_on_rails.rb config.auto_load_bundle = false ``` **Additional Resources**: - **Complete FOUC prevention guide**: [Shakapacker Preventing FOUC documentation](https://github.com/shakacode/shakapacker/blob/main/docs/preventing_fouc.md) - **Turbo/Hotwire integration**: [Using auto-bundling with Turbo](../building-features/turbolinks.md#turbo-with-auto-bundling) - same pattern required for Turbo compatibility - **Working example**: [react-webpack-rails-tutorial PR #686](https://github.com/shakacode/react-webpack-rails-tutorial/pull/686) - **Related issue**: [Shakapacker #720](https://github.com/shakacode/shakapacker/issues/720) **Note**: HMR-related FOUC in development mode (dynamic CSS injection) is separate from this SSR auto-loading issue. See Shakapacker docs for details. **Note**: If you're using Tailwind CSS or another utility-first framework and see layout jumps (sidebars collapsing, flex containers stacking), you may need to inline critical CSS. See [Tailwind/Utility-First CSS FOUC](../deployment/troubleshooting.md#type-2-tailwindutility-first-css-frameworks) for the solution. #### 3. "document is not defined" errors during SSR **Problem**: Server-side rendering fails with browser-only API access. **Solutions**: - Use dynamic imports for browser-only libraries: ```jsx useEffect(() => { const loadLibrary = async () => { const { default: BrowserLibrary } = await import('browser-library'); setLibrary(() => BrowserLibrary); }; loadLibrary(); }, []); ``` - Provide fallback/skeleton components during loading - Consider client-only rendering: use `ComponentName.client.jsx` files only #### 4. Bundles not being generated **Problem**: Running `rake react_on_rails:generate_packs` doesn't create files. **Solutions**: - Verify `nested_entries: true` in `shakapacker.yml` - Check that `components_subdirectory` is correctly configured - Ensure components are in the right directory structure: `src/ComponentName/ror_components/ComponentName.jsx` - Make sure you're using the correct source path in Shakapacker config #### 5. Manual pack tags not working after switching to auto-loading **Problem**: Manually specified `javascript_pack_tag` or `stylesheet_pack_tag` break. **Solutions**: - Remove specific pack names from manual pack tags: use `<%= javascript_pack_tag %>` instead of `<%= javascript_pack_tag 'specific-bundle' %>` - Remove manual `append_javascript_pack_tag` calls - `react_component` with `auto_load_bundle: true` handles this automatically - Delete any client bundle entry files (e.g., `client-bundle.js`) that manually register components #### 6. Bundle size issues **Problem**: Large bundles loading when not needed. **Solutions**: - Use component-level bundle splitting - each page loads only needed components - Implement dynamic imports for heavy dependencies - Check bundle analysis with `RAILS_ENV=production NODE_ENV=production bundle exec rails assets:precompile` and examine generated bundle sizes - Consider code splitting within heavy components #### 7. Development vs Production differences **Problem**: Works in development but fails in production. **Solutions**: - **CSS**: Production extracts CSS to separate files, development might inline it - **Source maps**: Check if source maps are causing issues in production - **Minification**: Some code might break during minification - check console for errors - **Environment**: Use `bin/dev prod` to test production-like assets locally #### 8. Component with `.server/.client` variants used with RSC **Problem**: A component with `.server.jsx`/`.client.jsx` file variants is rendered through `RSCRoute` or registered with `registerServerComponent`. This adds unnecessary overhead and can cause the wrong variant (the server version) to load in the browser — the RSC bundle imports the `.server.jsx` file and its chunk reference propagates through the client manifest to the browser. See [When to use `.client` / `.server` variants with RSC](#when-to-use-client--server-variants-with-rsc) for the full rules on when these suffixes are and aren't appropriate in an RSC project. **Solution depends on the component's intended role:** **If the component is a client component** (uses hooks, state, event handlers, or browser APIs): - Ensure it has the `'use client'` directive so it gets registered via `ReactOnRails.register()` instead of `registerServerComponent()` - Do not render it through `RSCRoute` — use `react_component` or `stream_react_component` instead - The `.server/.client` variant pattern works correctly with `react_component` and `stream_react_component` as long as the component is properly registered as a client component **If the component should be a server component** (server-side data fetching, no client interactivity): - Migrate to a single file — delete the `.client.jsx` file, since server components do not run on the client side at all - Adjust the `.server.jsx` variant (or rename it to drop the `.server` suffix) to properly use RSC capabilities: async data fetching, streaming with Suspense, direct access to server-only resources - If the component uses a render function pattern (`export default (props, railsContext) => { ... }`), convert it to a plain React component (`export default function Component(props) { ... }`) or an async component (`export default async function Component(props) { ... }`). Keep Rails-owned data loading in the controller and pass prepared data as props; see [RSC data fetching](../migrating/rsc-data-fetching.md). - Remove the `'use client'` directive if present — server components must not have it **Related**: [GitHub issue #2509](https://github.com/shakacode/react_on_rails/issues/2509), [How to use different files for client and server rendering](../building-features/how-to-use-different-files-for-client-and-server-rendering.md) ### Debug Mode To debug auto-loading behavior, temporarily add logging to see what bundles are being loaded: ```erb <!-- Temporarily add this to your layout to see what gets loaded --> <%= debug(content_for(:javascript_pack_tags)) %> <%= debug(content_for(:stylesheet_pack_tags)) %> ``` This helps verify that components are correctly appending their bundles. ================================================================================ PAGE: https://reactonrails.com/docs/core-concepts/webpack-configuration SOURCE: docs/oss/core-concepts/webpack-configuration.md ================================================================================ # Webpack Configuration: custom setup for Webpack or Shakapacker? ## Webpack vs. Shakapacker [Webpack](https://webpack.js.org) is the JavaScript npm package that prepares all your client-side assets. The Rails asset pipeline used to be the preferable way to prepare client-side assets. [Shakapacker](https://github.com/shakacode/shakapacker) (the official successor of [rails/webpacker](https://github.com/rails/webpacker)) is the Ruby gem that mainly gives us 2 things: 1. View helpers for placing the Webpack bundles on your Rails views. React on Rails depends on these view helpers. 2. A layer of abstraction on top of Webpack customization. The base setup works great for the client-side Webpack configuration. To get a deeper understanding of Shakapacker, watch [RailsConf 2020 CE - Webpacker, It-Just-Works, But How? by Justin Gordon](https://youtu.be/sJLoOpc5LD8). ## Rspack vs. Webpack [Rspack](https://rspack.dev/) is a high-performance JavaScript bundler written in Rust that provides significantly faster builds than Webpack (~20x improvement). React on Rails supports both bundlers through unified configuration. ### Using Rspack Generate a new app with Rspack: ```bash rails generate react_on_rails:install --rspack ``` Or switch an existing app to Rspack: ```bash bin/switch-bundler rspack ``` ### Performance Benefits - **Build times**: ~53-270ms with Rspack vs typical webpack builds - **~20x faster transpilation** with SWC (used by Rspack) - **Faster development** builds and CI runs ### Unified Configuration React on Rails generates unified webpack configuration files that work with both bundlers: **config/webpack/development.js** - Conditional plugin loading: ```javascript const { config } = require('shakapacker'); if (config.assets_bundler === 'rspack') { // Rspack uses @rspack/plugin-react-refresh const ReactRefreshPlugin = require('@rspack/plugin-react-refresh'); clientWebpackConfig.plugins.push(new ReactRefreshPlugin()); } else { // Webpack uses @pmmmwh/react-refresh-webpack-plugin const ReactRefreshWebpackPlugin = require('@pmmmwh/react-refresh-webpack-plugin'); clientWebpackConfig.plugins.push(new ReactRefreshWebpackPlugin()); } ``` **config/webpack/serverWebpackConfig.js** - Dynamic bundler detection: ```javascript const { config } = require('shakapacker'); const bundler = config.assets_bundler === 'rspack' ? require('@rspack/core') : require('webpack'); // Use bundler-specific APIs serverWebpackConfig.plugins.unshift(new bundler.optimize.LimitChunkCountPlugin({ maxChunks: 1 })); ``` ### Configuration in shakapacker.yml Rspack configuration is controlled via `config/shakapacker.yml`: ```yaml default: &default assets_bundler: 'rspack' # or 'webpack' webpack_loader: 'swc' # Rspack works best with SWC ``` The `bin/switch-bundler` script automatically updates this configuration when switching bundlers. ### Server Bundle Configuration (Shakapacker 9.0+) **Recommended**: For Shakapacker 9.0+, use `private_output_path` in `shakapacker.yml` for server bundles: ```yaml default: &default # ... other config ... private_output_path: ssr-generated ``` This provides a single source of truth for server bundle location. React on Rails automatically detects this configuration, eliminating the need to set `server_bundle_output_path` in your React on Rails initializer. In your `config/webpack/serverWebpackConfig.js`: ```javascript const { config } = require('shakapacker'); serverWebpackConfig.output = { filename: 'server-bundle.js', globalObject: 'this', path: config.privateOutputPath, // Automatically uses shakapacker.yml value }; ``` **Benefits:** - Single source of truth in `shakapacker.yml` - Automatic synchronization between webpack and React on Rails - No configuration duplication - Better maintainability **For older Shakapacker versions:** Use hardcoded paths and manual configuration as shown in the generator templates. Per the maintained SSR + HMR tutorial repo listed in [Examples and migration references](../getting-started/examples-and-references.md), you should consider keeping your codebase mostly consistent with the defaults for [Shakapacker](https://github.com/shakacode/shakapacker). # React on Rails Version 9 of React on Rails added support for the Shakapacker (`rails/webpacker` of that time) view helpers so that Webpack produced assets would no longer pass through the Rails asset pipeline. As part of this change, React on Rails added a configuration option to support customization of the node_modules directory. This allowed React on Rails to support the Shakapacker configuration of the Webpack configuration. A key decision in your use React on Rails is whether you go with the Shakapacker default setup or the traditional React on Rails setup of putting all your client side files under the `/client` directory. While there are technically 2 independent choices involved, the directory structure and the mechanism of Webpack configuration, for simplicity sake we'll assume that these choices go together. ## Option 1: Default Generator Setup: Shakapacker app/javascript Typical Shakapacker apps have a standard directory structure documented in the [Shakapacker README](https://github.com/shakacode/shakapacker/blob/master/README.md#configuration-and-code). If you follow [the basic tutorial](../getting-started/tutorial.md), you will see this pattern in action. In order to customize the Webpack configuration, consult the [Shakapacker webpack customization docs](https://github.com/shakacode/shakapacker#webpack-configuration). The _advantage_ of using Shakapacker to configure Webpack is that there is very little code needed to get started, and you don't need to understand really anything about Webpack customization. ## Option 2: Traditional React on Rails using the /client directory Until version 9, all React on Rails apps used the `/client` directory for configuring React on Rails in terms of the configuration of Webpack and location of your JavaScript and Webpack files, including the `node_modules` directory. Version 9 changed the default to `/` for the `node_modules` location using this value in `config/initializers/react_on_rails.rb`: `config.node_modules_location`. You can access values from `config/shakapacker.yml`: ```js const { config, devServer } = require('shakapacker'); ``` You will want to consider using some of the same values set in these files: - https://github.com/shakacode/shakapacker/blob/master/package/environments/base.ts - https://github.com/shakacode/shakapacker/blob/master/package/environments/development.ts ================================================================================ PAGE: https://reactonrails.com/docs/core-concepts/execjs-limitations SOURCE: docs/oss/core-concepts/execjs-limitations.md ================================================================================ # ExecJS Limitations React on Rails uses [ExecJS](https://github.com/rails/execjs) as the default server-side rendering engine. ExecJS provides a common interface to several JavaScript runtimes (Node.js, mini_racer, etc.) and works well for basic server rendering, but it has important limitations to understand. ## How ExecJS Works ExecJS evaluates your server bundle in an isolated JavaScript context. It calls your render function synchronously, collects the resulting HTML string, and returns it to Rails. This synchronous model is the root of most limitations — ExecJS cannot wait for asynchronous operations to complete. ExecJS auto-detects the best available runtime via its `best_available` method, checking runtimes such as mini_racer, Bun, and Node.js. The exact priority can vary by ExecJS version (for example, Bun support was added in newer releases), so verify against the version you're running. Node.js is not guaranteed: ExecJS may choose a higher-priority runtime when one is available. You can override runtime selection with the `EXECJS_RUNTIME` environment variable. All runtimes share the same synchronous limitations described below. See the [ExecJS readme](https://github.com/rails/execjs/blob/master/README.md) for available runtimes. ## Timer and Async Limitations ### Timer Functions (`setTimeout`, `setInterval`, `clearTimeout`, `clearInterval`) ExecJS does not support `setTimeout`, `setInterval`, `clearTimeout`, or `clearInterval`. These functions rely on an event loop, which ExecJS does not provide. React on Rails injects stubs for `setTimeout`, `setInterval`, and `clearTimeout` that silently drop calls to those APIs. `clearInterval` is **not** stubbed by React on Rails, so behavior depends on the ExecJS runtime: in `mini_racer` it can raise a `ReferenceError`, while Node-based runtimes provide `clearInterval`. With `trace: true` in your configuration, the three stubs log a warning to `console.error` with a stack trace; otherwise, calls are silently dropped. **What you'll see:** Timer callbacks are never executed. If `trace` is enabled, you'll see messages like: ```text [React on Rails Rendering] setTimeout is not defined for server rendering. ``` **Why this matters:** Many libraries use timers internally for debouncing, animations, polling, or deferred execution. When these libraries run during server rendering with ExecJS, the timer callbacks are silently dropped, which can cause missing content or unexpected behavior. **Workarounds:** ```javascript // Guard timer calls with an environment check if (typeof window !== 'undefined') { setTimeout(() => doSomething(), 100); } // Or use useEffect, which only runs on the client useEffect(() => { const timer = setTimeout(() => doSomething(), 100); return () => clearTimeout(timer); }, []); ``` ### Promises and Async/Await ExecJS cannot wait for Promises to resolve. Since the rendering call is synchronous, any data fetching or asynchronous initialization that relies on Promises will not complete before the HTML is returned. **What fails:** ```javascript // This component will render before data loads async function UserProfile({ userId }) { const data = await fetch(`/api/users/${userId}`); // Never completes in ExecJS return <div>{data.name}</div>; } ``` > **React on Rails note:** Even on the React on Rails Pro Node renderer, fetching application data from the component bypasses the Rails controller path where authorization, caching, tenancy, and instrumentation usually live. Prefer Rails-prepared props, or Pro streamed async props, for request-specific data. **Workaround:** Pass all required data as props from Rails rather than fetching it client-side during rendering: ```ruby # In your Rails controller @props = { user: User.find(params[:id]).as_json } ``` ```erb <%= react_component('UserProfile', props: @props, prerender: true) %> ``` ### File System Access ExecJS does not provide `fs`, `path`, or other Node.js built-in modules. Code that reads configuration files, templates, or other resources from the file system will fail. ## The `window` Object ExecJS does not provide a `window`, `document`, or any DOM API. Server rendering runs in a headless JavaScript context with no browser environment. **Common error messages:** ```text ReferenceError: window is not defined ReferenceError: document is not defined ``` **Workarounds:** ```javascript // Check before accessing const isClient = typeof window !== 'undefined'; const screenWidth = isClient ? window.innerWidth : 1200; // Better: use useEffect for DOM access useEffect(() => { const width = window.innerWidth; setWidth(width); }, []); ``` See [Client vs. Server Rendering](./client-vs-server-rendering.md) for more on handling browser-only code. ## Missing Globals in `mini_racer` The `mini_racer` runtime provides a bare V8 isolate without Node.js globals or Web APIs. Several APIs that React and React on Rails depend on are unavailable: ### `TextEncoder` / `TextDecoder` `mini_racer`'s V8 isolate does not include the `TextEncoder` or `TextDecoder` Web APIs. React DOM Server (18+) requires `TextEncoder` internally, so when using `mini_racer` you will encounter: ```text ReferenceError: TextEncoder is not defined ``` See [this solution](https://github.com/shakacode/react_on_rails/issues/1457#issuecomment-1165026717) for a polyfill approach. ### `Buffer` Node.js `Buffer` is not available in `mini_racer`. The React on Rails OSS package does not use `Buffer` in its ExecJS rendering path, so this is unlikely to cause errors for most users. If your own server-rendered code calls `Buffer` directly, you can polyfill it by installing the [`buffer`](https://www.npmjs.com/package/buffer) npm package and adding a `ProvidePlugin` entry to your server webpack config: ```js // in your server webpack config — add to the existing plugins array const { ProvidePlugin } = require('webpack'); serverWebpackConfig.plugins.push(new ProvidePlugin({ Buffer: ['buffer', 'Buffer'] })); ``` ### Practical Impact Because React DOM Server 18+ requires `TextEncoder` (which `mini_racer` does not provide), **`mini_racer` is effectively unsupported for server rendering with React 18 or later** unless you supply your own `TextEncoder` polyfill. If you are using React 18+, consider switching to the Node.js ExecJS runtime or upgrading to the [Node Renderer](../building-features/node-renderer/basics.md). ## Pool Size Constraints On MRI Ruby, `server_renderer_pool_size` must stay at 1 to avoid deadlocks. This is because the combination of ExecJS contexts, the `ConnectionPool` gem, and MRI's threading model can cause deadlocks when multiple threads contend for JavaScript contexts (see [#1438](https://github.com/shakacode/react_on_rails/issues/1438)). JRuby users can increase the pool size for concurrent rendering thanks to JRuby's true multi-threading support. ```ruby # config/initializers/react_on_rails.rb ReactOnRails.configure do |config| config.server_renderer_pool_size = 1 # MRI (default) # config.server_renderer_pool_size = 5 # JRuby config.server_renderer_timeout = 20 # seconds end ``` ## Debugging ExecJS Errors Enable `trace` mode to get detailed logging for timer calls and other server rendering issues: ```ruby ReactOnRails.configure do |config| config.trace = true config.logging_on_server = true config.replay_console = true config.raise_on_prerender_error = Rails.env.development? end ``` With these settings, ExecJS errors will: - Raise exceptions in development so you catch them immediately - Log server-side rendering output to `Rails.logger.info` - Replay server-side console messages in the browser console (via `replay_console`) See the [Configuration Reference](../configuration/README.md) for details on these options. ## Migrating to the Node Renderer If ExecJS limitations are blocking your application, the [Node Renderer](../building-features/node-renderer/basics.md) (a React on Rails Pro feature) eliminates these constraints by running a dedicated Node.js process for server rendering. The Node renderer supports: - Full async/await and Promise resolution - `setTimeout` and `setInterval` (requires setting `RENDERER_STUB_TIMERS=false`; timers are stubbed by default) - Streaming SSR with `renderToPipeableStream` - React Server Components - Node.js built-in modules (requires setting `RENDERER_SUPPORT_MODULES=true`) - Multi-worker concurrency The Node renderer typically delivers significantly faster SSR compared to ExecJS, with real-world results like Popmenu's [73% reduction in response times](https://www.shakacode.com/recent-work/popmenu/). See [OSS vs Pro](../getting-started/oss-vs-pro.md) for a full feature comparison. ================================================================================ PAGE: https://reactonrails.com/docs/core-concepts/performance-benchmarks SOURCE: docs/oss/core-concepts/performance-benchmarks.md ================================================================================ # Performance Benchmarks This page covers the performance characteristics of React on Rails across different rendering strategies, with data from real-world deployments and comparative benchmarks. ## SSR Performance: ExecJS vs Node Renderer The default ExecJS renderer evaluates JavaScript synchronously inside a single-threaded pool. The [Node Renderer](../building-features/node-renderer/basics.md) (React on Rails Pro) runs a dedicated Node.js master process with worker processes (via `cluster.fork()`), providing dramatically better throughput. ### Key Differences | Metric | ExecJS (mini_racer) | ExecJS (Node.js runtime) | Node Renderer (Pro) | | ----------------- | ----------------------------- | ----------------------------- | -------------------------- | | Architecture | V8 isolate in Ruby process | New process per eval call | Persistent Node.js workers | | Concurrency (MRI) | Single-threaded (pool size 1) | Single-threaded (pool size 1) | Multi-worker | | Async support | None | None | Full (Promises, timers) | | Streaming SSR | Not supported | Not supported | Supported | | RSC support | Not supported | Not supported | Supported | | Typical speedup | Baseline | Comparable | 3-10x over ExecJS | The Node Renderer's persistent process supports full async rendering and multi-worker concurrency, which are the primary sources of the performance difference. Popmenu reported a [73% decrease in response times](#popmenu) after switching to Pro. ExecJS is limited to synchronous rendering within a single-threaded pool, so the gap widens for pages with many async data sources or large component trees. ## Bundle Splitting Impact React on Rails supports [code splitting](../building-features/code-splitting.md) (Pro feature) to reduce the amount of JavaScript sent to the browser. The impact depends on your application's structure: ### Client Bundle Size Code splitting with dynamic `import()` breaks your application into smaller chunks loaded on demand: - **Without splitting:** A single bundle contains all components, even those not needed on the current page - **With splitting:** Only the components required for the current route are loaded initially; others load on navigation For applications with many routes and components, code splitting can substantially reduce initial bundle size. The actual reduction depends on how much code is shared across routes — apps with mostly independent route content typically see larger gains. ### Server Bundle Size Server bundles are not typically split because the server can load the full bundle once at startup. However, with React Server Components, server-only dependencies are excluded from the client bundle entirely, which compounds the benefits of code splitting. ## Streaming SSR Benefits [Streaming SSR](../building-features/streaming-server-rendering.md) (Pro feature) uses React's `renderToPipeableStream` to send HTML progressively as components resolve: ### Time to First Byte (TTFB) | Rendering Strategy | TTFB | Full Page Load | | ---------------------------------- | ------------------------- | --------------------------- | | Client-side only | Fast (empty shell) | Slow (fetch + render) | | Traditional SSR (`renderToString`) | Slow (waits for all data) | Fast (complete HTML) | | Streaming SSR | Fast (shell immediately) | Progressive (chunks arrive) | Streaming SSR provides the best of both approaches: the browser receives the initial HTML shell immediately (fast TTFB) while data-dependent sections stream in as they resolve. This is especially valuable for pages with multiple independent data sources. ### Selective Hydration With streaming SSR and React 18+, components can hydrate independently as their JavaScript loads: - Navigation can become interactive while main content is still streaming - User interactions automatically prioritize hydration of the clicked component - No single "hydration wall" where the entire page freezes **Note:** By default, React on Rails uses `defer` scripts which delay all hydration until the page finishes streaming. To enable selective hydration, configure your initializer: ```ruby config.generated_component_packs_loading_strategy = :async ``` See [Selective Hydration in Streamed Components](../../pro/react-server-components/selective-hydration-in-streamed-components.md) for complete details. ## React Server Components Impact React Server Components (Pro feature) provide additional performance benefits on top of streaming SSR: ### Client Bundle Reduction Server components and their dependencies are excluded from the client bundle. In practice, this means: ```jsx // These imports stay server-side — zero client cost import { format } from 'date-fns'; // ~30KB import { marked } from 'marked'; // ~35KB import numeral from 'numeral'; // ~25KB ``` Applications that use heavy formatting, parsing, or data-processing libraries on the server side see the largest gains. Frigade reported a [62% reduction in client-side bundle size](https://frigade.com/blog/bundle-size-reduction-with-rsc-and-frigade) after migrating to RSC. ### No Hydration for Server Components Server components produce HTML that does not need hydration — they have no client-side JavaScript. Only client components (those with `'use client'`) require hydration. This reduces Total Blocking Time and improves Time to Interactive. ## Benchmarking RSC Against Warm SSR Caches React Server Components reduce client JavaScript, hydration work, and duplicated data-fetching paths. They do not automatically beat an already-warm SSR cache on every first-paint metric. If the existing page uses [`cached_react_component` or `cached_react_component_hash`](../building-features/caching.md#level-2-fragment-caching), the fair baseline is a warm fragment-cache hit. If it uses [`config.prerender_caching = true`](../building-features/caching.md#level-1-prerender-caching) without fragment caching, the fair baseline is a warm prerender-cache hit. Do not compare RSC against an uncached SSR request unless that uncached state is the production baseline. This distinction matters most for mostly static public pages. On a fragment-cache hit, React on Rails Pro can skip prop assembly, JSON serialization, and JavaScript evaluation. Fragment-caching helpers skip the prerender cache for that render call because the full fragment is already cached. On a prerender-cache hit, props are still assembled and serialized, but the JavaScript render result is reused. Either warm path can be very hard for an RSC conversion to beat on TTFB, FCP, or LCP because there may be little server-rendering work left to remove. ### Static landing-page pattern A cache-optimized landing page often looks like this: ```erb <% cache_key = [ "welcome-page", current_user, device_type_cache_key, release_cache_key, cms_last_updated_at, I18n.locale ] rendered = cached_react_component_hash( "WelcomePage", cache_key:, auto_load_bundle: false ) do build_welcome_page_props end %> <% append_javascript_pack_tag("generated/WelcomePage") %> <% append_stylesheet_pack_tag("generated/WelcomePage") %> <%= preload_pack_asset("generated/WelcomePage.css") %> <%= rendered["componentHtml"] %> <%= content_for :script_tags, rendered["consoleReplayScript"] %> ``` In this shape, `auto_load_bundle: false` keeps asset loading explicit so the page can preserve head ordering and preload the critical CSS. That per-call option only disables automatic loading when the app has not enabled `config.auto_load_bundle` globally; if the global setting is `true`, preserve the resulting asset behavior in both the SSR baseline and the RSC experiment. An RSC experiment must keep the same data, release, device, locale, CMS state, CSS delivery, font preloads, and hero/image priority before claiming that RSC changed rendering performance. Otherwise the comparison is apples to oranges: a lower JavaScript payload or lower Total Blocking Time can coexist with worse LCP if the conversion delays CSS, fonts, or the LCP resource. ### Cache-state matrix Measure each relevant state intentionally and label it in the report: | Variant | How to prepare it | What it answers | | ----------------- | --------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | | Cold uncached SSR | Clear fragment/prerender caches and measure the first request for the SSR page | Cost of prop assembly, serialization, and JavaScript rendering before caching | | Warm cached SSR | Prime the exact cache key, then measure repeated hits; log `RORP_CACHE_HIT` when available | Repeat-visitor/server steady state for the existing cached implementation | | RSC cold | Clear relevant Rails/browser/renderer caches and measure the first RSC request | First-hit cost of the RSC render, Flight payload generation, and asset discovery | | RSC warm | Prime the RSC route under the same data and browser-cache policy, then measure repeated navigations | Steady state for RSC rendering, hydration, Flight payload, and cached assets | Use the same production build mode, data snapshot, asset host, CDN/cache policy, browser cache policy, throttling, and sample order for control and experiment. Include both desktop and mobile runs, and keep visual regression checks in the same gate as performance checks so a faster page is still the same page. ### Reading RSC wins and non-wins RSC is most likely to win when the page currently pays a large browser cost: heavy client bundles, long hydration tasks, large client-only data parsing, repeated interactive subtrees that can become Server Components, or server-only formatting/parsing libraries that can leave the client bundle entirely. Judge those migrations by Total Blocking Time, long tasks, JavaScript bytes, hydration/interactivity marks, and navigation responsiveness in addition to LCP. Warm cached SSR may already be close to optimal when the page is static or cacheable, the cache key is stable, prop assembly is skipped by `cached_react_component_hash`, critical CSS/fonts are manually preloaded, and the remaining client JavaScript is already small. In that case, an RSC conversion can still be valuable for maintainability or lower browser work, but the benchmark should say that clearly instead of framing a warm-cache first-paint tie as an RSC failure. For RSC pages, also measure what moved into the HTML response. The initial Flight payload is usually embedded in the HTML stream rather than fetched as a separate `/rsc_payload/*` resource, so `PerformanceResourceTiming` may show fewer JavaScript requests while the navigation response grows. Pair JavaScript byte counts with HTML transfer size, Flight payload bytes, FCP/LCP, TBT, and server/renderer timing before drawing conclusions. For PR evidence, use the [RSC Performance Validation Playbook](../migrating/rsc-performance-validation.md). It covers same-machine control/experiment setup, visual regression gates, stable package-stack evidence, archived benchmark artifacts, and the metrics checklist reviewers need. For public pages that become mostly static RSC shells, pair the benchmark with [Mostly Static RSC Shell With a Tiny Sidecar](../migrating/rsc-static-shell-sidecar.md) so JavaScript byte reductions do not hide missing behavior. ## Real-World Results > [!NOTE] > This section links to a public live demo first, then covers a non-production local directional benchmark, then a production case study. For validated, > at-scale results, see the [Production Case Study: Popmenu](#popmenu) below. ### Marketplace demo {#public-marketplace-rsc-demo} The [Marketplace demo](https://rsc.reactonrails.com/) is a public, inspectable React on Rails Pro + RSC demo showing the same page families rendered with traditional SSR, client rendering, and React Server Components. See the [Live Demo and Evidence](../../pro/react-server-components/index.md#live-demo-and-evidence) section for the canonical link inventory and caveats: performance showcase, raw Lighthouse reports, bundle-size breakdowns, the `/why-rsc` walkthrough, and the demo source. ### Non-Production Local Directional Benchmark: Gumroad-Style RSC Demo (April 2026) {#gumroad-style-rsc-demo} The [Gumroad-style RSC benchmark demo](https://github.com/shakacode/react-on-rails-demo-gumroad-rsc) is a public ShakaCode comparison repo modeled after a creator-dashboard surface with product listings and sales metrics, not an official Gumroad integration. The benchmark methodology, earlier-run artifacts, and the April 30, 2026 production-like local run with median and p95 timings are documented in [`docs/performance-findings.md`](https://github.com/shakacode/react-on-rails-demo-gumroad-rsc/blob/010b3564398dbb9c8f5caafab25daed65b6f425c/docs/performance-findings.md#production-like-compiled-asset-8-cycle-repeat) on stacked demo PR [shakacode/react-on-rails-demo-gumroad-rsc#12](https://github.com/shakacode/react-on-rails-demo-gumroad-rsc/pull/12); the per-run JSON files remain gitignored local artifacts ([Issue 3263](https://github.com/shakacode/react_on_rails/issues/3263) tracks publishing per-run distribution data). It measures the same reduced presenter data and outer layout across two routes. The comparison changes three axes at once (RSC, the Pro Node renderer, and SSR), so the deltas cannot be attributed to any single factor. The routes are: - Inertia-style control: `/dashboard/inertia_demo` (uses the actual `inertia_rails` gem; no Pro renderer or SSR) - React on Rails Pro + React Server Components: `/dashboard/rsc_demo` > [!NOTE] > Both routes use the same Shakapacker with Rspack page-asset build, so this is a route-level comparison rather than a > bundler comparison. It also does not isolate a renderer-only baseline: the Inertia route has no React on Rails Pro > renderer or SSR, while the RSC route uses the Pro Node renderer. Treat the deltas as the combined route-level effect; > see the [SSR Performance table](#ssr-performance-execjs-vs-node-renderer) for the renderer baseline. The April 30, 2026 local benchmark used eight cycles, each measuring both routes in alternating cycle order (cycle 1: Inertia then RSC; cycle 2: RSC then Inertia; cycle 3: Inertia then RSC; and so on), producing sixteen measured runs total — eight per route. Before each measured run, the harness sent one warmup request to the route being measured. Conditions: - Compiled page assets from the same Shakapacker with Rspack configuration for both routes - Compiled RSC demo bundles - Rails server without the Shakapacker dev server running - Dedicated React on Rails Pro Node renderer on `RENDERER_PORT=3800` - Chrome 147 with matching ChromeDriver 147 > [!WARNING] > The original April 30, 2026 local run did not preserve `RAILS_ENV`, hardware/OS, Ruby/Node/Rails versions, or > browser-cache state between measured runs, and those values are not recoverable for that run. The absolute timing > values may therefore include `RAILS_ENV=development` overhead (no eager loading, active code reloader, no asset > caching), and unknown browser-cache state between measured runs affects repeatability. The single warmup request > before each measured run may also be insufficient for the Pro Node renderer worker pool to reach JIT and > RSC-payload-compilation steady state, which is more likely to make the RSC route look slower than its steady-state > performance than to inflate its advantage. Treat these numbers as directional signals rather than a stable baseline. > [Issue 3253](https://github.com/shakacode/react_on_rails/issues/3253) tracks a deployed/staging repeat that will > publish full environment metadata; see [Environment metadata to capture for a new > run](#gumroad-rsc-env-metadata-checklist) below for the required fields. The median results showed this directional signal. The source artifact's navigation-duration metric comes from its Playwright harness and may differ from `PerformanceNavigationTiming.duration`. | Source | Metric | Inertia demo | RSC demo | Delta % (negative = RSC faster) | | ------- | ----------------------------------------------- | -----------: | -------: | ------------------------------: | | Browser | Navigation duration | 775ms | 607ms | -21.7% | | Browser | Largest Contentful Paint | 794ms | 634ms | -20.2% | | Browser | `responseEnd` | 645ms | 589ms | -8.7% | | Rails | Controller `action_total` (Rails wall time) [†] | 347ms | 339ms | -2.3% | [†] `action_total` scope is unconfirmed; do not use it to infer the server-rendering split — see the paragraph below. `action_total` is the Rails wall-time field from the raw benchmark artifact, not a browser Performance API metric. The artifact does not yet publish enough logger or extraction-script context to confirm whether it is the full `process_action` duration including rendering or a narrower controller-action field, so do not use it to infer the server-rendering split. Because the Pro Node renderer runs in a separate OS process, Rails wall time may also exclude RSC rendering cost that the Inertia control keeps in-process, so the two `action_total` values may not measure identical scopes of work. The source artifact publishes median and p95 for `responseEnd` but not for `action_total`; [Issue 3263](https://github.com/shakacode/react_on_rails/issues/3263) tracks publishing per-run distribution data. The navigation-duration gain (-21.7%) was larger than the `responseEnd` gain (-8.7%), which is consistent with the RSC route delivering fully server-rendered HTML — the browser has minimal client-side hydration work after `responseEnd`, while the Inertia control must hydrate the React component tree on the client. Because the navigation-duration value comes from the source artifact's Playwright harness rather than `PerformanceNavigationTiming.duration`, the two metrics are not from the same timing source and a direct `navigation duration - responseEnd` subtraction is not reported here. The same April 30, 2026 benchmark also captured per-navigation resource bytes via the `PerformanceResourceTiming` API for resources whose URL contains `/packs/` and ends in `.js`, plus the HTML response via `PerformanceNavigationTiming`. Medians across n=8 measured runs per route: | Metric | Inertia demo | RSC demo | | ------------------------------------------------------------------- | -----------: | -------: | | Page-specific JS requests (`/packs/*.js`) | 6 | 1 | | Page-specific JS transfer (wire bytes) | 3,587 B | 0 B | | Page-specific JS encoded body | 3,287 B | 0 B | | Page-specific JS decoded body | 10,947 B | 0 B | | HTML response transfer (`PerformanceNavigationTiming.transferSize`) | 14,523 B | 12,673 B | These transfer-size values are warmed-cache wire bytes, not cold-cache bundle totals. The harness sends one warmup request to the measured route before each measured run, which primes Chrome's HTTP disk cache so the Resource Timing API reports `transferSize: 0` for assets already cached by the warmup. For the Inertia demo, 5 of the 6 `/packs/` JS files (webpack-runtime, webpack-commons, two vendor chunks, and the inertia bundle) are served from disk cache on the measured run; the freshly-fetched bytes (~3.3 KB compressed, ~10.9 KB decompressed) come from a route-specific page chunk. For the RSC demo, the single page-specific JS file (the React on Rails Pro client bootstrap) is served from cache on the measured run, so its measured `transferSize` is `0`. The RSC route's Flight payload is not delivered as a separate `/rsc_payload/*` request in this benchmark; it is inlined in the HTML response, so the HTML transfer column (12,673 B vs 14,523 B for the Inertia control) captures most of the route-specific data delivered per navigation. The combined route-specific new bytes per warmed-cache navigation are roughly ~18.1 KB for the Inertia control (~3.6 KB JS + ~14.5 KB HTML) and ~12.7 KB for the RSC demo (~0 KB JS + ~12.7 KB HTML) — a ~30% warmed-cache wire-byte reduction, materially smaller than the -83% page-specific JS request-count reduction implies. Cold-cache bundle totals (what a first-time visitor downloads before any caching kicks in) are not captured by this benchmark methodology and remain a follow-up; see [Issue 3259](https://github.com/shakacode/react_on_rails/issues/3259). - _All timing values are medians from the raw benchmark artifact values (n=8 per route); sample size is too small to establish statistical significance._ - _The published `responseEnd` p95 (731ms Inertia vs 768ms RSC, see the [`responseEnd` p95 counter-signal](#gumroad-rsc-worst-case-responseend) below) is larger than the other route's median in both directions (Inertia p95 731ms > RSC median 589ms; RSC p95 768ms > Inertia median 645ms), so the per-run `responseEnd` ranges overlap and the median -8.7% RSC-favored delta is consistent with measurement noise rather than a stable RSC win on this metric._ - _The source artifact does not publish a p95 or per-run distribution for `action_total`, so its -2.3% median delta cannot be distinguished from measurement noise at n=8._ #### `responseEnd` p95 counter-signal {#gumroad-rsc-worst-case-responseend} | Metric | Inertia demo | RSC demo | Delta % (negative = RSC faster) | | ----------------------- | -----------: | -------: | ------------------------------: | | `responseEnd` p95 (n=8) | 731ms | 768ms | +5.1% | At n=8 the p95 is interpolated near the second-worst observed value rather than the maximum, but with only eight samples it remains a coarse tail estimate rather than a stable population p95. It shows a +5.1% RSC regression on tail `responseEnd` (high variance is expected at n=8), indicating the Inertia control had a faster tail `responseEnd` than the RSC route on this run. Use these numbers as a case-study signal, not a universal performance claim. The RSC route combines RSC, the Pro Node renderer, and SSR, while the Inertia control has none of those three factors. With that caveat, the RSC route showed faster median navigation duration and LCP on the measured routes. The `responseEnd` p95 counter-signal favored the Inertia control. A stable deployed repeat, renderer-internal timing, environment metadata, and distribution artifacts are still required before making stronger production-performance claims. See [Issue 3128](https://github.com/shakacode/react_on_rails/issues/3128) and [Issue 3144](https://github.com/shakacode/react_on_rails/issues/3144) for the ongoing tracking discussion. #### Environment metadata to capture for a new run {#gumroad-rsc-env-metadata-checklist} For any new local or staging Gumroad benchmark run, record the following so readers can calibrate the results. Missing fields should be listed explicitly rather than left implied. - **Environment:** `RAILS_ENV`, `NODE_ENV` - **Hardware/OS:** machine model, CPU, RAM, OS version - **Tool versions:** Ruby, Node.js, Rails, React on Rails, React on Rails Pro, Shakapacker, Rspack, Chrome, ChromeDriver - **Cache state:** Rails fragment/SQL cache mode, browser cache behavior between measured runs (cold vs warm), Pro Node renderer cache state - **Run protocol:** warmup requests per route, measured runs per route, alternation pattern, total wall-clock duration - **Renderer setup:** dedicated vs shared Pro Node renderer, `RENDERER_PORT`, worker count, eager-loading status - **Renderer-internal timing:** whether `config.tracing = true` was enabled on the Pro initializer, or `Server-Timing` was emitted for the RSC render/payload path - **Distribution:** raw per-run values for each metric (not just medians), enough to publish variance and tail values [Issue 3253](https://github.com/shakacode/react_on_rails/issues/3253) tracks applying this checklist to a stable deployed/staging repeat. ### Production Case Study: Popmenu {#popmenu} Popmenu, a restaurant platform serving tens of millions of SSR requests daily, adopted React on Rails Pro and reported: - **73% decrease** in average response times - **20-25% lower** Heroku hosting costs - Stable performance under high traffic with the Node Renderer's worker pool See the [full case study](https://www.shakacode.com/recent-work/popmenu/). ## Measuring Your Own Performance ### Key Metrics to Track - **Time to First Byte (TTFB):** How quickly the server begins sending HTML - **Largest Contentful Paint (LCP):** When the main content becomes visible - **Total Blocking Time (TBT):** Time the main thread is blocked during page load - **Client bundle size:** Total JavaScript downloaded by the browser - **Server render time:** Time spent in the SSR process (not logged by default — measure wall clock time in Ruby around the render call; on Pro, enable `config.tracing = true` in `config/initializers/react_on_rails_pro.rb` to log render timings) ### Tools - **Chrome DevTools Performance tab:** Profile page load and hydration timing - **Lighthouse:** Automated performance scoring with LCP, TBT, and other Core Web Vitals - **`webpack-bundle-analyzer`:** Visualize bundle composition and identify large dependencies - **Rails server logs:** Server-side console messages replayed to `Rails.logger` when `config.logging_on_server = true` - **Node Renderer logs:** Renderer lifecycle and error details controlled by `RENDERER_LOG_LEVEL` (Pro) ## JSON Serialization Performance React on Rails serializes component props to JSON before passing them to the JavaScript renderer. The performance of this serialization depends on which version of Ruby's `json` gem you have installed. ### Upgrading the JSON Gem Ruby's bundled `json` gem (versions 2.5–2.7) is slower than it needs to be. Version 2.8.0 introduced a major performance rewrite that makes it **2x faster** for large payloads. To get this improvement, add to your `Gemfile`: ```ruby gem 'json', '>= 2.8' ``` ### Benchmark Results For a ~3 MB props payload on Ruby 3.3: | JSON Gem Version | Serialization Time | Improvement | | ----------------- | ------------------ | --------------- | | 2.7.2 (bundled) | 21.5 ms | Baseline | | 2.19.8 (upgraded) | 10.2 ms | **2.1x faster** | The improvement scales with payload size — approximately **3-4 ms saved per MB** of props data. ### When This Matters This optimization is most impactful for: - **Large component trees** with many props - **Data-heavy pages** (dashboards, tables, lists) - **Traditional SSR** where props are serialized before rendering For typical pages with small props (under 100 KB), the difference is negligible (< 1 ms). ### Compatibility JSON gem 2.19.8 (latest) supports Ruby 2.7+, so it works with all Ruby versions supported by React on Rails. ## Related Documentation - [ExecJS Limitations](./execjs-limitations.md) — constraints of the default rendering engine - [Streaming Server Rendering](../building-features/streaming-server-rendering.md) — setup and best practices - [Code Splitting](../building-features/code-splitting.md) — route-based bundle splitting - [Node Renderer Basics](../building-features/node-renderer/basics.md) — Pro Node.js renderer setup - [OSS vs Pro](../getting-started/oss-vs-pro.md) — feature comparison - [React Server Components](../../pro/react-server-components/index.md) — RSC overview and guides ================================================================================ PAGE: https://reactonrails.com/docs/building-features/react-router SOURCE: docs/oss/building-features/react-router.md ================================================================================ # Using React Router React on Rails supports React Router for client-side routing. This guide shows how to integrate React Router into your React on Rails application. > Looking for TanStack Router? See [Using TanStack Router](./tanstack-router.md). **Important:** The React on Rails generator does not install React Router. You'll need to add it to your project manually. > React Router support in React on Rails is a manual integration pattern. > If you want a first-class SSR helper with router dehydration/hydration, use TanStack Router with React on Rails Pro. ## Compatibility Note If you're using Turbo (Rails 7+) or Turbolinks (Rails 6 and earlier), be aware that both React Router and Turbo/Turbolinks handle browser navigation and the back button. These two routing systems can conflict. Consider: - Using one routing approach (either Turbo OR React Router, not both) - Disabling Turbo for pages using React Router with `data-turbo="false"` - Using code splitting instead of client-side routing for similar performance benefits If you successfully integrate both, please share your solution with the community! For more details, see [Turbo/Turbolinks Guide](./turbolinks.md). ## Installation First, add React Router v6 to your project: ```bash npm install react-router-dom@^6.0.0 # or: yarn add react-router-dom@^6.0.0 # or: pnpm add react-router-dom@^6.0.0 ``` **Why React Router v6?** React Router v7 has merged with Remix and uses a different architecture that may not be fully compatible with React on Rails' manual server-side rendering approach. We recommend v6 for stable integration. If you need v7 features, please test thoroughly and share your findings with the community. React Router v6 offers multiple routing approaches. For React on Rails, we recommend **Declarative Mode** (traditional component-based routing, covered in this guide). **Note on Data Mode:** React Router's Data Mode (with loaders/actions) is designed for SPAs where the client handles data fetching. Since React on Rails uses Rails controllers to load data and pass it as props to React components, Data Mode would create duplicate data loading. Stick with Declarative Mode to leverage React on Rails' server-side data loading pattern. ## Basic Client-Side Setup Most React Router integrations do not need Redux. Route ordinary components inside one React root, pass initial data from Rails as props, and use your normal server-state approach for follow-up data loading. **File: `app/javascript/src/RouterApp/RouterRoutes.jsx`** ```jsx import React from 'react'; import { Routes, Route } from 'react-router-dom'; const Home = ({ name }) => <div>Hello, {name}!</div>; const About = () => <div>About</div>; const RouterRoutes = (props) => ( <Routes> <Route path="/hello_world" element={<Home {...props} />} /> <Route path="/hello_world/about" element={<About />} /> </Routes> ); export default RouterRoutes; ``` `RouterRoutes.jsx` is a shared route tree that expects a router context from its parent. Keep it outside `ror_components/` and do not register it directly with React on Rails. Only the files inside `ror_components/` are registered entry points. **File: `app/javascript/src/RouterApp/ror_components/RouterApp.client.jsx`** ```jsx import React from 'react'; import { BrowserRouter } from 'react-router-dom'; import RouterRoutes from '../RouterRoutes'; const RouterApp = (props) => ( <BrowserRouter> <RouterRoutes {...props} /> </BrowserRouter> ); export default RouterApp; ``` ## Legacy Client-Side Setup with Redux If you're maintaining an app that already uses Redux, including the hidden legacy Redux generator output, you can add React Router by wrapping your app: **File: `app/javascript/src/HelloWorldApp/ror_components/HelloWorldApp.client.jsx`** ```jsx import React from 'react'; import { Provider } from 'react-redux'; import { BrowserRouter, Routes, Route } from 'react-router-dom'; import configureStore from '../store/helloWorldStore'; import HelloWorldContainer from '../containers/HelloWorldContainer'; // Import other components for routing // import About from '../components/About'; // import Contact from '../components/Contact'; const HelloWorldApp = (props) => { const store = configureStore(props); return ( <Provider store={store}> <BrowserRouter> <Routes> <Route path="/" element={<HelloWorldContainer />} /> {/* Add more routes here */} {/* <Route path="/about" element={<About />} /> */} {/* <Route path="/contact" element={<Contact />} /> */} </Routes> </BrowserRouter> </Provider> ); }; export default HelloWorldApp; ``` **Key points:** - In Redux-backed legacy apps, `<Provider>` wraps `<BrowserRouter>` so all routes have Redux access - Use `<Routes>` and `<Route>` (not `<Switch>` from React Router v5) - Use `element` prop to specify components (not `component` or `render` props from v5) - Routes are automatically matched by best fit, not render order ## Basic Server-Side Rendering with React Router For server rendering without Redux, use the same route tree with `StaticRouter` instead of `BrowserRouter`. This `.client.jsx` / `.server.jsx` split assumes [auto-bundling](../core-concepts/auto-bundling-file-system-based-automated-bundle-generation.md) is configured so React on Rails registers the client and server files separately. The server entry returns a render function, not JSX directly; see [Render-Functions and railsContext](../core-concepts/render-functions-and-railscontext.md). **File: `app/javascript/src/RouterApp/ror_components/RouterApp.server.jsx`** ```jsx import React from 'react'; import { StaticRouter } from 'react-router-dom/server'; import RouterRoutes from '../RouterRoutes'; const RouterApp = (props, railsContext) => { const { location } = railsContext; // React on Rails calls RouterApp(props, railsContext) to get this function, // then calls createElement(returnedFn, props). This example uses the props // and location captured by closure. return (_props) => ( <StaticRouter location={location}> <RouterRoutes {...props} /> </StaticRouter> ); }; export default RouterApp; ``` > **Note:** Components rendered through `react_component_hash` still need the explicit object return shape > instead of the render-function thunk shown here. Keep using `renderToString(...)` and return the object > described in [Render-Functions](../core-concepts/render-functions.md), for example > `{ renderedHtml: { componentHtml: renderToString(...), ...otherSlots } }`. ## Legacy Server-Side Setup with Redux If your app still uses the legacy shared Redux store, keep the provider around the `StaticRouter`. **File: `app/javascript/src/HelloWorldApp/ror_components/HelloWorldApp.server.jsx`** ```jsx import React from 'react'; import { StaticRouter } from 'react-router-dom/server'; import { Provider } from 'react-redux'; import { Routes, Route } from 'react-router-dom'; import configureStore from '../store/helloWorldStore'; import HelloWorldContainer from '../containers/HelloWorldContainer'; // Import other components for routing // import About from '../components/About'; // import Contact from '../components/Contact'; const HelloWorldApp = (props, railsContext) => { const store = configureStore(props); const { location } = railsContext; return (_props) => ( <Provider store={store}> <StaticRouter location={location}> <Routes> <Route path="/" element={<HelloWorldContainer />} /> {/* Add more routes here */} {/* <Route path="/about" element={<About />} /> */} {/* <Route path="/contact" element={<Contact />} /> */} </Routes> </StaticRouter> </Provider> ); }; export default HelloWorldApp; ``` **Important changes from React Router v5:** - Import `StaticRouter` from `'react-router-dom/server'` (not `'react-router'`) - Use `<Routes>` and `<Route>` with `element` prop - `location` prop takes a string path from `railsContext` - No need for `match()` or `RouterContext` - simplified API - Components rendered through `react_component_hash` still need the explicit object return shape instead of the render-function thunk shown here. Keep using `renderToString(...)` and return the object described in [Render-Functions](../core-concepts/render-functions.md), for example `{ renderedHtml: { componentHtml: renderToString(...), ...otherSlots } }`. ## Rails Routes Configuration **Critical Step:** To support direct URL visits, browser refresh, and server-side rendering, you must configure Rails to handle all React Router paths. Add a wildcard route in your `config/routes.rb`: ```ruby # config/routes.rb Rails.application.routes.draw do # Your main route get 'your_path', to: 'your_controller#index' # Wildcard catch-all for React Router sub-routes get 'your_path/*path', to: 'your_controller#index' end ``` **Example:** ```ruby # For a HelloWorld app with React Router get 'hello_world', to: 'hello_world#index' get 'hello_world/*path', to: 'hello_world#index' ``` This configuration ensures: - `/hello_world` → Renders your React app - `/hello_world/about` → Rails serves the same view, React Router handles routing - `/hello_world/contact` → Rails serves the same view, React Router handles routing - Browser refresh works on any route - Direct URL visits work with server-side rendering **Important:** Your React Router paths should match your Rails route structure. If Rails serves your app at `/hello_world`, your React Router routes should start with `/hello_world`: ```jsx <Routes> <Route path="/hello_world" element={<Home />} /> <Route path="/hello_world/about" element={<About />} /> <Route path="/hello_world/contact" element={<Contact />} /> </Routes> ``` ## Example Application For a complete example of React on Rails with React Router, see the [React Webpack Rails Tutorial](https://github.com/shakacode/react-webpack-rails-tutorial). For a practical example of route organization, see the [routes configuration file](https://github.com/shakacode/react-webpack-rails-tutorial/blob/master/client/app/bundles/comments/routes/routes.jsx) from the tutorial. **Note:** This tutorial uses a legacy directory structure (`client/app/bundles`) from earlier React on Rails versions. Modern projects use `app/javascript/src/` structure as shown in this guide. The React Router integration patterns remain applicable. ## `<Navigate>` Component SSR Behavior When using React Router's `<Navigate>` component with server-side rendering, be aware of the following behavior: - **During SSR, `<Navigate>` is a no-op.** It renders `null` because `useEffect` does not fire on the server. No redirect is performed — Rails still sends the full response with whatever HTML was rendered. - **The redirect only fires on the client** via `useEffect`, which runs after hydration. This means: - Users briefly see the SSR content before being redirected (content flash). - Search engines see the original page content, not a redirect — there is no HTTP 301/302 status code. - The client-side redirect adds a navigation entry to the browser history. **Recommendations for SSR redirects:** 1. **Prefer Rails controller redirects** for auth guards, canonical URLs, and SEO-critical redirects. Check conditions in your controller and call `redirect_to` before rendering. 2. **Use `<Navigate>` only for client-side routing transitions** where a brief flash is acceptable and SEO redirect semantics are not needed. ## Additional Resources - [React Router Official Documentation](https://reactrouter.com/) - [TanStack Router Guide for React on Rails](./tanstack-router.md) - [React Router v6 Migration Guide](https://reactrouter.com/docs/en/v6/upgrading/v5) - If upgrading from v5 - [React on Rails Turbo/Turbolinks Guide](./turbolinks.md) ================================================================================ PAGE: https://reactonrails.com/docs/building-features/tanstack-router SOURCE: docs/oss/building-features/tanstack-router.md ================================================================================ # Using TanStack Router [TanStack Router](https://tanstack.com/router) is a fully type-safe React router with built-in data loading, search param validation, and first-class TypeScript support. It's a strong choice when you want end-to-end type safety from your route definitions through to your components and search params. React on Rails Pro supports TanStack Router SSR via `react-on-rails-pro/tanstack-router`. This helper creates a render-function that handles both server-side rendering and client hydration/navigation. TanStack Router SSR **requires React on Rails Pro** with the Node Renderer and `rendering_returns_promises = true` in your Pro configuration. The async Node Renderer uses TanStack Router's public `router.load()` API for reliable, maintainable SSR. Client-side-only TanStack Router (without SSR) works with the open-source package - no special integration is needed since it's just a standard React app. ## Support Model - **First-class TanStack Router SSR**: React on Rails Pro only, via `react-on-rails-pro/tanstack-router` - **Server renderer**: Pro Node Renderer with `rendering_returns_promises = true` - **ExecJS**: intentionally not supported for TanStack Router SSR - **Client-only TanStack Router**: works in OSS without any special helper - **React Router**: remains the manual integration option; see [Using React Router](./react-router.md) ## Why Pro-Only This guide intentionally avoids an ExecJS SSR path. Synchronous SSR with TanStack Router pushes React on Rails toward private TanStack Router internals. The Pro-only async path keeps the integration on TanStack Router's public `router.load()`, `router.dehydrate()`, and `router.hydrate()` APIs, which is a much better long-term maintenance boundary. ## Install ```bash pnpm add @tanstack/react-router ``` ## Register a TanStack Router App Create a render-function with `createTanStackRouterRenderFunction` and register it with React on Rails: ```tsx import ReactOnRails from 'react-on-rails-pro'; import { createTanStackRouterRenderFunction } from 'react-on-rails-pro/tanstack-router'; import { RouterProvider, createBrowserHistory, createMemoryHistory, createRouter, } from '@tanstack/react-router'; import { routeTree } from '../routes/routeTree.gen'; const TanStackApp = createTanStackRouterRenderFunction( { createRouter: () => createRouter({ routeTree }), // AppWrapper: ({ children }) => <MyProviders>{children}</MyProviders>, // optional }, { RouterProvider, createMemoryHistory, createBrowserHistory, }, ); ReactOnRails.register({ TanStackApp }); ``` Then render it from Rails: ```erb <%= react_component("TanStackApp", props: { currentUserId: current_user&.id }, prerender: true) %> ``` ## How SSR + Hydration Works On the server, the helper returns a server render hash: ```ts { renderedHtml: ReactElement, clientProps: { __tanstackRouterDehydratedState: { ... } } } ``` React on Rails then: 1. Renders `renderedHtml` into HTML. 2. Merges `clientProps` into the client hydration payload generated by `react_component`. 3. Hydrates TanStack Router on the client using the dehydrated router state. ## Props Requirement When using this helper with `prerender: true`, pass `props:` as a Ruby `Hash` or a JSON object string. If you pass a JSON string that parses to a non-object value (like an array), React on Rails raises an error. ## Pro Configuration Ensure your React on Rails Pro initializer includes: ```ruby ReactOnRailsPro.configure do |config| # TanStack Router SSR requires the Pro Node Renderer async path. config.rendering_returns_promises = true end ``` ## Compatibility - Supported `@tanstack/react-router` versions: `>=1.139.0 <2.0.0` - Keep `react-on-rails-pro` up to date when upgrading `@tanstack/react-router`. ## Working Examples in This Repo - Pro dummy app (async server rendering): - Route + view: - `react_on_rails_pro/spec/dummy/config/routes.rb` - `react_on_rails_pro/spec/dummy/app/views/tanstack_router/index.html.erb` - TanStack app entry: - `react_on_rails_pro/spec/dummy/client/app/ror-auto-load-components/TanStackRouterAppAsync.jsx` - System test: - `react_on_rails_pro/spec/dummy/spec/system/integration_spec.rb` ## References - [Render-Functions Guide](../core-concepts/render-functions.md) - [View Helpers API](../api-reference/view-helpers-api.md) - [React Router Guide](./react-router.md) - [TanStack Query Guide](./tanstack-query.md) (the client-side server-state layer this pairs with) ================================================================================ PAGE: https://reactonrails.com/docs/building-features/client-side-routing-instant-navigation SOURCE: docs/oss/building-features/client-side-routing-instant-navigation.md ================================================================================ # Client-Side Routing & Instant Navigation React on Rails defaults to **component-per-page**: each page is its own `react_component` mount, and clicking a link is a normal Rails request. That is the right default for incremental adoption — but teams building a substantial React section often want **SPA navigation**: instant client-side transitions, a persistent shell layout that never unmounts, and server-driven data per route. This guide shows the **opt-in starter pattern** for exactly that, built entirely from existing React on Rails Pro APIs: - [`createTanStackRouterRenderFunction`](./tanstack-router.md) — SSR + hydration for a TanStack Router app - [`RSCRoute`](../../pro/react-server-components/inside-client-components.md) — streams a React Server Component's payload from a Rails endpoint during client navigation A complete runnable example lives in the Pro dummy app — see [Working example](#working-example-in-this-repo) below. ## Opt-In, Not a Takeover The starter is **a React-routed island inside a normal Rails app**, not a framework takeover: - One Rails catch-all route hands a URL subtree (for example `/dashboard/*`) to the React router. Every other route stays server-rendered Rails (ERB, Hotwire, anything). - Inertia replaces the view layer per route; Next.js owns the whole app. Here, the rest of your app doesn't change. - You can mount several independent React-routed sections, or none — adoption stays incremental. ## Requirements | Capability | Needs | | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | Client-only TanStack Router (no SSR) | Open-source React on Rails — it's just a React app | | SSR of the initial route | **Pro**: Node Renderer + `config.rendering_returns_promises = true` | | `RSCRoute` server-component routes | **Pro**: RSC support enabled (`enable_rsc_support`, `rsc_payload_generation_url_path`) and the matching `rsc_payload_route` mounted in `config/routes.rb` | See [Using TanStack Router](./tanstack-router.md) for the SSR helper details and [React Server Components inside client components](../../pro/react-server-components/inside-client-components.md) for `RSCRoute`. ## Why TanStack Router? The starter blesses **TanStack Router** because it is the router with a first-class React on Rails Pro SSR helper (`react-on-rails-pro/tanstack-router`), end-to-end TypeScript route types, and built-in data loading. **React Router remains the documented manual alternative.** [Using React Router](./react-router.md) covers the manual integration pattern, and recommends React Router **v6** over v7 (v7 merged with Remix and uses an architecture that is not a clean fit for React on Rails' manual SSR approach). If your team is already a React Router shop, that guide is the supported path — the starter pattern here (catch-all Rails route, persistent layout, scoped Turbo boundary) carries over; only the SSR dehydration/hydration helper is TanStack-specific. ## The Starter, Piece by Piece ### 1. One Rails route owns the subtree ```ruby # config/routes.rb get "dashboard(/*all)" => "dashboard#index", as: :dashboard ``` Every URL under `/dashboard` renders the same view, so deep links server-render the matching route and navigation after that is client-side. ### 2. The view mounts the app and scopes Turbo off Prepare request-specific route data in Rails first (for example, `@reports = current_user.reports.visible.select(:id, :title)` in the controller), then pass display-safe fields into the React-routed island: ```erb <%# app/views/dashboard/index.html.erb %> <div data-turbo="false"> <%= react_component("DashboardApp", props: { reports: @reports.as_json(only: [:id, :title]) }, prerender: true, raise_on_prerender_error: true) %> </div> ``` `raise_on_prerender_error: true` makes SSR failures raise during development and test instead of silently serving a broken page. Decide separately whether that behavior fits your production error-handling policy. The `data-turbo="false"` boundary keeps Turbo Drive from intercepting link clicks inside the React-routed subtree, so the two routers never compete. Outside this boundary, Turbo keeps working as usual. This guide does not address **deeper Turbo integration** (shared back/forward handling, scroll restoration across the boundary, Turbo Frames around streamed HTML) — that coexistence track is open in [issue #3485](https://github.com/shakacode/react_on_rails/issues/3485). ### 3. A persistent shell layout with nested routes ```jsx 'use client'; import React, { Suspense, useEffect, useMemo, useState } from 'react'; import { Link, Outlet, RouterProvider, createBrowserHistory, createMemoryHistory, createRootRoute, createRoute, createRouter, } from '@tanstack/react-router'; import { createTanStackRouterRenderFunction } from 'react-on-rails-pro/tanstack-router'; import RSCRoute from 'react-on-rails-pro/RSCRoute'; // The shell renders once and stays mounted across navigations. // Anything stateful here (sidebar state, form drafts, websocket // connections) survives route changes. const ReportDataContext = React.createContext({ reports: [] }); const ShellLayout = () => { const [count, setCount] = useState(0); return ( <div> <nav> <Link to="/dashboard">Home</Link> <Link to="/dashboard/reports">Reports</Link> <button type="button" onClick={() => setCount((c) => c + 1)}> Clicks: {count} {/* survives navigation — the shell never unmounts */} </button> </nav> <Outlet /> </div> ); }; const HomePage = () => <h2>Home</h2>; // An RSCRoute-backed route: the page's content is a React Server // Component, streamed from a Rails endpoint when the user navigates here. // componentProps are serialized into the payload request, so the server // component receives them when the payload is generated (see step 4). // // The mounted guard keeps RSCRoute out of the server render: with the // react_component entry point, RSC payloads cannot be generated during the // initial SSR (that needs wrapServerComponentRenderer + // stream_react_component), so deep links server-render the placeholder and // the client fetches the payload after mount — the same path used on // client-side navigation. const ReportsPage = () => { const { reports } = React.useContext(ReportDataContext); const [mounted, setMounted] = useState(false); const componentProps = useMemo(() => ({ reports }), [reports]); useEffect(() => { setMounted(true); }, []); if (!mounted) { return <p>Loading reports...</p>; } return ( <Suspense fallback={<p>Loading reports...</p>}> <RSCRoute componentName="Reports" componentProps={componentProps} /> </Suspense> ); }; const rootRoute = createRootRoute({ component: ShellLayout }); const routeTree = rootRoute.addChildren([ createRoute({ getParentRoute: () => rootRoute, path: '/dashboard', component: HomePage }), createRoute({ getParentRoute: () => rootRoute, path: '/dashboard/reports', component: ReportsPage }), ]); const DashboardApp = createTanStackRouterRenderFunction( { AppWrapper: ({ children, reports = [] }) => ( <ReportDataContext.Provider value={{ reports }}>{children}</ReportDataContext.Provider> ), createRouter: () => createRouter({ routeTree, // The Rails catch-all forwards every /dashboard/* path to this app, // so give unmatched URLs a real page instead of a blank Outlet. defaultNotFoundComponent: () => <h2>Page not found</h2>, }), }, { RouterProvider, createMemoryHistory, createBrowserHistory }, ); export default DashboardApp; ``` > [!NOTE] > Keep `componentProps` references stable for values derived during render, and wrap production `RSCRoute` routes in an app-specific error boundary so payload fetch or render failures degrade to your chosen error UI. For constant or empty props, prefer a module-level constant over `useMemo`. With [auto-bundling](../core-concepts/auto-bundling-file-system-based-automated-bundle-generation.md), placing this file in your components subdirectory registers it automatically — the generated client pack also sets up the default RSC provider that `RSCRoute` needs in the browser. ### 4. The server component `Reports` is a plain React Server Component (no `'use client'` directive). Its code never ships to the browser; only its rendered payload does: ```jsx import React from 'react'; const Reports = ({ reports = [] }) => ( <ul> {reports.map((r) => ( <li key={r.id}>{r.title}</li> ))} </ul> ); export default Reports; ``` > [!IMPORTANT] > The RSC payload is generated by the Pro **Node renderer**, which has no Rails models, database connection, or user session — so a server component must not reach into Rails directly, and an in-component fetch bypasses Rails' authorization and caching. > > - Let Rails resolve request-specific data first, then pass only display-safe data as props: through `RSCRoute` `componentProps` (serialized into the payload request, as above) or via [async props](../migrating/rsc-data-fetching.md#async-props-stream-each-slow-prop-independently), where Rails resolves each prop and the component awaits it under `<Suspense>`. > - **Treat `componentProps` as untrusted client input.** Client navigation re-sends `componentProps` to the RSC payload endpoint; an attacker can forge arbitrary values, including values that control what data is fetched or rendered. Re-derive any security- or data-sensitive values (current user, permissions, record IDs, tenant) from the Rails session or database inside the controller or a Pro async prop, not from client-supplied props. > > See [RSC Data Fetching Patterns](../migrating/rsc-data-fetching.md) for the full set of options. ### How navigation behaves - **Initial page load**: Rails serves SSR HTML for whatever route the URL matches; the client hydrates it. Deep links work because the Rails catch-all route renders the same component for the whole subtree. - **Client navigation**: TanStack Router swaps only the route outlet. The shell stays mounted, and no Rails page load happens. - **Navigating to an `RSCRoute` route**: the client fetches the server component's RSC payload over HTTP from the Rails `rsc_payload` endpoint and streams it into the outlet — server-driven data with no separate JSON API layer. - **Direct visit to the `RSCRoute` route**: the mounted guard means the server renders the placeholder and the client fetches the RSC payload after hydration. Server-rendering the RSC payload during the initial page load requires the `wrapServerComponentRenderer` + `stream_react_component` setup described in [the RSC guide](../../pro/react-server-components/inside-client-components.md), which is a different entry point than the TanStack SSR helper. - **Repeat visits to an `RSCRoute` route**: the default RSC provider caches payload promises by `componentName` plus serialized `componentProps` while the provider stays mounted, so returning to the same route can reuse the already-fetched payload. The local mounted guard can still briefly show the placeholder when the route outlet remounts before the cached payload is read. ## How This Compares **vs. Next.js App Router.** Next gives file-system routing with nested layouts that persist across navigations, streaming, and route prefetching — but it owns the entire app. The starter gives you the same persistent-layout, instant-navigation experience for a section of a Rails app, with React Server Components streamed from your Rails app's `rsc_payload` endpoint (Rails prepares the data — no separate backend to run). There is no file-system routing convention here — routes are explicit code. **vs. Inertia (inertia-rails).** Inertia's `<Link>` gives SPA navigation with server-driven props, plus prefetch and partial reloads, but it replaces the Rails view layer for every Inertia-rendered route. The starter is scoped: the React router owns one URL subtree, and `RSCRoute` streams server components (not just JSON props) per route. Inertia currently ships link prefetching out of the box; this starter does not (see below). **Honest gaps (current state).** - **No prefetch or bounded RSC payload-cache eviction yet.** The default provider already keeps payload promises in memory while mounted, keyed by `componentName` plus serialized `componentProps`. What is still missing is hover/viewport prefetch and a bounded eviction or invalidation policy for production-sized caches, tracked in [issue #3564](https://github.com/shakacode/react_on_rails/issues/3564). - **Repeat-visit flash on `RSCRoute` routes.** When the user navigates away from an `RSCRoute`-backed route and returns, TanStack Router unmounts the outlet component, so the placeholder briefly reappears before the cached or fetched payload is read. You can avoid that by lifting mount state above the outlet, but the starter keeps the simpler local-state pattern. - **Turbo coexistence is scoped-off, not integrated.** Deeper Turbo integration is tracked in [issue #3485](https://github.com/shakacode/react_on_rails/issues/3485). ## Working Example in This Repo The Pro dummy app contains the full runnable starter, exercised by a system test: - App: `react_on_rails_pro/spec/dummy/client/app/ror-auto-load-components/TanStackStarterApp.jsx` - Server component: `react_on_rails_pro/spec/dummy/client/app/ror-auto-load-components/StarterServerData.jsx` - Rails route/controller/view: `react_on_rails_pro/spec/dummy/config/routes.rb` (`tanstack_starter`), `react_on_rails_pro/spec/dummy/app/controllers/tanstack_starter_controller.rb`, `react_on_rails_pro/spec/dummy/app/views/tanstack_starter/index.html.erb` - System test (SSR, persistent layout, no-reload navigation, RSC streaming): `react_on_rails_pro/spec/dummy/spec/system/tanstack_starter_spec.rb` The dummy keeps the running example intentionally small: it passes `props: {}`, so it does not need the `AppWrapper`/`ReportDataContext` pattern shown in Step 3. Use that Step 3 pattern when Rails passes request-specific data into the routed island. ================================================================================ PAGE: https://reactonrails.com/docs/building-features/code-splitting SOURCE: docs/oss/building-features/code-splitting.md ================================================================================ # Code Splitting with Loadable Components > **Pro Feature** — Available with [React on Rails Pro](../../pro/react-on-rails-pro.md). > Free or very low cost for startups and small companies. [Upgrade or licensing details →](../../pro/upgrading-to-pro.md#try-pro-risk-free) ## Introduction The [React library recommends](https://loadable-components.com/docs/getting-started/) the use of React.lazy for code splitting with dynamic imports except when using server-side rendering. In that case, as of February 2020, they recommend [Loadable Components](https://loadable-components.com) for server-side rendering with dynamic imports. Note, in 2019 and prior, the code-splitting feature was implemented using `react-loadable`. The React team no longer recommends that library. The new way is far preferable. ## Installation ```bash yarn add @loadable/babel-plugin @loadable/component @loadable/server @loadable/webpack-plugin ``` ### Summary - [`@loadable/babel-plugin`](https://loadable-components.com/docs/getting-started/) - The plugin transforms your code to be ready for Server Side Rendering. - `@loadable/component` - Main library for creating loadable components. - `@loadable/server` - Has functions for collecting chunks and provide style, script, link tags for the server. - `@loadable/webpack-plugin` - The plugin to create a stats file with all chunks, assets information. ## Configuration These instructions mainly repeat the [server-side rendering steps from the official documentation for Loadable Components](https://loadable-components.com/docs/server-side-rendering/), but with some additions specifically to react_on_rails_pro. ### Webpack #### Server Bundle Configuration See example of server configuration differences in the loadable-components [example of the webpack.config.babel.js for server-side rendering](https://github.com/gregberge/loadable-components/blob/master/examples/server-side-rendering/webpack.config.babel.js) You need to configure 3 things: 1. `target` a. client-side: `web` b. server-side: `node` 2. `output.libraryTarget` a. client-side: `undefined` b. server-side: `commonjs2` 3. babel-loader options.caller = 'node' or 'web' 4. `plugins` a. server-side: `new webpack.optimize.LimitChunkCountPlugin({ maxChunks: 1 })` ```js { target: 'node', plugins: [ ..., new webpack.optimize.LimitChunkCountPlugin({ maxChunks: 1 }) ] } ``` Explanation: - `target: 'node'` is required to be able to run the server bundle with the dynamic import logic on nodejs. If that is not done, webpack will add and invoke browser-specific functions to fetch the chunks into the bundle, which throws an error on server-rendering. - `new webpack.optimize.LimitChunkCountPlugin({ maxChunks: 1 })` The react_on_rails_pro node-renderer expects only one single server-bundle. In other words, we cannot and do not want to split the server bundle. #### Client config For the client config we only need to add the plugin: ```js { plugins: [ ..., new LoadablePlugin({ filename: 'loadable-stats.json' }) ] } ``` This plugin collects all the information about entrypoints, chunks, and files, that have these chunks and creates a stats file during client bundle build. This stats file is used later to map rendered components to file assets. While you can use any filename, our documentation will use the default name. ### Babel Per [the docs](https://loadable-components.com/docs/babel-plugin/#transformation): > The plugin transforms your code to be ready for Server Side Rendering Add this to `babel.config.js`: ```js { "plugins": ["@loadable/babel-plugin"] } ``` https://loadable-components.com/docs/babel-plugin/ ### Convert components into loadable components Instead of importing the component directly, use a dynamic import: ```js import load from '@loadable/component'; const MyComponent = load(() => import('./MyComponent')); ``` ### Resolving issue with ChunkLoadError Sometimes chunks might not be loaded (network issues or others). You may get errors like this: ```js ChunkLoadError: Loading chunk 6 failed. (error: https://www.cityfalcon.com/packs/js/News-58215546ef43bc340bac.chunk.js) ``` This can be fixed by using a retry loop: ```js // https://gist.github.com/briancavalier/842626 const consoleDebug = (fn) => { if (typeof console.debug !== 'undefined') { console.debug(fn()); } }; const retry = (fn, retryMessage = '', retriesLeft = 3, interval = 500) => new Promise((resolve, reject) => { fn() .then(resolve) .catch(() => { setTimeout(() => { if (retriesLeft === 1) { console.warn(`Maximum retries exceeded, retryMessage: ${retryMessage}. Reloading page...`); window.location.reload(); return; } // Passing on "reject" is the important part consoleDebug( () => `Trying request, retryMessage: ${retryMessage}, retriesLeft: ${retriesLeft - 1}`, ); retry(fn, retryMessage, retriesLeft - 1, interval).then(resolve, reject); }, interval); }); }); export default retry; ``` Then use it in your component: ```js import retry from 'utils/retry'; const HomePage = loadable(() => retry(() => import('./HomePage'))); ``` **Please note that babel must not be configured to strip comments, since the chunk name is defined in a comment.** ### Server and client entries #### Client In the client bundle, we need to wrap the `hydrateRoot` call into a `loadableReady` function. So, hydration will be fired only after all necessary chunks preloads. In this example below, `ClientApp` is registering as `App`. ```js import React from 'react'; import ReactOnRails from 'react-on-rails-pro'; import { hydrateRoot } from 'react-dom/client'; import { loadableReady } from '@loadable/component'; import App from './App'; const ClientApp = (props, railsContext, domId) => { loadableReady(() => { const root = document.getElementById(domId); hydrateRoot(root, <App {...props} />); }); }; ReactOnRails.register({ App: ClientApp, }); ``` #### Server The purpose of the server function is to collect all rendered chunks and pass them as script, link, style tags to the Rails view. In this example below, `ServerApp` is registering as `App`. ```js import React from 'react'; import ReactOnRails from 'react-on-rails-pro'; import { ChunkExtractor } from '@loadable/server'; import App from './App'; import path from 'path'; const ServerApp = (props, railsContext) => { // This loadable-stats file was generated by `LoadablePlugin` in client webpack config. // You must configure the path to resolve per your setup. If you are copying the file to // a remote server, the file should be a sibling of this file. // __dirname is going to be the directory where the server-bundle.js exists // Note, React on Rails Pro automatically copies the loadable-stats.json to the same place as the // server-bundle.js. Thus, the __dirname of this code is where we can find loadable-stats.json. // Be sure to configure ReactOnRailsPro.config.assets_top_copy to this file. const statsFile = path.resolve(__dirname, 'loadable-stats.json'); // This object is used to search filenames by corresponding chunk names. // See https://loadable-components.com/docs/api-loadable-server/#chunkextractor // for the entryPoints, pass an array of all your entryPoints using dynamic imports const extractor = new ChunkExtractor({ statsFile, entrypoints: ['client-bundle'] }); // It creates the wrapper `ChunkExtractorManager` around `App` to collect chunk names of rendered components. const jsx = extractor.collectChunks(<App {...props} railsContext={railsContext} />); const componentHtml = renderToString(jsx); return { renderedHtml: { componentHtml, // Returns all the files with rendered chunks for furture insert into rails view. linkTags: extractor.getLinkTags(), styleTags: extractor.getStyleTags(), scriptTags: extractor.getScriptTags(), }, }; }; ReactOnRails.register({ App: ServerApp, }); ``` ## Configure react_on_rails_pro ### React on Rails Pro You must set `config.assets_top_copy` so that the node-renderer will have access to the loadable-stats.json. ```ruby config.assets_to_copy = Rails.root.join("public", "webpack", Rails.env, "loadable-stats.json") ``` Your server rendering code, per the above, will find this file like this: ```js const statsFile = path.resolve(__dirname, 'loadable-stats.json'); ``` Note, if `__dirname` is not working in your webpack build, that's because you didn't set `node: false` in your webpack configuration. That turns off the polyfills for things like `__dirname`. ### Node Renderer In your `renderer/node-renderer.js` file which runs node renderer, you need to specify `supportModules` options as follows: ```js const path = require('path'); const env = process.env; const { reactOnRailsProNodeRenderer } = require('react-on-rails-pro-node-renderer'); const config = { ... supportModules: env.RENDERER_SUPPORT_MODULES || null, }; ... reactOnRailsProNodeRenderer(config); ``` ## Rails View ```erb <% res = react_component_hash("App", props: {}, prerender: true) %> <%= content_for :link_tags, res['linkTags'] %> <%= content_for :style_tags, res['styleTags'] %> <%= res['componentHtml'].html_safe %> <%= content_for :script_tags, res['scriptTags'] %> ``` ## Making HMR Work To make HMR work, it's best to disable loadable-components when using the Dev Server. Take a look at the code searches for ['imports-loadable'](https://github.com/shakacode/react_on_rails/search?q=imports-loadable&type=code) and ['imports-hmr'](https://github.com/shakacode/react_on_rails/search?q=imports-hmr&type=code) The general concept is that we have a non-loadable, HMR-ready, file that substitutes for the loadable-enabled one, with the suffixes `imports-hmr.js` instead of `imports-loadable.js` ### Webpack configuration Use the [NormalModuleReplacement plugin](https://webpack.js.org/plugins/normal-module-replacement-plugin/): [code](https://github.com/shakacode/react_on_rails/blob/main/react_on_rails_pro/spec/dummy/config/webpack/commonWebpackConfig.js#L41-L49) ```js if (isWebpackDevServer) { environment.plugins.append( 'NormalModuleReplacement', new webpack.NormalModuleReplacementPlugin(/(.*)\.imports-loadable(\.jsx)?/, (resource) => { // eslint-disable-next-line no-param-reassign resource.request = resource.request.replace(/imports-loadable/, 'imports-hmr'); return resource.request; }), ); } ``` And compare: ### Routes file - [spec/dummy/client/app/components/Loadable/routes/Routes.imports-hmr.jsx](https://github.com/shakacode/react_on_rails/blob/main/react_on_rails_pro/spec/dummy/client/app/components/Loadable/routes/Routes.imports-hmr.jsx) - [spec/dummy/client/app/components/Loadable/routes/Routes.imports-loadable.jsx](https://github.com/shakacode/react_on_rails/blob/main/react_on_rails_pro/spec/dummy/client/app/components/Loadable/routes/Routes.imports-loadable.jsx) ### Client-Side Startup - [spec/dummy/client/app/loadable/loadable-client.imports-hmr.jsx](https://github.com/shakacode/react_on_rails/blob/main/react_on_rails_pro/spec/dummy/client/app/loadable/loadable-client.imports-hmr.jsx) - [spec/dummy/client/app/loadable/loadable-client.imports-loadable.jsx](https://github.com/shakacode/react_on_rails/blob/main/react_on_rails_pro/spec/dummy/client/app/loadable/loadable-client.imports-loadable.jsx) ### Server-Side Startup - [spec/dummy/client/app/loadable/loadable-server.imports-hmr.jsx](https://github.com/shakacode/react_on_rails/blob/main/react_on_rails_pro/spec/dummy/client/app/loadable/loadable-server.imports-hmr.jsx) - [spec/dummy/client/app/loadable/loadable-server.imports-loadable.jsx](https://github.com/shakacode/react_on_rails/blob/main/react_on_rails_pro/spec/dummy/client/app/loadable/loadable-server.imports-loadable.jsx) ================================================================================ PAGE: https://reactonrails.com/docs/building-features/hydration-scheduling SOURCE: docs/oss/building-features/hydration-scheduling.md ================================================================================ # Hydration Scheduling `hydrate_on` lets a Rails view keep server-rendered HTML visible immediately while deferring when React attaches event handlers and effects for that island. Deferred modes are implemented by the open-source client renderer. If React on Rails Pro is installed, non-immediate modes raise an error instead of silently hydrating immediately. Use it on standard `react_component` roots: ```erb <%= react_component("ProductRecommendations", props: @recommendation_props, prerender: true, hydrate_on: :visible) %> ``` The open-source package supports these modes: | Mode | Behavior | | ------------ | --------------------------------------------------------------------------------------------------------------- | | `:immediate` | Default. Hydrates or client-renders as soon as React on Rails processes the component. | | `:visible` | Uses `IntersectionObserver` and hydrates when the component container enters the viewport, with a 200px margin. | | `:idle` | Uses `requestIdleCallback` with a timeout, falling back to a short timer when the browser lacks idle callbacks. | ## When to Use It Use `hydrate_on: :visible` for below-the-fold islands such as recommendations, comments, footers, or sidebar widgets. Use `hydrate_on: :idle` for low-priority islands that are visible but not needed for the first interaction. Keep `:immediate` for navigation, forms, buttons, and anything the user may interact with right away. ## Server-Rendered Islands With `prerender: true`, the user sees the server-rendered HTML immediately. React hydration waits for the selected mode: ```erb <%= react_component("Reviews", props: { product_id: @product.id }, prerender: true, hydrate_on: :visible) %> ``` Because the HTML is already present, this works well for content that should be readable before it becomes interactive. Avoid making deferred islands look interactive before hydration. For example, render controls disabled until the component has hydrated, or keep immediate hydration for controls above the fold. ## Client-Only Roots `hydrate_on` also schedules client-only roots: ```erb <%= react_component("ClientOnlyChart", props: @chart_props, prerender: false, hydrate_on: :idle) %> ``` For `prerender: false`, the container stays empty until React renders. Prefer server rendering when users should see meaningful content before hydration. For `hydrate_on: :visible`, an empty zero-size client-only container cannot be reliably observed by `IntersectionObserver`. React on Rails renders that root in a macrotask via `setTimeout(fn, 0)` instead of leaving it permanently unmounted. If you need true viewport-based deferral for a client-only root, reserve layout space for the container or use `hydrate_on: :idle`. ## Turbo and Turbolinks Cleanup React on Rails cancels pending `:visible` observers and `:idle` callbacks during the same page-unload lifecycle it uses to unmount React roots on Turbo and Turbolinks navigation. If a user navigates away before a deferred island hydrates, the pending observer or callback is disconnected so the old page cannot hydrate after Turbo swaps the body. ## What This Does Not Do `hydrate_on` does not defer JavaScript bundle fetching. If you use `auto_load_bundle: true`, the generated bundle is still loaded when the page loads; only the React root creation is scheduled. Deferred bundle fetch is a separate optimization. `:interaction` is not supported in the open-source package. Passing `hydrate_on: :interaction` raises an error. Use `:immediate`, `:visible`, or `:idle`. Renderer functions, the 3-argument functions that call `hydrateRoot` or `createRoot` themselves, own their own mounting behavior. `hydrate_on` applies to normal React component registrations that React on Rails mounts for you. ================================================================================ PAGE: https://reactonrails.com/docs/building-features/react-helmet SOURCE: docs/oss/building-features/react-helmet.md ================================================================================ # Using React Helmet to build `<head>` content > **React 19 Alternative:** If you are using React 19, consider using [React 19 Native Metadata](react-19-native-metadata.md) instead of react-helmet. Native metadata tags (`<title>`, `<meta>`, `<link>`) are built into React 19 and work with streaming SSR and React Server Components — no extra dependencies or render-functions needed. ## Installation and general usage See [nfl/react-helmet](https://github.com/nfl/react-helmet) for details on how to use this package. Add this package to your application: ```bash yarn add react-helmet # or: npm install react-helmet # or: pnpm add react-helmet ``` ## Example Here is what you need to do in order to configure your Rails application to work with **ReactHelmet**. Create a render-function for server rendering like this: ```javascript export default (props, _railsContext) => { const componentHtml = renderToString(<App {...props} />); const helmet = Helmet.renderStatic(); const renderedHtml = { componentHtml, title: helmet.title.toString(), }; return { renderedHtml }; }; ``` You can add more **helmet** properties to the result, e.g. **meta**, **base** and so on. See https://github.com/nfl/react-helmet#server-usage. Use a regular React functional or class component or a render-function for your client-side bundle: ```javascript // React functional component export default (props) => <App {...props} />; ``` Or a render-function. Note you can't return just the JSX (React element), but you need to return either a React functional or class component. ```javascript // React functional component export default (props, railsContext) => ( () => <App {{railsContext, ...props}} /> ); ``` Note, this doesn't work, because this function just returns a React element rather than a React component ```javascript // React functional component export default (props, railsContext) => ( <App {{railsContext, ...props}} /> ); ``` Put the **ReactHelmet** component somewhere in your `<App>`: ```javascript import { Helmet } from 'react-helmet'; const App = (props) => ( <div> <Helmet> <title>Custom page title</title> </Helmet> ... </div> ); export default App; ``` Register your generators for client and server sides: ```javascript import ReactHelmetApp from '../ReactHelmetClientApp'; ReactOnRails.register({ ReactHelmetApp, }); ``` ```javascript // Note the import from the server file. import ReactHelmetApp from '../ReactHelmetServerApp'; ReactOnRails.register({ ReactHelmetApp, }); ``` Now when the `react_component_hash` helper is called with **"ReactHelmetApp"** as a first argument it will return a hash instead of an HTML string. Note, there is no need to specify "prerender" as it would not make sense to use react_component_hash without server rendering: ```erb <% react_helmet_app = react_component_hash("ReactHelmetApp", props: { hello: "world" }, trace: true) %> <% content_for :title do %> <%= react_helmet_app['title'] %> <% end %> <%= react_helmet_app["componentHtml"] %> ``` So now we're able to insert received title tag to our application layout: ```erb <%= yield(:title) if content_for?(:title) %> ``` ================================================================================ PAGE: https://reactonrails.com/docs/building-features/react-19-native-metadata SOURCE: docs/oss/building-features/react-19-native-metadata.md ================================================================================ # React 19 Native Metadata: Replacing react-helmet and react_component_hash React 19 introduces built-in support for rendering `<title>`, `<meta>`, and `<link>` tags anywhere in your component tree. React automatically hoists them into the document `<head>`. This eliminates the need for `react-helmet` and, for metadata use cases, `react_component_hash`. ## Why Migrate? | | react-helmet + react_component_hash | React 19 Native Metadata | | --------------------- | ---------------------------------------------------------- | ------------------------------------------------------------ | | **SSR approach** | `renderToString` only | Works with `renderToString`¹, streaming, and RSC | | **Streaming support** | Not compatible | Fully compatible | | **Dependencies** | `react-helmet` package | None (built into React 19) | | **Server setup** | Render-function returning object + `Helmet.renderStatic()` | Standard component | | **View helper** | `react_component_hash` (returns Hash) | `react_component` or `stream_react_component` (returns HTML) | | **Bundle complexity** | Separate server/client render-functions | Same component for both | ¹ With `renderToString`, metadata tags initially appear in `<body>` (since React on Rails renders component fragments, not full documents). They are hoisted to `<head>` only after client hydration. Streaming and RSC do not have this limitation. ## What React 19 Hoists to `<head>` React 19 automatically hoists these elements from anywhere in the component tree into the document `<head>`: | Element | Hoisted? | Notes | | --------------------------- | -------- | --------------------------------------------------------- | | `<title>` | Yes | Last rendered `<title>` wins | | `<meta>` | Yes | All variants (`name`, `property`, `httpEquiv`, `charSet`) | | `<link rel="stylesheet">` | Yes | Must include `precedence` prop for ordering | | `<link rel="preload">` | Yes | | | `<link rel="icon">` | Yes | And other `rel` types | | `<script async src="...">` | Yes | Only `async` scripts with `src` | | `<style>` with `precedence` | Yes | Inline styles with `precedence` prop | | `<script>` (inline) | **No** | Stays where rendered in the tree | | `<script defer>` | **No** | Not hoisted | > **Key limitation:** Inline `<script>` tags (including those with `dangerouslySetInnerHTML`) are **not** hoisted to `<head>`. They render where placed in the component tree. This matters for use cases like Apollo Client state serialization — see [What react_component_hash Is Still Needed For](#what-react_component_hash-is-still-needed-for). ## Migration Guide ### Step 1: Remove react-helmet Uninstall the package: ```bash yarn remove react-helmet # or: npm uninstall react-helmet # or: pnpm remove react-helmet ``` ### Step 2: Replace Helmet Tags with Native Tags **Before (react-helmet):** ```jsx import { Helmet } from 'react-helmet'; const MyPage = ({ title, description }) => ( <div> <Helmet> <title>{title}</title> <meta name="description" content={description} /> <link rel="canonical" href="https://example.com/page" /> </Helmet> <h1>{title}</h1> <p>Page content...</p> </div> ); ``` **After (React 19 native):** ```jsx const MyPage = ({ title, description }) => ( <div> <title>{title}</title> <meta name="description" content={description} /> <link rel="canonical" href="https://example.com/page" /> <h1>{title}</h1> <p>Page content...</p> </div> ); ``` The metadata tags can be placed anywhere in the component tree — React 19 hoists them to `<head>` automatically. There is no need for a wrapper component. ### Step 3: Replace the Render-Function and View Helper This is the key architectural change. With react-helmet, you needed a **render-function** returning an object and `react_component_hash` in your view. With React 19 native metadata, you use a standard component and `react_component` or `stream_react_component`. **Before — Server render-function (react-helmet):** ```jsx // MyPageServerApp.server.jsx import { renderToString } from 'react-dom/server'; import { Helmet } from 'react-helmet'; import MyPage from './MyPage'; export default (props, _railsContext) => { const componentHtml = renderToString(<MyPage {...props} />); const helmet = Helmet.renderStatic(); return { renderedHtml: { componentHtml, title: helmet.title.toString(), meta: helmet.meta.toString(), link: helmet.link.toString(), }, }; }; ``` **Before — Client component (react-helmet):** ```jsx // MyPageClientApp.jsx import MyPage from './MyPage'; export default (props) => () => <MyPage {...props} />; ``` **Before — ERB view (react-helmet):** ```erb <% page_data = react_component_hash("MyPageApp", props: { title: "My Page", description: "..." }, trace: true) %> <% content_for :title do %> <%= page_data['title'] %> <% end %> <% content_for :head do %> <%= page_data['meta'] %> <%= page_data['link'] %> <% end %> <%= page_data["componentHtml"] %> ``` **After — Single component (React 19 native):** ```jsx // MyPageApp.jsx const MyPageApp = ({ title, description }) => ( <div> <title>{title}</title> <meta name="description" content={description} /> <link rel="canonical" href="https://example.com/page" /> <h1>{title}</h1> <p>Page content...</p> </div> ); export default MyPageApp; ``` **After — ERB view (React 19 native, without streaming):** ```erb <%= react_component("MyPageApp", props: { title: "My Page", description: "..." }, prerender: true) %> ``` **After — ERB view (React 19 native, with streaming):** ```erb <%= stream_react_component("MyPageApp", props: { title: "My Page", description: "..." }, prerender: true) %> ``` No `content_for`, no separate server/client files, no render-function. React 19 handles the metadata hoisting automatically during both `renderToString` and `renderToPipeableStream`. ### Step 4: Remove Unused `content_for` Blocks If your layout has `content_for` blocks that were only used for react-helmet output, you can remove them: ```erb <!-- Before: needed for react-helmet output --> <head> <%= yield(:title) if content_for?(:title) %> <%= yield(:head) if content_for?(:head) %> </head> <!-- After: React 19 hoists metadata directly to <head> --> <head> <!-- React 19 automatically inserts <title>, <meta>, <link> here --> </head> ``` > **Note:** Keep `content_for` blocks if other (non-React) parts of your app still use them. ## Streaming with Native Metadata One of the biggest advantages of React 19 native metadata over react-helmet is **streaming compatibility**. With `stream_react_component`, metadata tags are included in the initial HTML shell and hoisted to `<head>` before the browser sees the content. ### Async Components with Dynamic Metadata Metadata can be rendered inside async components within Suspense boundaries. When the async component resolves, React streams the metadata to the client and updates `<head>`. Use [async props](../migrating/rsc-data-fetching.md#async-props-stream-each-slow-prop-independently) to stream slow data from Rails while showing a loading shell immediately. These APIs are available in React on Rails Pro: the parent component calls `getReactOnRailsAsyncProp` to obtain a Promise for each slow prop, passes it to an async child that `await`s it, and wraps that child in `<Suspense>`: > **React on Rails Pro setup:** This async-props helper is Pro-only. The controller must `include ReactOnRailsPro::Stream` and render the view via `stream_view_containing_react_components` (see [Streaming SSR](../../pro/streaming-ssr.md#4-render-the-view-using-the-stream_view_containing_react_components-helper)), and RSC must be enabled with `config.enable_rsc_support = true` in `config/initializers/react_on_rails_pro.rb` (see [React on Rails Pro configuration](../configuration/configuration-pro.md)). > **Server Component boundary:** Async function components such as `UserProfile` must run in a Server Component tree. Keep this file free of a `'use client'` directive. If resolved data needs to cross into a Client Component, await it in the server component first and pass only serializable props. ```jsx import React, { Suspense } from 'react'; // ProfilePage.jsx (no 'use client' directive; this is a Server Component tree) const UserProfile = async ({ userPromise, siteName }) => { const user = await userPromise; return ( <> <title>{`${user.name}'s Profile | ${siteName}`}</title> <meta name="description" content={`Profile page for ${user.name}`} /> <h1>{user.name}</h1> <p>{user.bio}</p> </> ); }; const ProfileSkeleton = () => <p>Loading profile...</p>; const ProfilePage = ({ getReactOnRailsAsyncProp, siteName }) => { const userPromise = getReactOnRailsAsyncProp('user'); return ( <div> {/* Initial metadata shown while loading */} <title>{`Loading Profile... | ${siteName}`}</title> <meta property="og:site_name" content={siteName} /> <Suspense fallback={<ProfileSkeleton />}> {/* Updated metadata streamed when resolved */} <UserProfile userPromise={userPromise} siteName={siteName} /> </Suspense> </div> ); }; export default ProfilePage; ``` > **Production note:** Error Boundaries help with client-side RSC payload fetches, refetches, and render-time failures after the initial stream. They do **not** catch errors thrown during the initial Server Component HTML stream; handle Rails/server-side failures before or inside `emit.call` with Rails-side rescue, logging, and serializable fallback values. See [Error Boundary limitations](../migrating/rsc-troubleshooting.md#error-boundary-limitations) and the [client-side retry pattern](../../pro/react-server-components/inside-client-components.md#error-handling). ```erb <%# Rails view — controller authorizes @user and captures request-scoped values first %> <% site_name = Current.account.name %> <%= stream_react_component_with_async_props("ProfilePage", props: { siteName: site_name }) do |emit| emit.call("user", @user.as_json(only: %i[name bio])) end %> ``` > **React on Rails note:** Keep authorization, database access, and cache-aware data loading in Rails. When auth, tenancy, or request state lives in `CurrentAttributes`, capture the needed serializable values before entering async-props work, pass them as regular props or IDs, and resolve scoped records server-side before calling `emit.call`. The React component never fetches data itself; it awaits the Promise that `getReactOnRailsAsyncProp` returns. See [RSC data fetching](../migrating/rsc-data-fetching.md). The initial `<title>` ("Loading Profile...") appears immediately. When Rails emits the `user` prop via `emit.call`, the Promise resolves, `UserProfile` renders, and React replaces the title with the user-specific one. ### React Server Components (RSC) with Native Metadata Native metadata works in React Server Components too. Since RSC components run exclusively on the server, metadata tags are always server-rendered. Keep canonical URLs and any SEO-critical tags that Rails already knows in the first-wave shell, then use React on Rails Pro async props so that slower article content and metadata can stream in while the shell renders immediately: ```jsx // NativeMetadataRSCApp.jsx (no 'use client' directive — this is a Server Component) import React, { Suspense } from 'react'; const AsyncContent = async ({ articlePromise }) => { const article = await articlePromise; return ( <> <title>{article.title}</title> <meta name="description" content={article.excerpt} /> <meta property="og:title" content={article.title} /> <meta property="og:image" content={article.cover_image} /> <article>{article.body}</article> </> ); }; const ArticlePage = ({ getReactOnRailsAsyncProp, canonicalUrl }) => { const articlePromise = getReactOnRailsAsyncProp('article'); return ( <div> <title>Loading...</title> {canonicalUrl && <link rel="canonical" href={canonicalUrl} />} <Suspense fallback={<ArticleSkeleton />}> <AsyncContent articlePromise={articlePromise} /> </Suspense> </div> ); }; export default ArticlePage; ``` ```erb <%# Rails view — controller authorizes @article and prepares first-wave SEO props %> <% canonical_url = @article.canonical_url %> <%= stream_react_component_with_async_props("ArticlePage", props: { canonicalUrl: canonical_url }) do |emit| emit.call("article", @article.as_json( only: %i[title excerpt cover_image body] )) end %> ``` > **React on Rails note:** RSC server components still run as part of a Rails-rendered request. Pass canonical URLs, tenant IDs, viewer IDs, and other first-wave context as explicit serializable props, or resolve the scoped records in Rails before streaming them through `emit.call`. The React component only awaits the Promise from `getReactOnRailsAsyncProp`. See [RSC data fetching](../migrating/rsc-data-fetching.md). ## Hybrid Approach: Rails-Side + React-Side Metadata For pages where some metadata is known at the Rails level (and doesn't need React), you can combine Rails-side metadata with React 19 native metadata for dynamic content: ```erb <%# Static metadata set in Rails — no React needed %> <% content_for :title, "My App — Dashboard" %> <% content_for :head do %> <meta property="og:site_name" content="My App" /> <link rel="canonical" href="<%= dashboard_url %>" /> <% end %> <%# Dynamic content rendered by React — component handles its own metadata %> <%= stream_react_component("DashboardApp", props: { user: @user }, prerender: true) %> ``` This approach is useful when the page title and Open Graph tags are static, but the component needs to render additional metadata based on its internal state. ## What react_component_hash Is Still Needed For React 19 native metadata replaces react-helmet for `<title>`, `<meta>`, and `<link>` tags. However, `react_component_hash` is still needed for use cases where **the render-function returns non-metadata HTML** that must be placed outside the component's DOM node: ### Apollo Client State Serialization Apollo Client's SSR pattern requires extracting the cache state **after** rendering the entire component tree, then serializing it as a `<script>` tag in the page. This cannot be done with native metadata because: 1. `client.extract()` requires all queries to resolve first (full tree convergence) 2. Inline `<script>` tags are **not hoisted** by React 19 3. The state must be available before hydration begins ```jsx // This pattern still requires react_component_hash export default async (props, _railsContext) => { const client = createApolloClient(); const componentHtml = await getMarkupFromTree({ tree: <App {...props} client={client} />, renderFunction: renderToString, }); const apolloState = client.extract(); const serializedApolloState = JSON.stringify(apolloState) .replace(/</g, '\\u003c') .replace(/>/g, '\\u003e') .replace(/&/g, '\\u0026'); const apolloStateTag = `<script>window.__APOLLO_STATE__ = ${serializedApolloState};</script>`; return { renderedHtml: { componentHtml, apolloStateTag, }, }; }; ``` > **Security:** If you serialize JSON into an inline `<script>` tag, escape `<`, `>`, and `&` characters at minimum. Consider using a library like [`serialize-javascript`](https://github.com/yahoo/serialize-javascript) for comprehensive escaping, so user data cannot break out of the script block with `</script>` or inject HTML entities. ### Code-Splitting with @loadable/component If you use `@loadable/component` with `ChunkExtractor` to collect code-split chunk tags, this still requires `react_component_hash`: ```jsx export default (props, _railsContext) => { const extractor = new ChunkExtractor({ statsFile }); const componentHtml = renderToString(extractor.collectChunks(<App {...props} />)); return { renderedHtml: { componentHtml, linkTags: extractor.getLinkTags(), scriptTags: extractor.getScriptTags(), styleTags: extractor.getStyleTags(), }, }; }; ``` > **Modern alternative:** For streaming SSR, consider replacing `@loadable/component` with `React.lazy` + `Suspense`. React 19 hoists `<script async src="...">` and `<link rel="stylesheet" precedence="...">` automatically, which covers the same use case as `ChunkExtractor` without needing a render-function. ## Migration Decision Matrix Use this matrix to decide which approach to use: | Use Case | Before | After | | ------------------------------------------ | ----------------------------------------- | ------------------------------------------------------------ | | Page title and meta tags | `react-helmet` + `react_component_hash` | React 19 native `<title>`, `<meta>` | | Canonical URLs | `react-helmet` + `react_component_hash` | React 19 native `<link rel="canonical">` | | Open Graph tags | `react-helmet` + `react_component_hash` | React 19 native `<meta property="og:...">` | | Stylesheets | `react-helmet` or `ChunkExtractor` | React 19 native `<link rel="stylesheet" precedence="...">` | | Async script loading | `ChunkExtractor` or manual | React 19 native `<script async src="...">` | | Apollo Client state | `react_component_hash` | **Keep** `react_component_hash` (no migration path) | | Inline scripts (`dangerouslySetInnerHTML`) | `react_component_hash` | **Keep** `react_component_hash` (inline scripts not hoisted) | | `@loadable/component` chunks | `react_component_hash` + `ChunkExtractor` | Consider `React.lazy` + `Suspense` with streaming | ## Prerequisites - **React 19** — native metadata hoisting is a React 19 feature - **React on Rails 15+** — for basic `react_component` usage - **React on Rails Pro 4+** — for `stream_react_component` and RSC support ## References - [React 19 `<title>` documentation](https://react.dev/reference/react-dom/components/title) - [React 19 `<meta>` documentation](https://react.dev/reference/react-dom/components/meta) - [React 19 `<link>` documentation](https://react.dev/reference/react-dom/components/link) - [React 19 `<script>` documentation](https://react.dev/reference/react-dom/components/script) - [Streaming Server Rendering](streaming-server-rendering.md) — how to set up streaming SSR - [View Helpers API](../api-reference/view-helpers-api.md) — `react_component`, `react_component_hash`, `stream_react_component` - [Render-Functions](../core-concepts/render-functions.md) — how render-functions work with `react_component_hash` - [Using React Helmet](react-helmet.md) — legacy react-helmet documentation ================================================================================ PAGE: https://reactonrails.com/docs/building-features/react-19-activity SOURCE: docs/oss/building-features/react-19-activity.md ================================================================================ # React 19.2 `<Activity>` with React on Rails React 19.2 introduces [`<Activity>`](https://react.dev/reference/react/Activity), a built-in component that lets you **hide part of your UI without unmounting it**: ```jsx import { Activity } from 'react'; <Activity mode={isActive ? 'visible' : 'hidden'}> <TabPanel /> </Activity>; ``` When `mode="hidden"`: - The subtree stays **mounted** — all component state (inputs, scroll positions, fetched data held in state) is preserved. - Its DOM stays in the document but is hidden with `display: none`. - Its **effects are deactivated** (cleanup functions run), and they reactivate when the boundary becomes visible again. - Updates inside the hidden subtree are **deferred** to idle time, so hidden UI never competes with visible UI for rendering priority. This is the React-blessed replacement for the classic "keep the inactive tab alive" hacks (`display: none` wrappers, lifting every tab's state up, etc.). Typical uses: tab switchers, master/detail panes, and pre-rendering likely-next screens. ## Version requirements | Layer | Requirement | | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `react` / `react-dom` in your app | **19.2.0 or later** (`Activity` does not exist in earlier versions, including 19.0/19.1) | | `react_on_rails` gem + npm package | Any current version — the package's peer dependency is `react >= 16`, so React on Rails does not constrain you; just upgrade `react`/`react-dom` in **your app's** bundle | | RSC / Pro streaming path | **Not yet** — the React Server Components toolchain is currently pinned to the React 19.0 line. Use `<Activity>` only in plain client bundles for now | `<Activity>` is a regular React feature inside your components. React on Rails needs no configuration for it — it works with the standard `react_component` helper in both client-side rendering and server-side rendering with hydration. ## Client-side rendering (CSR) ```erb <%= react_component("ActivityTabSwitcher", props: { initialTab: "profile" }, prerender: false) %> ``` ```tsx import { Activity, useState } from 'react'; const TAB_NAMES = ['profile', 'drafts'] as const; type TabName = (typeof TAB_NAMES)[number]; function TabPanel({ tab }: { tab: TabName }) { // This state survives tab switches because the hidden panel stays mounted. const [draft, setDraft] = useState(''); return ( <label> Draft for {tab}: <input value={draft} onChange={(e) => setDraft(e.target.value)} /> </label> ); } const ActivityTabSwitcher = ({ initialTab = 'profile' }: { initialTab?: TabName }) => { const [activeTab, setActiveTab] = useState<TabName>(initialTab); return ( <div> {TAB_NAMES.map((tab) => ( <button key={tab} type="button" onClick={() => setActiveTab(tab)}> {tab} </button> ))} {TAB_NAMES.map((tab) => ( <Activity key={tab} mode={tab === activeTab ? 'visible' : 'hidden'}> <TabPanel tab={tab} /> </Activity> ))} </div> ); }; export default ActivityTabSwitcher; ``` Contrast with the usual conditional render `{tab === activeTab && <TabPanel tab={tab} />}`, which unmounts the inactive panel and **loses** its state. ## Server-side rendering + hydration (`prerender: true`) ```erb <%= react_component("ActivityTabSwitcher", props: { initialTab: "profile" }, prerender: true) %> ``` This works with React on Rails' standard string SSR (verified in the dummy app on the ExecJS path; the Pro Node renderer uses the same `renderToString` API). Verified behavior on React 19.2: - **Visible** Activity content is included in the server-rendered HTML (delimited by `<!--&-->` / `<!--/&-->` boundary markers). - **Hidden** Activity content is **omitted from the server HTML entirely**. React renders hidden subtrees on the client after hydration, at low priority. - Hydration produces **no mismatch warnings** — React knows hidden boundaries are server-skipped and fills them in client-side. Practical consequences: - Your initial HTML payload only pays for visible content. Hidden tabs do not bloat the SSR response. - Hidden content is **not available for SEO** or for users with JavaScript disabled. Put content that must be in the initial HTML in the visible boundary. - Hidden subtrees still consume client memory once rendered — do not keep unbounded numbers of hidden trees mounted. ## Effects unmount while hidden — gotchas When a boundary goes `hidden`, React runs all effect cleanups in that subtree (and re-runs the effects when it becomes visible again). State is preserved; effects are not. Audit hidden-able components for: - **Subscriptions / sockets**: a WebSocket opened in `useEffect` disconnects when the tab hides and reconnects when shown. That is the designed behavior — not a bug. If the connection must outlive visibility, own it above the `<Activity>` boundary. - **Timers and intervals**: cleared on hide; restart on show. - **Analytics "view" events fired from effects**: they will fire again each time the boundary becomes visible. ## Turbo / Turbolinks caveat (important) **`<Activity>` cannot preserve state across Turbo (or Turbolinks) page visits.** State preservation only works **within a persistent React root**. On a Turbo Drive navigation, Turbo replaces the document `<body>`; React on Rails unmounts your components on the page-change events and mounts fresh ones on the new page. Every `<Activity>` boundary — hidden or visible — is destroyed with its root, and all React state is gone. Use the right tool for each axis: - **Within one page** (tabs, panes, wizards rendered by a single `react_component`): `<Activity>` preserves the hidden parts' state. ✅ - **Across Turbo page visits**: `<Activity>` does not help. ❌ If you need UI to survive Turbo navigation, the element must be excluded from Turbo's body swap (e.g., Turbo's [`data-turbo-permanent`](https://turbo.hotwired.dev/handbook/building#persisting-elements-across-page-loads)), which is independent of React and has its own significant constraints with React-managed DOM. For React-native cross-"page" state preservation, use client-side routing (e.g., React Router) inside one persistent React root instead of full Turbo page loads — then `<Activity>` can keep inactive route trees alive. ## Working example The React on Rails dummy app contains a complete, tested example: - Component: `react_on_rails/spec/dummy/client/app/startup/ActivityTabSwitcher.tsx` - CSR page: `/client_side_activity` (`prerender: false`) - SSR page: `/server_side_activity` (`prerender: true`) - Tests: `react_on_rails/spec/dummy/spec/requests/activity_component_spec.rb` (server HTML shape) and `react_on_rails/spec/dummy/spec/system/activity_spec.rb` (state preservation + hydration in a real browser) ## References - [React docs: `<Activity>`](https://react.dev/reference/react/Activity) - [React 19.2 release post](https://react.dev/blog/2025/10/01/react-19-2) - [Turbo handbook: persisting elements across page loads](https://turbo.hotwired.dev/handbook/building#persisting-elements-across-page-loads) ================================================================================ PAGE: https://reactonrails.com/docs/building-features/react-compiler SOURCE: docs/oss/building-features/react-compiler.md ================================================================================ # React Compiler with React on Rails [React Compiler](https://react.dev/learn/react-compiler) (stable **v1.0**, shipped 2025-10-07) is a build-time tool that adds **automatic memoization** to your components. It cuts unnecessary re-renders and much of the hand-written `useMemo` / `useCallback` / `React.memo` boilerplate. Because the Compiler is versioned independently of React itself, it works on React on Rails' current `react`/`react-dom` `~19.0.x` pin. You do **not** need to wait for a React 19.2 bump to adopt it. React on Rails delegates JavaScript/TypeScript transforms to your app's build tool (Shakapacker → webpack or Rspack, with Babel or SWC). The Compiler is therefore configured in **your app's Babel or SWC config**, not inside React on Rails. This page documents both transform paths. ## TL;DR - **Babel path is canonical and verified.** Add `babel-plugin-react-compiler` to your `babel.config.js`, ordered **first**. The compiler-memoized output builds and server-renders correctly. - **SWC path is experimental — not recommended for production yet.** As of June 2026 there is no first-party SWC React Compiler plugin; only a brand-new, pre-1.0 third-party Wasm plugin exists. See [Rspack + SWC path](#rspack--swc-path-experimental). - **Scope it.** Both paths let you gate the compiler to specific files via the `sources` option. Start scoped to a few components, verify SSR, then widen. - **RSC boundaries are opt-in from the client side.** Compile `'use client'` islands, keep Server Components directive-free, and verify the RSC payload path separately. ## Prerequisites - **React ≥ 19** runtime (React on Rails' dummy apps and the Pro runtime already pin `~19.0.x`). - **Shakapacker** (any bundler/transpiler combination it supports). - Components that follow the [Rules of React](https://react.dev/reference/rules). The Compiler skips (bails out of) components it cannot safely optimize; it does not crash the build for them. ## Shakapacker + Babel path (canonical) This is the verified, recommended path. ### 1. Install the plugin ```bash # pnpm pnpm add -D babel-plugin-react-compiler@^1.0.0 # npm npm install --save-dev babel-plugin-react-compiler@^1.0.0 # yarn yarn add --dev babel-plugin-react-compiler@^1.0.0 ``` ### 2. Add the plugin to `babel.config.js`, ordered FIRST The React Compiler **must run before every other Babel plugin and preset** so it sees your original source before another transform rewrites it (per the [React docs](https://react.dev/learn/react-compiler/installation)). In Babel, make it the **first entry in `plugins`**. A typical React on Rails `babel.config.js` builds on Shakapacker's preset. Prepend the compiler: ```js // babel.config.js const defaultConfigFunc = require('shakapacker/package/babel/preset.js'); module.exports = function createBabelConfig(api) { const resultConfig = defaultConfigFunc(api); const isProductionEnv = api.env('production'); resultConfig.presets = [ ...resultConfig.presets, ['@babel/preset-react', { runtime: 'automatic', development: !isProductionEnv }], ]; // React Compiler MUST be first. resultConfig.plugins = [ 'babel-plugin-react-compiler', // ← first, ahead of everything else ...resultConfig.plugins, ]; return resultConfig; }; ``` ### 3. (Recommended) Scope the compiler with `sources` Avoid enabling the compiler for the whole app in one step: it changes every component's output and can surface latent Rules-of-React violations. The `sources` option accepts **either an array of strings or a predicate `(filename) => boolean`**. The array form is **not glob-based**: each entry is matched as a filename **substring**, so a literal `**` glob like `client/app/**/*.tsx` matches no real path and silently skips every component. Use the predicate form for precise control: ```js resultConfig.plugins = [ [ 'babel-plugin-react-compiler', { // Compile only files under client/app/startup/compiler-ready/ sources: (filename) => typeof filename === 'string' && filename.includes('client/app/startup/compiler-ready'), }, ], ...resultConfig.plugins, ]; ``` Start scoped, verify SSR and tests, then widen the predicate (or drop `sources`). ### 4. Build and verify ```bash # Your normal Shakapacker build, e.g.: RAILS_ENV=test NODE_ENV=test bin/shakapacker ``` The compiler injects a memoization cache into each compiled component. In the emitted bundle, a compiled component contains memo-cache slot accesses (`$[0]`, `$[1]`, …) and `useMemoCache` calls — components it skipped do not. That is how you can confirm, against a real build, that the compiler ran and that your `sources` scope is correct. > **Note:** `Symbol.for("react.memo_cache_sentinel")` appears in every React 19 bundle — it is part of React's runtime, not proof that the compiler ran. Look for `$[n]` memo-slot accesses **inside your component** instead. ## No double-application risk (verified) A common worry is that Shakapacker's default Babel preset might already include the React Compiler (or `@babel/preset-react`), causing a double transform. **It does not.** Inspecting the resolved `shakapacker/package/babel/preset.js` (Shakapacker 10.1) shows its full transform set is: - `@babel/preset-env` - `@babel/preset-typescript` (when present) - `@babel/plugin-transform-runtime` It contains **no** `@babel/preset-react` and **no** `babel-plugin-react-compiler`. Apps add `@babel/preset-react` themselves in `babel.config.js`, and the React Compiler is only present if you add it explicitly. So there is **no double-application** — the compiler runs exactly once, and only where you place it. ## SSR compatibility (verified) React on Rails server-renders your components through the Node renderer / ExecJS server bundle (`renderToString` / `renderToPipeableStream`). The Compiler's output is plain React — auto-memoization is a render-time optimization that does not change the SSR contract. This was verified end-to-end: a compiler-memoized example component (`ReactCompilerExample`) was built with the Babel path and server-rendered through the dummy app's server bundle, producing correct HTML with `hasErrors: false`. SSR works unchanged with the compiler enabled. If you adopt the compiler, keep verifying SSR for your own components — especially any that read browser-only globals at render time, which is a Rules-of-React violation independent of the compiler. ## RSC boundary example The React Compiler applies only to Client Components (`'use client'`). Keep Server Components directive-free and outside the `sources` predicate: ```tsx // components/compiler-ready/Picker.client.tsx 'use client'; import { useState } from 'react'; export function Picker() { const [quantity, setQuantity] = useState(1); return <button onClick={() => setQuantity((value) => value + 1)}>{quantity}</button>; } // ror-auto-load-components/RscProduct.tsx import { Picker } from '../components/compiler-ready/Picker.client'; export default function RscProduct() { return <Picker />; } ``` Scope `sources` to `components/compiler-ready/` before widening it. ## Rspack + SWC path (experimental) Many React on Rails teams use Rspack with SWC for build speed (see the [Babel → SWC migration guide](../migrating/babel-to-swc-migration.md)). Unfortunately, the SWC React Compiler story is **not production-viable as of June 2026**: - There is **no first-party SWC plugin**. `@swc/plugin-react-compiler` does not exist on npm (404), and `@swc/core` has no native React Compiler support. - The only candidate, `swc-plugin-react-compiler`, is a **brand-new third-party Wasm plugin** (first published 2026-06-09, currently `0.1.1`) with no published `@swc/core` peer-version constraints. SWC Wasm plugins do not follow semver for ABI compatibility with the `@swc/core` host, so a plugin built against one `@swc/core` can fail to load against another. **Recommendation: the Babel path is canonical; the SWC path is experimental.** If you are on SWC/Rspack and want the React Compiler today, the most reliable option is to run the **Babel compiler plugin scoped to your compiler-ready components** while keeping SWC for the rest of the build, or to stay on SWC without the compiler until a first-party `@swc/core` integration ships. Track the React Compiler [working group](https://github.com/reactwg/react-compiler) and `@swc/core` releases before wiring the experimental SWC plugin into a production Rspack build. If you do experiment with the SWC plugin, do it behind an env flag and scoped to a throwaway component first, exactly as with the Babel `sources` example above — and treat any build that succeeds as unverified until you have an SSR smoke test. ## Reference example in this repo The standard dummy app (`react_on_rails/spec/dummy`) ships a scoped, runnable reference: - **Component:** `client/app/startup/ReactCompilerExample.tsx` — a non-RSC component written with **no** manual memoization. - **Babel wiring:** `babel.config.js` adds `babel-plugin-react-compiler` **first**, gated behind `REACT_COMPILER=1` and scoped via `sources` to just `ReactCompilerExample`, so the default build (which uses SWC) and the existing test suite are unaffected. - **View / route:** `app/views/pages/react_compiler_example.html.erb` + the `react_compiler_example` route render it with `prerender: true` (SSR + hydration). - **Lint wiring:** the root flat ESLint config uses `eslint-plugin-react-hooks` v6 and enables the compiler Rules-of-React checks for this scoped compiler example. Build it with the compiler on (Babel path): ```bash cd react_on_rails/spec/dummy REACT_COMPILER=1 SHAKAPACKER_JAVASCRIPT_TRANSPILER=babel \ RAILS_ENV=test NODE_ENV=test bin/shakapacker ``` The compiler is **off by default**, so nothing changes for the normal SWC build. ## Follow-ups (not yet covered here) These are intentionally deferred and tracked separately: - **Performance benchmark.** A concrete before/after re-render / interaction-latency benchmark to quantify the win is a follow-up. ## References - [React Compiler (v1.0)](https://react.dev/learn/react-compiler) - [React Compiler installation](https://react.dev/learn/react-compiler/installation) - [Rules of React](https://react.dev/reference/rules) - [Babel → SWC migration guide](../migrating/babel-to-swc-migration.md) - [React Compiler working group](https://github.com/reactwg/react-compiler) ================================================================================ PAGE: https://reactonrails.com/docs/building-features/view-transitions SOURCE: docs/oss/building-features/view-transitions.md ================================================================================ # View Transitions with React on Rails (Experimental) > **⚠️ Experimental — not officially supported.** This entire page is a canary recipe. The browser > [View Transitions API](https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API) is still > evolving, React's component-level `<ViewTransition>` API is canary-only, and this recipe may change or > break without notice. Nothing on this page is covered by React on Rails' support policy or semver > guarantees. React Server Components are explicitly out of scope here. Tracked in > [#3888](https://github.com/shakacode/react_on_rails/issues/3888). This page shows how to use the **browser-native** `document.startViewTransition()` API with components rendered by `react_component` — first client-side-only (CSR), then with server rendering plus hydration (SSR-hydrate) — and how it interacts with Turbo Drive's own view-transition support. ## What this covers (Experimental) - Wrapping React state updates (and client-side route updates) in `document.startViewTransition()`. - What does and does not work when the component is server-rendered and hydrated. - The Turbo Drive interplay: Turbo's cross-page transitions vs React-driven in-page transitions. - A tiny flagged demo in the gem's dummy app. It deliberately does **not** cover React's canary `<ViewTransition>` component / `addTransitionType` API beyond a status note (see below), and it does not cover React Server Components. ## Browser support and feature detection (Experimental) Same-document view transitions (`document.startViewTransition`) ship in Chrome/Edge 111+, Safari 18+, and recent Firefox releases, but you must always feature-detect — unsupported browsers simply apply the DOM update without animation: ```js function withViewTransition(applyUpdate) { if (typeof document.startViewTransition === 'function') { document.startViewTransition(applyUpdate); } else { applyUpdate(); // graceful fallback: same update, no animation } } ``` ## CSR recipe (Experimental) `document.startViewTransition(callback)` snapshots the current page, runs your `callback` to mutate the DOM, snapshots the result, and animates between the two snapshots. The catch for React: React 18/19 **batches state updates and commits asynchronously**, but the browser expects the DOM to be fully updated when your callback returns. Wrap the state update in [`flushSync`](https://react.dev/reference/react-dom/flushSync) so React commits synchronously inside the callback: ```tsx import React, { useState } from 'react'; import { flushSync } from 'react-dom'; const Panel = () => { const [expanded, setExpanded] = useState(false); const toggle = () => { const applyUpdate = () => { flushSync(() => { setExpanded((prev) => !prev); }); }; if (typeof document.startViewTransition === 'function') { document.startViewTransition(applyUpdate); } else { applyUpdate(); } }; return ( <div> <button type="button" onClick={toggle}> Toggle </button> <div id="vt-panel" className={expanded ? 'panel panel--expanded' : 'panel'}> … </div> </div> ); }; ``` Give the animated element a `view-transition-name` so the browser can pair its old/new snapshots, and optionally style the transition pseudo-elements: ```css #vt-panel { view-transition-name: vt-panel; } ::view-transition-old(vt-panel), ::view-transition-new(vt-panel) { animation-duration: 300ms; } ``` This works with plain `react_component("Panel", prerender: false)` — no React on Rails configuration is involved; the recipe is entirely inside your component and CSS. ### Client-side route changes (Experimental) The same pattern wraps client-side navigation inside a React root: call your router's navigate function inside the `startViewTransition` callback (with `flushSync` if the router commits asynchronously). If you use React Router, prefer its built-in integration (`<Link viewTransition>` / `useViewTransitionState`) instead of hand-rolling — see [React Router](./react-router.md). These router-level integrations are experimental in the same sense as the rest of this page. ### CSR pitfalls (Experimental) - **`flushSync` is a forced synchronous render.** Keep the transitioned update small; large trees will jank inside the transition callback. - **One transition at a time.** Starting a new same-document transition skips any transition already running. Rapid clicks fall back to the final state — that is by design, but don't queue your own. - **Duplicate `view-transition-name`s abort the transition.** Each name must be unique on the page at snapshot time (watch out for lists; derive names from item ids if you animate list items). - **Names must be valid CSS custom identifiers.** A `view-transition-name` cannot start with a digit and cannot be a CSS-wide keyword (`none`, `inherit`, …) — prefix derived names, e.g. `item-42`, not `42`. ## SSR-hydrate recipe (Experimental) The same component works with `prerender: true` (server rendering + client hydration) as long as you follow these rules: - **Only touch the API in event handlers or effects.** `document` does not exist in the server-side rendering environment (ExecJS or the Pro Node renderer). Never call or feature-detect `document.startViewTransition` at module scope or during render of a server-rendered component. - **Don't branch markup on feature support during the initial render.** The server cannot know what the browser supports, so support-dependent markup causes hydration mismatches. Feature-detect inside the handler (as above), or stash support in state from a `useEffect` after mount. - **`view-transition-name` in server-rendered HTML is safe.** It is plain CSS — it has no effect until a transition starts, and it does not affect hydration. - **The initial paint is not transitioned.** View transitions animate _updates_; server-rendered HTML appearing and React hydrating it produce no transition (and hydration itself must not be wrapped in one). Only post-hydration interactions animate. In short: SSR-hydrate works today with the browser API because the transition only ever runs on the client, after hydration, inside user-triggered handlers. ## React canary `<ViewTransition>` status (Experimental) React's component-level API (`<ViewTransition>`, `addTransitionType`) is **canary-only** and is not part of this recipe. React 19.2 shipped groundwork that matters for the future here — SSR Suspense reveal batching, and the `useId` prefix change to `_r_` so generated ids are valid `view-transition-name` values — but running a canary React build under React on Rails is untested and unsupported. This page intentionally uses only the browser API, which works on stable React 19. ## Turbo Drive interplay (Experimental) > **⚠️ Turbo claims pending maintainer review.** The claims in this section follow Turbo's documented > behavior and React on Rails' Turbo event wiring, but they have not yet been verified end-to-end in > the dummy app. Treat them as provisional until a maintainer confirms them. Rails apps using [Turbo Drive](https://turbo.hotwired.dev) have a second, independent view-transition system: Turbo can wrap its **cross-page** (page-to-page) renders in `document.startViewTransition` when the page opts in via: ```html <meta name="view-transition" content="same-origin" /> ``` How this relates to React-driven transitions: - **Two different scopes.** Turbo Drive transitions animate whole-page navigations (Turbo replaces the `<body>`); React-driven transitions (this page's recipe) animate state/route updates **inside** a mounted React root. Use Turbo's mechanism for cross-page continuity and the React recipe for in-page interactions — they solve different problems. - **React state does not survive a Turbo visit.** React on Rails listens to `turbo:before-render` / `turbo:render` and unmounts components before Turbo swaps the body, then re-mounts them on the new page (see `packages/react-on-rails/src/pageLifecycle.ts`). Any cross-page visual continuity must come from Turbo's transition (matching `view-transition-name`s in the old and new HTML), not from React. - **They must not run simultaneously.** Browsers allow only one active same-document transition; starting another skips the one in progress. Avoid triggering a React `startViewTransition` from code that runs during a Turbo visit (e.g., in `turbo:before-render`/`turbo:render` handlers or unmount paths). In practice this is easy to satisfy: trigger React transitions only from user interactions. - **Turbo's preview cache can confuse pairing.** Turbo may first render a cached preview of the next page and then the fresh response. Elements with `view-transition-name` that appear in both the old page and the preview can pair unexpectedly or abort (duplicate names). Test with the cache in play before shipping, or disable preview for transitioned pages (`<meta name="turbo-cache-control" content="no-preview">`). ## In-repo demo (Experimental) The gem's dummy app contains a minimal CSR demo of this recipe, inert unless you opt in with an environment flag: - Component: `react_on_rails/spec/dummy/client/app/startup/ViewTransitionsDemo.client.tsx` - View: `react_on_rails/spec/dummy/app/views/pages/view_transitions_demo.html.erb` - Route: defined in `react_on_rails/spec/dummy/config/routes.rb` only when `VIEW_TRANSITIONS_DEMO=true` Run it from a React on Rails checkout: ```bash cd react_on_rails/spec/dummy VIEW_TRANSITIONS_DEMO=true bin/dev # then open http://localhost:3000/view_transitions_demo ``` With the flag unset, the route does not exist and the demo page is unreachable. ## Promote-to-supported checklist (Experimental) This page graduates from experimental to supported only when all of the following are true: - [ ] React's `<ViewTransition>` / `addTransitionType` ship in a **stable** React release, and React on Rails' supported React range includes that release. - [ ] The Turbo-interplay claims above are verified end-to-end in the dummy app (Turbo is enabled there) by a maintainer, and the "pending maintainer review" banner is removed. - [ ] The CSR and SSR-hydrate recipes are re-validated against the then-current React on Rails major, and the dummy demo is either covered by a spec/E2E test or promoted out of its env flag. - [ ] Browser support is re-confirmed as Baseline for same-document transitions across the browsers the docs target (re-check Firefox). - [ ] Experimental banners are removed from this page and the change is announced in the CHANGELOG. **Owner:** maintainers — tracked in [#3888](https://github.com/shakacode/react_on_rails/issues/3888). Re-check cadence: each React minor release (or quarterly, whichever comes first). ================================================================================ PAGE: https://reactonrails.com/docs/building-features/streaming-server-rendering SOURCE: docs/oss/building-features/streaming-server-rendering.md ================================================================================ # Streaming Server Rendering :::tip Pro Feature SSR works in the OSS version via ExecJS. Pro adds streaming SSR with `renderToPipeableStream` and Suspense for progressive rendering. See the [Streaming SSR guide](../../pro/streaming-ssr.md) or [upgrade to Pro →](../../pro/upgrading-to-pro.md) ::: React on Rails Pro supports streaming server rendering using React 18/19's `renderToPipeableStream` API. Instead of waiting for the entire page to render before sending any HTML, streaming SSR sends HTML to the browser progressively as each part of the page becomes ready. ## Why Streaming SSR? Traditional SSR renders the full page on the server, then sends the complete HTML in one response. This means the user sees nothing until the slowest component finishes rendering. Streaming SSR changes this: - **Faster Time to First Byte (TTFB)** — The browser receives the page shell immediately - **Progressive rendering** — Content appears as it becomes ready, not all at once - **Suspense integration** — React's `<Suspense>` boundaries define which parts can stream independently - **Selective Hydration** — Components become interactive as soon as their JavaScript loads, even while other parts are still streaming ## How It Works 1. Rails starts the response immediately, sending the HTML shell (layout, static content, loading placeholders) 2. The Node Renderer uses `renderToPipeableStream` to render React components 3. As each `<Suspense>` boundary resolves (e.g., an async data fetch completes), the rendered HTML chunk is streamed to the browser 4. The browser replaces placeholders with real content — no full-page reload needed ## Quick Example ```jsx import React, { Suspense } from 'react'; const ProductPage = () => ( <> <Suspense fallback={<div>Loading details...</div>}> <ProductDetails /> </Suspense> <Suspense fallback={<div>Loading reviews...</div>}> <ProductReviews /> </Suspense> </> ); ``` ```ruby class ProductsController < ApplicationController include ActionController::Live include ReactOnRails::Controller include ReactOnRailsPro::Stream def show stream_view_containing_react_components(template: 'products/show') end end ``` ```erb <%= stream_react_component('ProductPage', props: { id: @product.id }) %> ``` ## Full Guide For implementation steps, compression middleware compatibility, script loading strategies, metadata handling, immediate hydration, and best practices, see the [Streaming SSR guide](../../pro/streaming-ssr.md). ================================================================================ PAGE: https://reactonrails.com/docs/building-features/conditional-server-rendering SOURCE: docs/oss/building-features/how-to-conditionally-server-render-based-on-device-type.md ================================================================================ # How to conditionally render server side based on the device type In general, we want to use CSS to do mobile responsive layouts. However, sometimes we want to have layouts sufficiently different that we can't do this via CSS. If we didn't do server rendering, we can check the device type on the client side. However, if we're doing server rendering, we need to send this data to the client code from the Rails server so that the server rendering can account for this. Here's an example: ## config/initializers/react_on_rails.rb ```ruby module RenderingExtension # Return a Hash that contains custom values from the view context that will get passed to # all calls to react_component and redux_store for rendering def self.custom_context(view_context) if view_context.controller.is_a?(ActionMailer::Base) {} else { desktop: !(view_context.browser.device.tablet? || view_context.browser.device.mobile?), tablet: view_context.browser.device.tablet?, mobile: view_context.browser.device.mobile? || false } end end end # Shown below are the defaults for configuration ReactOnRails.configure do |config| # See https://reactonrails.com/docs/configuration/ for the rest # This allows you to add additional values to the Rails Context. Implement one static method # called `custom_context(view_context)` and return a Hash. config.rendering_extension = RenderingExtension end ``` Note, full details of the React on Rails configuration are [available here](../configuration/README.md). See the doc file [render-functions-and-railscontext.md](../core-concepts/render-functions-and-railscontext.md#rails-context) for how your client-side code uses the device information ================================================================================ PAGE: https://reactonrails.com/docs/building-features/client-server-files SOURCE: docs/oss/building-features/how-to-use-different-files-for-client-and-server-rendering.md ================================================================================ ## How to use different versions of a file for client and server rendering > [!NOTE] > **React Server Components (RSC) users:** With RSC, server components run exclusively on the server and client components handle browser interactivity. This component model eliminates the need for separate `.server/.client` file variants. Using file variants with RSC can cause issues — see the [auto-bundling troubleshooting guide](../core-concepts/auto-bundling-file-system-based-automated-bundle-generation.md#8-component-with-serverclient-variants-used-with-rsc) for details. There are 3 main ways to use different code for server vs. client rendering. ## A. Using different Entry Points Many projects will have different entry points for client and server rendering. This only works for a top-level entry point such as the entry point for a React Router app component. Your Client Entry can look like this: ```js import ReactOnRails from 'react-on-rails/client'; import App from './ClientApp'; ReactOnRails.register({ App }); ``` So your Server Entry can look like: ```js import ReactOnRails from 'react-on-rails'; import App from './ServerApp'; ReactOnRails.register({ App }); ``` Note that the only difference is in the imports. ## B. Two Options for Using Webpack Resolve Alias in the Webpack Config Per [Webpack Docs](https://webpack.js.org/configuration/resolve/#resolve-alias). ### 1. Update `webpack/set-resolve.js` to have a different resolution for the exact file ```js function setResolve(builderConfig, webpackConfig) { // Use a different resolution for Client and Server file let SomeJsFile; if (builderConfig.serverRendering) { SomeJsFile = path.resolve(__dirname, "../bundles/SomeJsFileServer"); } else { SomeJsFile = path.resolve(__dirname, "../bundles/SomeJsFileClient"); } const resolve = { alias: { // ... other aliases SomeJsFile, // ... other aliases }, ``` Then you have this import: ```js import SomeJsFile from 'SomeJsFile'; ``` ### 2. Use a different resolution for the right directory of client or server files #### a. Update `webpack/set-resolve.js` to have something like ```js function setResolve(builderConfig, webpackConfig) { // Use a different resolution for Client and Server file let variant; if (builderConfig.serverRendering) { variant = path.resolve(__dirname, "../bundles/variant/ServerOnly"); } else { variant = path.resolve(__dirname, "../bundles/variant/ClientOnly"); } const resolve = { alias: { // ... other aliases variant, // ... other aliases }, ``` #### b. Add different versions of the file to the `bundles/variant/ClientOnly` and `bundles/variant/ServerOnly` directories #### c. Use the `variant` in import in a file that can be used both for client and server rendering ```js import SomeJsFile from 'variant/SomeJsFile'; import AnotherJsFile from 'variant/AnotherJsFile'; ``` ## C. Conditional code that can check if `window` is defined. This is probably the ugliest and hackiest way to do this, but it's quick! Essentially you wrap code that cannot execute server side in a conditional: ```js if (window) { // window should be falsy on the server side doSomethingClientOnly(); // or do an import const foobar = require('foobar').default; } ``` ================================================================================ PAGE: https://reactonrails.com/docs/building-features/caching SOURCE: docs/oss/building-features/caching.md ================================================================================ # SSR Caching: Prerender Caching and Fragment Caching :::tip Pro Feature Available with [React on Rails Pro](../../pro/react-on-rails-pro.md). Free or very low cost for startups and small companies. [Upgrade or licensing details →](../../pro/upgrading-to-pro.md#try-pro-risk-free) ::: Server-side rendering (SSR) is expensive. Every render evaluates JavaScript, assembles props from the database, serializes them to JSON, and produces HTML. React on Rails Pro provides two levels of caching that avoid repeating this work on every request. Both solve the same core problem — **eliminating redundant SSR** — but they operate at different layers and offer different tradeoffs. | | Prerender Caching | Fragment Caching | | -------------------------- | ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- | | **What it caches** | The JavaScript evaluation result (the SSR output for a given set of props) | The entire rendered fragment including props assembly, serialization, and SSR | | **Setup effort** | One config line — `config.prerender_caching = true` | Requires choosing cache keys and passing props as a block | | **Cache key** | Automatic: hash of server bundle + JavaScript code to evaluate | You define it: any combination of ActiveRecord models, timestamps, locale, URL, etc. | | **Skips prop evaluation?** | No — props are still computed, serialized, and sent to the JS engine; only the JS execution result is cached | Yes — when the cache hits, the props block is never called, saving database queries and serialization | | **Best for** | Quick win, especially when you want to avoid JS evaluation overhead without changing view code | Maximum performance, especially for pages with expensive prop assembly (database queries, API calls) | | **Start here?** | Yes — turn it on first and measure the impact | Add it next for your highest-traffic or most expensive components | **Recommendation**: Start with prerender caching (one line of config). Once you see the benefit, add fragment caching to your most expensive components for the biggest additional gains. Fragment caching subsumes prerender caching — when a fragment cache hits, prerender caching is never consulted because the entire rendered output is already stored. Consult the [Rails Guide on Caching](http://guides.rubyonrails.org/caching_with_rails.html#cache-stores) for details on: - [Cache Stores and Configuration](http://guides.rubyonrails.org/caching_with_rails.html#cache-stores) - [Determination of Cache Keys](http://guides.rubyonrails.org/caching_with_rails.html#cache-keys) - [Caching in Development](http://guides.rubyonrails.org/caching_with_rails.html#caching-in-development): **To toggle caching in development**, run `rails dev:cache`. ## Tracing If tracing is turned on in your config/initializers/react_on_rails_pro.rb, you'll see timing log messages that begin with `[ReactOnRailsPro:1234]: exec_server_render_js` where 1234 is the process id and `exec_server_render_js` could be a different method being traced. - **exec_server_render_js**: Timing of server rendering, which may have the prerender_caching turned on. - **cached_react_component** and **cached_react_component_hash**: Timing of the cached view helper which may be calling server rendering. Here's a sample. Note the second request: ```text Started GET "/server_side_redux_app_cached" for ::1 at 2018-05-24 22:40:13 -1000 [ReactOnRailsPro:63422] exec_server_render_js: ReduxApp, 230.7ms [ReactOnRailsPro:63422] cached_react_component: ReduxApp, 2483.8ms Completed 200 OK in 3613ms (Views: 3407.5ms | ActiveRecord: 0.0ms) Started GET "/server_side_redux_app_cached" for ::1 at 2018-05-24 22:40:36 -1000 Processing by PagesController#server_side_redux_app_cached as HTML Rendering pages/server_side_redux_app_cached.html.erb within layouts/application [ReactOnRailsPro:63422] cached_react_component: ReduxApp, 1.1ms Completed 200 OK in 19ms (Views: 16.4ms | ActiveRecord: 0.0ms) ``` --- ## Level 1: Prerender Caching Prerender caching is the simplest way to speed up SSR. It caches the result of JavaScript evaluation so that identical rendering calls return instantly from the Rails cache instead of re-executing JavaScript. ### How it works When a `react_component` call triggers SSR, React on Rails Pro computes a cache key from: 1. A hash of the server bundle 2. The JavaScript code to evaluate (which includes the serialized props) If the cache contains an entry for that key, the cached HTML is returned without calling JavaScript. If not, the JS is evaluated, the result is cached, and then returned. ### Setup One line in `config/initializers/react_on_rails_pro.rb`: ```ruby config.prerender_caching = true ``` That's it. No view code changes required. ### When to use it - As a quick first step — turn it on and measure the impact before investing in fragment caching - When your components are stateless (same props always produce the same output) - When you want to reduce load on the JavaScript evaluation engine (ExecJS or Node Renderer) ### When NOT to use it - If you're already using fragment caching for most components, prerender caching adds cache entries without additional benefit for those components (increasing the likelihood of premature cache ejection) - If your server-side JavaScript depends on external state (AJAX calls, GraphQL) that makes rendering non-idempotent ### Diagnostics If you're using `react_component_hash`, you'll get 2 extra keys returned: 1. RORP_CACHE_KEY: the prerender cache key 2. RORP_CACHE_HIT: whether or not there was a cache hit. It can be useful to log these to the rendered HTML page to debug caching issues. --- ## Level 2: Fragment Caching Fragment caching is the advanced option that delivers the biggest performance gains. It caches the entire rendered output — including the cost of assembling props from the database — so that on a cache hit, no database queries, no JSON serialization, and no JavaScript evaluation occur. See also the [Fragment Caching overview](../../pro/fragment-caching.md). This is very similar to [Rails fragment caching](http://guides.rubyonrails.org/caching_with_rails.html#fragment-caching): > Fragment Caching allows a fragment of view logic to be wrapped in a cache block and served out of the cache store when the next request comes in. If you're already familiar with Rails fragment caching, the React on Rails implementation should feel familiar. The most important parts to consider are: 1. Determining the optimal cache keys that minimize any cost such as database queries. 2. Clearing the Rails.cache on some deployments. ### Why Use Fragment Caching? 1. Next to caching at the controller or HTTP level, this is the fastest type of caching. 2. The additional complexity to add this with React on Rails Pro is minimal. 3. The performance gains can be huge. 4. The load on your Rails server can be far lessened. ### Why Not Use Fragment Caching? 1. It's tricky to get all the right cache keys. You have to consider any values that can change and cause the rendering to change. See the [Rails docs for cache keys](http://guides.rubyonrails.org/caching_with_rails.html#cache-keys) 2. Testing is a bit tricky or just not done for fragment caching. 3. Some deployments require you to clear caches. ### Considerations for Determining Your Cache Key 1. Consult the [Rails docs for cache keys](http://guides.rubyonrails.org/caching_with_rails.html#cache-keys) for help with cache key definitions. 2. If your React code depends on any values from the [Rails Context](../core-concepts/render-functions-and-railscontext.md#rails-context), such as the `locale` or the URL `location`, then be sure to include such values in your cache key. In other words, if you are using some JavaScript such as `react-router` that depends on your URL, or on a call to `toLocaleString(locale)`, then be sure to include such values in your cache key. To find the values that React on Rails uses, use some code like this: ```ruby the_rails_context = rails_context i18nLocale = the_rails_context[:i18nLocale] location = the_rails_context[:location] ``` If you are calling `rails_context` from your controller method, then prefix it like this: `helpers.rails_context` so long as you have react_on_rails > 11.2.2. If less than that, call `helpers.send(:rails_context, server_side: true)` If performance is particularly sensitive, consult the view helper definition for `rails_context`. For example, you can save the cost of calculating the rails_context by directly getting a value: ```ruby i18nLocale = I18n.locale ``` ### How: API Here is the doc for helpers `cached_react_component` and `cached_react_component_hash`. Consult the [view helpers API docs](../api-reference/view-helpers-api.md) for the non-cached analogies `react_component` and `react_component_hash`. These docs only show the differences. ```ruby # Provide caching support for react_component in a manner akin to Rails fragment caching. # All the same options as react_component apply with the following difference: # # 1. You must pass the props as a block. This is so that the evaluation of the props is not done # if the cache can be used. # 2. Provide the cache_key option # cache_key: String or Array (or Proc returning a String or Array) containing your cache keys. # If prerender is set to true, the server bundle digest will be included in the cache key. # When RSC support is enabled and the RSC bundle exists, the RSC bundle digest is also included. # The cache_key value is the same as used for conventional Rails fragment caching. # 3. Optionally provide the `:cache_options` key with a value of a hash including as # :compress, :expires_in, :race_condition_ttl as documented in the Rails Guides # 4. Provide boolean values for `:if` or `:unless` to conditionally use caching. ``` You can find the `:cache_options` documented in the [Rails docs for ActiveSupport cache store](https://guides.rubyonrails.org/caching_with_rails.html#activesupport-cache-store). #### API Usage examples The fragment caching for `react_component`: ```ruby <%= cached_react_component("App", cache_key: [@user, @post], prerender: true) do some_slow_method_that_returns_props end %> ``` Suppose you only want to cache when `current_user.nil?`. Use the `:if` option (`unless:` is analogous): ```ruby <%= cached_react_component("App", cache_key: [@user, @post], prerender: true, if: current_user.nil?) do some_slow_method_that_returns_props end %> ``` And a fragment caching version for the `react_component_hash`: ```ruby <% result = cached_react_component_hash("ReactHelmetApp", cache_key: [@user, @post], id: "react-helmet-0") do some_slow_method_that_returns_props end %> <% content_for :title do %> <%= result['title'] %> <% end %> <%= result["componentHtml"] %> <% printable_cache_key = ReactOnRailsPro::Utils.printable_cache_key(result[:RORP_CACHE_KEY]) %> <!-- <%= "CACHE_HIT: #{result[:RORP_CACHE_HIT]}, RORP_CACHE_KEY: #{printable_cache_key}" %> --> ``` Note in the above example, React on Rails Pro returns both the raw cache key and whether or not there was a cache hit. ### Your JavaScript Bundles and Cache Keys When doing fragment caching of server rendering with React on Rails Pro, the cache key must reflect your React. This is analogous to how Rails puts an MD5 hash of your views in the cache key so that if the views change, then your cache is busted. In the case of React code, if your React code changes, then your bundle name will change if you are doing the inclusion of a hash in the name. However, if you are using a separate webpack configuration to generate the server bundle file, then you **must not** include the hash in the output filename or else you will have a race condition overwriting your `manifest.json`. Regardless of which case you have, React on Rails handles it. --- ## Tag-Based Revalidation Cache keys answer "is this entry still current?" at read time. Tags answer a different question: "delete everything that depends on this data, right now." With `cache_tags:`, you attach declarative invalidation handles to fragment-cached components and bust them all with one call — the React on Rails Pro analog of Next.js `revalidateTag`. ```erb <%= cached_react_component("PostShow", cache_key: [@post, I18n.locale], cache_tags: [@post, @post.author], cache_options: { expires_in: 12.hours }) do { post: @post.to_props } end %> ``` ```ruby # Anywhere in Ruby — controller, job, service object, console: ReactOnRailsPro.revalidate_tag(post) # => number of cache entries deleted ReactOnRailsPro.revalidate_tags(post, post.author) ``` `cache_tags:` is accepted by the cached helpers — `cached_react_component`, `cached_react_component_hash`, `cached_stream_react_component`, `cached_buffered_stream_react_component`, and `cached_async_react_component` — and is purely additive: `cache_key:` semantics are unchanged, and `cache_key:` is still required. ### Tag forms and normalization A tag can be: - a **String** — passed through unchanged (`"post:42"`) - a **Symbol or Numeric** — stringified via `.to_s` (`:featured` -> `"featured"`, `42` -> `"42"`) - an object responding to **`#cache_key`** (any ActiveRecord model) — ActiveRecord-style records normalize to the stable identity `posts/42` (equal to the version-less `record.cache_key`, and stable even when `cache_versioning` is disabled), so the tag stays valid as the record changes; other objects pass their `#cache_key` through. Objects with both `model_name` and `id` always resolve to `collection/id`; pass an explicit String tag if you want a different key. - a **Proc** (arity 0) returning any accepted form - an **Array** of any mix of the above Tags that normalize to blank raise `ReactOnRailsPro::Error`. Tag coarsely (`post:42`, `tenant:7`, `posts:index`) — never per-user or per-request; see the index bounds below. ### Revalidating from the model layer Include the `Revalidates` concern so the model that owns the data also owns cache invalidation. It runs in `after_commit`, so it never fires for a rolled-back transaction and fires only after the new data is visible to the re-rendering request: ```ruby class Post < ApplicationRecord include ReactOnRailsPro::Cache::Revalidates revalidates_react_cache # default tag: record.cache_key, e.g. "posts/42" # or custom / additional tags: # revalidates_react_cache { |post| ["post:#{post.id}", "author:#{post.author_id}"] } end ``` This covers create/update/destroy and `touch` — so `belongs_to ..., touch: true` composes for free: touching the parent fires the parent's revalidation. The standard Rails callback caveat applies: `update_column`, `update_all`, `delete_all`, and other callback-skipping writes do not trigger revalidation; call `ReactOnRailsPro.revalidate_tags(record)` yourself after such writes. One more caveat for custom tag blocks: the block runs in `after_commit` and sees only the record's **new** values. If a custom tag derives from a mutable attribute (e.g. `"author:#{post.author_id}"` and a post moves to a different author), the old grouping's entries are not revalidated — they expire via `expires_in`. Prefer tags derived from the record's own identity, or revalidate the old grouping explicitly (`previous_changes` in `after_commit` has the prior value). ### How it works, and the contract On every tagged cache write, the final cache key is appended to a per-tag index entry in `Rails.cache` (keyed by a SHA-256 digest under `rorp:tag:v1:` so long tag names and whitespace do not violate cache-store key limits). `revalidate_tag` reads the index, deletes the recorded entries with `delete_multi`, then deletes the index entry. A missing index (never-written tag, evicted entry, `:null_store`) means "nothing to revalidate" — never an error. **Tag revalidation is best-effort; correctness is bounded by `expires_in`.** `ActiveSupport::Cache` has no atomic set-append, so the index append is a read-modify-write: two processes caching different entries under the same tag at the same moment can race, and one entry can be lost _from the index_ (the cached data itself is never lost). A lost index entry simply survives `revalidate_tag` and expires via its own `expires_in`. The same applies when the index entry itself is LRU-evicted. Therefore: - **Always set `expires_in` (or `expires_at`) on tagged entries.** It is the upper bound on how long a missed invalidation can serve stale HTML. In development, React on Rails Pro logs a warning when `cache_tags:` is used without an expiry. - **Use a shared cache store in production** — Redis or Memcached. With `:memory_store` the index is per-process, so `revalidate_tag` in one process cannot see entries written by another; with `:null_store` tags are inert. - **Keep cache deletion failures bounded by expiry.** `revalidate_tag` clears the tag index before deleting the indexed entries to reduce re-registration races. If the cache store raises during deletion, any surviving entries are orphaned from that tag and only expire via their own `expires_in`. - **Custom cache stores must honor `namespace: nil` in `delete_multi` and `delete`.** The tag index records the fully namespaced logical keys that Rails wrote, then suppresses the store default namespace at delete time. Stores that ignore `options[:namespace]` can silently miss tag-revalidation deletes. Two config knobs bound the index (defaults shown): ```ruby ReactOnRailsPro.configure do |config| config.cache_tag_index_expires_in = 7.days # index TTL ceiling for entries without expires_in config.cache_tag_index_max_keys = 5_000 # keys recorded per tag; oldest dropped beyond this end ``` When a tagged entry has `expires_in`, the index entry's TTL automatically covers it (plus slack). When a tag exceeds the per-tag key cap, the oldest keys are dropped with a logged warning — those entries fall back to plain TTL expiration. Note that tags solve **data**-driven invalidation only. Deploy invalidation is already handled by deploy bundle digests in the cache key (see [Cache Warming](#cache-warming)) — a deploy cold-starts prerendered fragment caches regardless of tags. ### Next.js mapping | Next.js 16 (Cache Components) | React on Rails Pro | | --------------------------------------------------- | --------------------------------------------------------------------------------------- | | `'use cache'` on a function/component | `cached_react_component` / `cached_react_component_hash` / streaming and async variants | | `cacheTag('post-42')` inside the cached scope | `cache_tags: ["post:42"]` helper option | | `revalidateTag('post-42')` in a Server Action | `ReactOnRailsPro.revalidate_tag("post:42")` — anywhere in Ruby, incl. `after_commit` | | Manually wiring `revalidateTag` into every mutation | `include ReactOnRailsPro::Cache::Revalidates` — invalidation rides the AR transaction | | `cacheLife` profiles | `cache_options: { expires_in: ... }` | | `revalidateTag(tag, 'max')` / SWR profiles | Not yet supported (stale-while-revalidate is a possible future addition) | Like Next.js's default `revalidateTag`, revalidation deletes: the next request re-renders and re-registers. There is no background refresh. --- ## Cache Warming Prerendered fragment cache keys include deploy bundle digests, which means every deploy creates new cache keys. This is correct — rendered output must match the current server bundle and, when RSC support is enabled and the RSC bundle exists, the current RSC bundle — but it means every deploy starts with a cold cache. Under live traffic, this creates a synchronized storm of cache misses: every user request triggers full SSR, database queries for props assembly, and JS evaluation simultaneously. The solution is **cache warming**: rendering your highest-traffic pages in the background immediately after deploy, before real users hit those pages. ### The pattern 1. Deploy new code 2. Identify the pages that matter most (by recent traffic) 3. Render those pages in background jobs through the normal view path 4. The existing `cached_react_component` helpers fill the cache naturally 5. Live traffic hits warm caches instead of triggering cold rebuilds ```ruby # app/jobs/warm_page_job.rb class WarmPageJob include Sidekiq::Job sidekiq_options queue: "cache_warming", retry: 3 def perform(page_id, release_version) return unless ReleaseRegistry.current_version == release_version page = Page.includes(:restaurant, :menu).find(page_id) ApplicationController.renderer.render( template: "restaurants/show", assigns: { restaurant: page.restaurant, menu: page.menu } ) end end ``` The job does not write full-page HTML into a custom cache key. It simply runs the normal render path so the fragment caches embedded in the page are populated before real users arrive. ### Why warming matters The real bottleneck during cold-cache rebuilds is often **database contention**, not app-server CPU. Many pages go cold simultaneously, each render triggers database queries, and concurrency spikes overwhelm the primary database. Extra app servers don't fix a saturated database. Key techniques for production cache warming: - **Prioritize by traffic**: Warm the top 5,000 most-visited pages first. A page with 10,000 daily visits matters more than one with 100. - **Use read replicas**: Route warming queries to a replica to protect the primary database. - **Rate limit**: Cap warming concurrency to what the database can handle. Sidekiq rate limiters prevent overwhelming the rendering system. - **Stampede prevention**: Use Redis `SET NX` locks to ensure only one worker renders a given page at a time. - **Jittered expiration**: Use `expires_in: 24.hours + rand(0..3600)` instead of fixed TTLs to prevent synchronized mass expiration. ### Real-world impact At Popmenu (a ShakaCode client running React on Rails Pro), cache warming across 37 Sidekiq dynos processing 2,000–8,000 pages per minute produced: - Average TTFB dropped from 320ms to 65ms (-80%) - Server CPU during peak hours dropped 45% - Database connections dropped 35% (fewer concurrent renders) For more details on the full cache warming architecture including stampede prevention, event-driven warming, and monitoring, contact [justin@shakacode.com](mailto:justin@shakacode.com) for consulting on production cache warming strategies. --- ## Confirming and Debugging Cache Keys Cache key composition can be confirmed in development mode with the following steps. The goal is to confirm that some change that should trigger new cached data actually triggers a new cache key. For example, when the server bundle changes, does that trigger a new cache key for any server rendering? 1. Run `Rails.cache.clear` to clear the cache. 1. Run `rails dev:cache` to toggle caching in development mode. You will see a message like: > Development mode is now being cached. You might need to check your `config/development.rb` contains the following: ```ruby # Enable/disable caching. By default caching is disabled. if Rails.root.join("tmp/caching-dev.txt").exist? config.action_controller.perform_caching = true config.cache_store = :memory_store config.public_file_server.headers = { "Cache-Control" => "public, max-age=172800" } # For Rails >= 5.1 determines whether to log fragment cache reads and writes in verbose format as follows: config.action_controller.enable_fragment_cache_logging = true else config.action_controller.perform_caching = false config.cache_store = :null_store end ``` 3. Start your server in development mode. You should see cache entries in the console log. Fetch the page that uses the cache. Make a note of the cache key used for the cached component. 4. Suppose you want to confirm that updated JavaScript causes a cache key change. Make any change to the JavaScript that's server rendered or change the version of any package in the bundle. 5. Check the cache entry again. You should have noticed that it changed. To avoid seeing the cache calls to the prerender_caching, you can temporarily set: ```ruby config.prerender_caching = false ``` ================================================================================ PAGE: https://reactonrails.com/docs/building-features/bundle-caching SOURCE: docs/oss/building-features/bundle-caching.md ================================================================================ # Bundle Caching > **Pro Feature** — Available with [React on Rails Pro](../../pro/react-on-rails-pro.md). > Free or very low cost for startups and small companies. [Upgrade or licensing details →](../../pro/upgrading-to-pro.md#try-pro-risk-free) Bundle caching avoids redundant webpack builds by caching bundles based on a digest of source files. ## Why? Building webpack bundles is often time-consuming, and the same bundles are built many times. For example, you might build the production bundles during CI, then for a Review app, then for Staging, and maybe even for Production. Or you might want to deploy a small Ruby-only change to production, but you will have to wait minutes for your bundles to be built again. ## Solution React on Rails 2.1.0 introduces bundle caching based on a digest of all the source files, defined in the `config/shakapacker.yml` file, plus other files defined with `config.dependency_globs` and excluding any files from `config.excluded_dependency_globs`. Creating this hash key takes at most a few seconds for even large projects. Additionally, the cache key includes 1. NODE_ENV 2. Version of React on Rails Pro 3. Configurable additional env values by supplying an array in method cache_keys on the `remote_bundle_cache_adapter`. See examples below. This cache key is used for saving files to some remote storage, typically S3. ## Bonus for local development with multiple directories building production builds Bundle caching can help save time if you have multiple directories for the same repository. The bundles are cached in `Rails.root.join('tmp', 'bundle_cache')` So, if you have sibling directories for the same project, you can make a sym link so both directories use the same bundle cache directory. ```bash cd my_project2/tmp ln -s ../../my_project/tmp/bundle_cache ``` ## Configuration ### 1. React on Rails Configuration First, we need to tell React on Rails to use a custom build module. In `config/initializers/react_on_rails`, set this value: ```ruby config.build_production_command = ReactOnRailsPro::AssetsPrecompile ``` Alternatively, if you need to run something after the files are built or extracted from the cache, you can do something like this: ```ruby ReactOnRails.configure do |config| # This configures the script to run to build the production assets by webpack. Set this to nil # if you don't want react_on_rails building this file for you. config.build_production_command = CustomBuildCommand end ``` And define it like this: ```ruby module CustomBuildCommand def self.call ReactOnRailsPro::AssetsPrecompile.call end end ``` ### 2. React on Rails Pro Configuration Next, we need to configure the `config/initializers/react_on_rails_pro.rb` with some module, say called S3BundleCacheAdapter. ```ruby config.remote_bundle_cache_adapter = S3BundleCacheAdapter ``` This module needs four class methods: `cache_keys` (optional), `build`, `fetch`, `upload`. See two examples of this below. Also, add whatever file the remote_bundle_cache_adapter module is defined in to `config.dependency_globs`. If there are any other files for which changes should bust the fragment cache for cached_react_component and cached_react_component_hash, add those as well to `config.dependency_globs`. This should include any files used to generate the JSON props, webpack and/or Shakapacker configuration files, and package lockfiles. To simplify your configuration, entire directories can be added to `config.dependency_globs` & then any irrelevant files or subdirectories can be added to `config.excluded_dependency_globs` For example: ```ruby config.dependency_globs = [ File.join(Rails.root, "app", "views", "**", "*.jbuilder") ] config.excluded_dependency_globs = [ File.join(Rails.root, "app", "views", "**", "dont_hash_this.jbuilder") ] ``` will hash all files in `app/views` that have the `jbuilder` extension except for any file named `dont_hash_this.jbuilder`. The goal is that Ruby only changes that don't affect your webpack bundles don't change the cache keys, and anything that could affect the bundles MUST change the cache keys! ### 3. Remove any call to rake task `react_on_rails_pro:pre_stage_bundle_for_node_renderer` This task is called automatically if you're using bundle caching. The automatic staging uses the same bundle-hash cache layout as the renderer's runtime upload flow and the copy-based `react_on_rails_pro:pre_seed_renderer_cache` task used for Docker/image-build workflows. ```ruby # Remove this line — pre-staging is now automatic when bundle caching is enabled. Rake::Task['react_on_rails_pro:pre_stage_bundle_for_node_renderer'].invoke ``` #### Custom ENV cache keys Check your webpack config for the webpack.DefinePlugin. That allows JS code to use `process.env.MY_ENV_VAR` resulting in bundles that differ depending on the ENV value set. Thus, if you access these `process.env.MY_ENV_VAR` in your JS code, then you need to include such ENV vars in return value of the `cache keys` method. A much better approach than accessing `process.env` is to use the `config/initializers/react_on_rails.rb` setting for the`config.rendering_extension` to always pass some values into the rendering props. See [our railsContext docs](../core-concepts/render-functions-and-railscontext.md) for more details. Also, if your webpack build process depends on any ENV values, then you will also need to add those to return value of the `cache_keys` method. Note, the NODE_ENV value is always included in the cache_keys. Another use of the ENV values would be a cache version, so incrementing this ENV value would force a new cache value. ## Disabling via an ENV value Once configured for bundle caching, ReactOnRailsPro::AssetsPrecompile's caching functionality can be disabled by setting ENV["DISABLE_PRECOMPILE_CACHE"] equal to "true" ## Examples of `remote_bundle_cache_adapter`: ### S3BundleCacheAdapter Example of a module for custom methods for the `remote_bundle_cache_adapter`. Note, S3UploadService is your own code that fetches and uploads. ```ruby class S3BundleCacheAdapter # Optional # return an Array of Strings that should get added to the cache key. # These are values to put in the cache key based on either using the webpack.DefinePlugin # or webpack compilation varying by the ENV values. # See the use of the webpack.DefinePlugin. That allows JS code to use # process.env.MY_ENV_VAR resulting in bundles that differ depending on the ENV value set # when building the bundles. # Note, NODE_ENV is automatically included in the default cache key. # Also, we can have an ENV value be a cache version, so incrementing this ENV value # would force a new cache value. def self.cache_keys [Rails.env, ENV['SOME_ENV_VALUE']] end # return value is unused # This command should build the bundles def self.build Rake.sh(ReactOnRails::Utils.prepend_cd_node_modules_directory('yarn start build.prod').to_s) end # parameter zipped_bundles_filename will be a string # should return the zipped file as a string if successful & nil if not def self.fetch(zipped_bundles_filename:) result = S3UploadService.new.fetch_object(zipped_bundles_filename) result.get.body.read if result end # Optional: method to return an array of extra files paths, that require caching. # These files get placed at the `extra_files` directory at the top of the zipfile # and are moved to the original places after unzipping the bundles. def self.extra_files_to_cache [ Rails.root.join("app", "javascript", "utils", "operationStore.json") ] end # parameter zipped_bundles_filepath will be a Pathname # return value is unused def self.upload(zipped_bundles_filepath:) return unless ENV['UPLOAD_BUNDLES_TO_S3'] == 'true' zipped_bundles_filename = zipped_bundles_filepath.basename.to_s puts "Bundles are being uploaded to s3 as #{zipped_bundles_filename}" starting = Process.clock_gettime(Process::CLOCK_MONOTONIC) S3UploadService.new.upload_object(zipped_bundles_filename, File.read(zipped_bundles_filepath, mode: 'rb'), 'application/zip', expiration_months: 12) ending = Process.clock_gettime(Process::CLOCK_MONOTONIC) elapsed = (ending - starting).round(2) puts "Bundles uploaded to s3 as #{zipped_bundles_filename} in #{elapsed} seconds" end end ``` ### LocalBundleCacheAdapter Example of a module for custom methods for the `remote_bundle_cache_adapter` that does not save files remotely. Only local files are used. ```ruby class LocalBundleCacheAdapter def self.cache_keys # if no additional cache keys, return an empty array [] end def self.build Rake.sh(ReactOnRails::Utils.prepend_cd_node_modules_directory('yarn start build.prod').to_s) end def self.fetch(zipped_bundles_filename:) # no-op end def self.upload(zipped_bundles_filepath:) # no-op end end ``` ================================================================================ PAGE: https://reactonrails.com/docs/building-features/accessibility SOURCE: docs/oss/building-features/accessibility.md ================================================================================ # Accessibility (a11y) This page covers accessibility problems caused by the Rails/React boundary in React on Rails and React on Rails Pro apps. It is not a general accessibility handbook. For WCAG rules, ARIA patterns, keyboard behavior, and screen reader basics, use [General Web Accessibility References](#general-web-accessibility-references). **Target: WCAG 2.2 Level AA.** See the [W3C quick reference](https://www.w3.org/WAI/WCAG22/quickref/) for the criteria. These React on Rails terms appear throughout this page: - A **React island** is one React component mounted inside a Rails-rendered page. - A **mount point** is the DOM container where React on Rails mounts that island. - `react_component` is the Rails view helper that writes the mount point and passes props to your component. - `prerender: true` tells React on Rails to render the component HTML on the server; `prerender: false` leaves only the container until JavaScript loads. - **SSR** means server-side rendering: the server sends real HTML in the first response. - **Hydration** is when React attaches client-side behavior to HTML that was rendered on the server. - `stream_react_component` is the React on Rails Pro helper for streaming server-rendered HTML as it becomes ready. - A **render-function** is JavaScript registered with React on Rails to render a component and receive request context. - `railsContext` is request-level data that React on Rails passes to render-functions, such as locale. - **React Server Components (RSC)** are React components that render on the server and do not run browser effects. ## Contents **Framework-specific** 1. [Rails shell vs. React island responsibilities](#1-rails-shell-vs-react-island-responsibilities) 2. [The `react_component` accessibility contract](#2-the-react_component-accessibility-contract) 3. [SSR and hydration](#3-ssr-and-hydration) 4. [Stable IDs in an SSR context](#4-stable-ids-in-an-ssr-context) 5. [Pro streaming SSR and Suspense](#5-pro-streaming-ssr-and-suspense) 6. [React Server Components in React on Rails Pro](#6-react-server-components-in-react-on-rails-pro) 7. [Routing, page transitions, and focus](#7-routing-page-transitions-and-focus) 8. [Rails + React forms](#8-rails--react-forms) 9. [Flash messages, toasts, and async status](#9-flash-messages-toasts-and-async-status) 10. [Fragment caching and accessibility freshness](#10-fragment-caching-and-accessibility-freshness) 11. [Internationalization through railsContext / RSC](#11-internationalization-through-railscontext--rsc) 12. [Testing in React on Rails](#12-testing-in-react-on-rails) 13. [Hydration and accessibility debugging](#13-hydration-and-accessibility-debugging) **General references** - [General Web Accessibility References](#general-web-accessibility-references) --- ## 1. Rails shell vs. React island responsibilities When Rails renders the page shell and React renders islands inside it, screen readers get one combined page. If both sides add the same page structure, users hear duplicate landmarks, duplicate headings, or missing context. Fix this by deciding which side owns each page-level item. | Concern | Usually owned by | | ---------------------------------------------------- | ---------------------------------------------------- | | `<html lang>`, `dir`, `<title>`, meta | Rails layout (ERB) | | Landmarks: `<header>`, `<nav>`, `<main>`, `<footer>` | Rails layout, usually | | Skip links | Rails layout | | The single `<h1>` | Decide explicitly: layout or island | | Flash messages container + live region | Rails layout, with React writing into it when needed | | Interactive widgets, focus management, live updates | React islands | Use `react_component` when Rails should place a React island on the page: ```erb <%= react_component( "ProductSummary", props: { product_id: @product.id }, prerender: true ) %> ``` Guidance: - If the Rails layout already has `<main>`, the island should not render another `<main>`. - Pick one owner for the page `<h1>`. If the island renders it, the layout should not. - Use `prerender: true` for content that must exist in the first HTML response. - Use `prerender: false` only for client-only widgets where an empty first response is acceptable. --- ## 2. The `react_component` accessibility contract When you call `react_component`, React on Rails writes a container element. React then mounts your component inside that container as its children. The container stays in the DOM and in the accessibility tree. If you omit an `id`, React on Rails auto-assigns one to the container. ```erb <%= react_component("AccountMenu", props: { signed_in: true }) %> ``` - **Wrapper element and `tag`.** The default container is a `<div>`. That is usually fine because a plain `<div>` has no landmark or widget meaning. If the container itself needs attributes, pass them through `html_options`. To change the container element, put `tag` inside `html_options`. (The `tag` option applies to `react_component` only — the `react_component_hash` helper always renders a `<div>` container.) ```erb <%= react_component( "InlineBadge", props: { text: "New" }, id: "account-badge", html_options: { tag: "span", class: "badge" } ) %> ``` - **The real wrapper pitfall is duplicate semantics.** Do not put a landmark role on the container if your component already renders the same landmark inside it. Before: this creates two navigation landmarks. ```erb <%= react_component( "HeaderNav", props: {}, html_options: { role: "navigation", "aria-label": "Main" } ) %> ``` ```jsx export default function HeaderNav() { return <nav aria-label="Main">...</nav>; } ``` After: keep the container neutral and let the component own the landmark. ```erb <%= react_component("HeaderNav", props: {}) %> ``` ```jsx export default function HeaderNav() { return <nav aria-label="Main">...</nav>; } ``` - **Set the container `id` with the top-level `id:` option, not inside `html_options`.** React on Rails overwrites `html_options[:id]` with the value from the top-level `id:` option (or an auto-generated id), so an `id` placed inside `html_options` is ignored. Put `class`, `style`, `role`, and `aria-*` in `html_options`; put `id` at the top level. (`role="status"` already implies `aria-live="polite"`, so it is not repeated here.) ```erb <%= react_component( "SaveStatus", props: { state: "saving" }, id: "save-status", html_options: { role: "status" } ) %> ``` - **Keep container IDs and internal IDs separate.** The container `id` comes from the top-level `id:` option (or is auto-generated). Your component still needs its own stable IDs for labels, descriptions, and ARIA relationships inside the island. See section 4. - **Server and client must agree.** Do not set a wrapper role or ARIA attribute in ERB that the hydrated React tree contradicts. The markup inside the component follows normal web accessibility rules: native elements first, labels for inputs, names for icon-only buttons, visible focus, and correct keyboard behavior. For those rules, use [WAI-ARIA APG](https://www.w3.org/WAI/ARIA/apg/patterns/) and [MDN Accessibility](https://developer.mozilla.org/en-US/docs/Web/Accessibility). --- ## 3. SSR and hydration When you use `prerender: false`, the first HTML response contains the container but not the component content. Screen readers and no-JS users get an empty island until the JavaScript bundle loads. Fix this by using `prerender: true` for content-bearing islands. ```erb <%= react_component("ArticleBody", props: { article_id: @article.id }, prerender: true) %> <%= react_component("ColorSchemeToggle", props: {}, prerender: false) %> ``` React hydration then attaches event handlers and client behavior to the server-rendered HTML. The accessibility risk is that users can reach HTML before hydration is done. Guidance: - Keep server and client output deterministic. Do not use `Date.now()`, `Math.random()`, browser-only checks, or client-only locale detection in render output. - Pass request data from Rails as props, or read it from `railsContext` in a render-function, so server and client render the same text. - Do not hide hydration warnings with `suppressHydrationWarning` unless you have confirmed the mismatch is harmless. - A prerendered button is announced as a button before its `onClick` works. For critical actions, use a real form submit that works without JavaScript, or render an honest pending state until hydration finishes. - Do not move focus in a mount effect on first page load. Move focus only after a user action, such as route navigation or opening a dialog. For React's general hydration behavior, see [`hydrateRoot`](https://react.dev/reference/react-dom/client/hydrateRoot). --- ## 4. Stable IDs in an SSR context When an input points to a label or error message by `id`, the `id` must be the same on the server and client. It must also be unique on the page. If it changes during hydration, screen readers can lose the label or description. This is easy to break in React on Rails because the same component can be mounted more than once with `react_component`. Do not hard-code IDs inside reusable islands. Do not generate IDs with `Math.random()` or a module-level counter. Use React's [`useId`](https://react.dev/reference/react/useId) for IDs that must match SSR and hydration. ```jsx import { useId } from 'react'; export default function EmailField({ error }) { const id = useId(); const errorId = `${id}-error`; return ( <> <label htmlFor={id}>Email</label> <input id={id} type="email" aria-invalid={error ? 'true' : undefined} aria-describedby={error ? errorId : undefined} /> {error && <p id={errorId}>{error}</p>} </> ); } ``` **With the open-source package, `useId` is not enough when you mount the same component more than once on a page.** `useId` keeps an id stable between the server render and hydration _within one mount_, but React only guarantees uniqueness _across_ separate roots when each root is given a distinct [`identifierPrefix`](https://react.dev/reference/react-dom/client/hydrateRoot#parameters). The open-source React on Rails package does not set a per-mount `identifierPrefix`, so two mounts of the same component can produce the same `useId` value (for example `«r0»`) and collide. (React on Rails Pro sets `identifierPrefix` to the container DOM id automatically on the default RSC-provider path — when RSC support is enabled — so `useId` is already safe there. On any other path, follow the open-source guidance below and pass an explicit prefix; doing so is always safe regardless of tier.) When a component can appear more than once on a page, pass a unique prefix into it — the container `id` you set with the top-level `id:` option (section 2) works well — and build your ARIA ids from that. Use the same value for `id:` and the prefix prop so they stay in sync: ```erb <%# Each mount gets a unique id; the same value is threaded in as the prefix prop. Prop keys are passed through verbatim (React on Rails does not camelize them), so use the same `idPrefix` key the component reads. %> <%= react_component("EmailField", props: { idPrefix: "signup-email" }, id: "signup-email") %> <%= react_component("EmailField", props: { idPrefix: "contact-email" }, id: "contact-email") %> ``` ```jsx export default function EmailField({ idPrefix, error }) { const errorId = `${idPrefix}-email-error`; // ...use `${idPrefix}-email` for the input id, etc. } ``` --- ## 5. Pro streaming SSR and Suspense When you use `stream_react_component`, React on Rails Pro can send server-rendered HTML in pieces as work finishes. Screen readers still read the DOM in logical order, not your loading plan. Fix this by making each streamed `Suspense` boundary match the reading order of the page. Guidance: - Keep streamed chunks in the same order a user should read them. - Mark loading regions as busy with `aria-busy` while content is still pending. - Do not wrap a large streamed subtree (such as a full result list) in `aria-live` — that queues the entire subtree for announcement and overwhelms screen-reader users. Instead, announce a short message like "Results loaded" in the page's shared live region (section 9) once the content commits. - Reserve `aria-live` for small, deliberately announced status text, and set that text after the real content commits so the announcement is not missed or repeated. - Do not move focus when a late chunk arrives. Preserve the user's current focus. - Mark skeleton placeholders as decorative. ```jsx function ResultsRegion({ loading, children }) { // `aria-busy` signals loading; a plain <div> avoids implying a landmark. return ( <div aria-busy={loading ? 'true' : undefined}> {loading ? <div aria-hidden="true" className="skeleton" /> : children} </div> ); } ``` --- ## 6. React Server Components in React on Rails Pro When part of the page is a React Server Component, that part can render HTML but cannot run browser effects. If focus movement, keyboard handlers, or live-region updates live only in a server component, they will not run in the browser. Fix this by putting browser behavior in client components and keeping server components for static, semantic HTML. Guidance: - Put focus management, keyboard handlers, live-region updates, and effect-driven ARIA in client components. - Use server components for headings, articles, navigation markup, and other static content that does not need hydration. - Use Rails-owned data consistently. If an accessible name depends on locale, permissions, or user state, make sure the server-rendered content and any hydrated client component receive the same value. - If a form returns server-side validation errors, surface those errors with the same accessible pattern described in section 8. The accessibility guidance above is what is specific to the server/client split. For the RSC helper names, the config flag that enables RSC mode, and how to register server vs. client components — which are version-dependent — see the [React on Rails Pro React Server Components docs](../../pro/react-server-components/index.md). --- ## 7. Routing, page transitions, and focus When a React island changes routes without a full page load, the browser does not automatically announce a new page. Focus may stay on a link or button from the old view. Fix this with the standard SPA pattern: - Update `document.title`. - Move focus to the new view's `<h1 tabIndex={-1}>` or `<main tabIndex={-1}>`. - Write the new page name into one visually hidden `aria-live="polite"` route announcer. What is specific to React on Rails is where this code lives. - If React Router, TanStack Router, or another client router runs inside an island, hook this behavior into that router's navigation events. - If Rails or Turbo changes the page, run the same behavior after the new page loads. For Turbo, that usually means the `turbo:load` event. - Keep one route announcer for the page. Do not create one announcer per island. - Make sure skip links still point to the current main content after navigation. A minimal announcer inside a router island, reusing the shared live region from section 9: ```jsx import { useEffect, useRef } from 'react'; import { useLocation } from 'react-router-dom'; // or your router's equivalent // Inside a React Router / TanStack Router island function RouteAnnouncer() { const { pathname } = useLocation(); // or the router's location hook const firstRender = useRef(true); useEffect(() => { // Skip the initial mount during hydration — only announce real navigations, // and do not steal focus on first page load (see "SSR and hydration"). if (firstRender.current) { firstRender.current = false; return undefined; } const region = document.getElementById('app-live-region'); if (!region) return undefined; // Clear first, then set on the next tick so the change is announced. region.textContent = ''; const rafId = requestAnimationFrame(() => { region.textContent = `Navigated to ${document.title}`; // Move focus after the new content has painted. document.querySelector('main')?.focus(); // <main tabIndex={-1}> }); return () => cancelAnimationFrame(rafId); }, [pathname]); return null; } ``` For the general SPA pattern, see [Gatsby's user testing of accessible client-side routing](https://www.gatsbyjs.com/blog/2019-07-11-user-testing-accessible-client-routing/) and [Deque's SPA accessibility tips](https://www.deque.com/blog/accessibility-tips-in-single-page-applications/). --- ## 8. Rails + React forms When Rails validates a form on the server and React renders the fields, errors can land in the wrong place or lose their label relationship. Fix this by passing Rails errors into the island once, then rendering one accessible error UI in React. Guidance: - Map the Rails `errors` hash to field-level errors and one top-of-form summary. - Do not render the same error once in ERB and again in React. - Keep each label connected to its input with matching `for` and `id`. - Keep `aria-describedby` pointed at the error message after hydration. - If the server prerenders an error state, the hydrated React output must use the same IDs and text. - If the form island can be mounted more than once on a page, pass a unique `idPrefix` prop (section 4) instead of relying on `useId` alone, so the OSS path does not produce colliding field IDs. ```jsx function NameField({ idPrefix, value, error }) { const id = `${idPrefix}-name`; const errorId = `${id}-error`; return ( <div> <label htmlFor={id}>Name</label> <input id={id} name="name" defaultValue={value} aria-invalid={error ? 'true' : undefined} aria-describedby={error ? errorId : undefined} /> {error && <p id={errorId}>{error}</p>} </div> ); } ``` For the general form rules, see the [WAI forms tutorial](https://www.w3.org/WAI/tutorials/forms/). --- ## 9. Flash messages, toasts, and async status When Rails flash messages and React toasts each create their own live region, screen readers may announce the same message twice or miss one. Fix this by creating one persistent live region in the Rails layout. Rails can render the first message there, and React islands can update the same region later. ```erb <%# Seed any first-load flash so it is present in the initial HTML response %> <div id="app-live-region" role="status" aria-atomic="true"> <%= flash[:notice] || flash[:alert] %> </div> ``` `role="status"` already implies `aria-live="polite"`, so that is not repeated. `aria-atomic="true"` is set explicitly so screen readers announce the whole message rather than only the changed text node. If the region holds only screen-reader announcements (not visible text), hide it **visually** — not from assistive technology. `display: none` and `visibility: hidden` suppress announcements; use the clip pattern instead: ```css .sr-only { position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip: rect(0, 0, 0, 0); white-space: nowrap; border: 0; } ``` If the same element also renders visible flash messages, leave it visible — no hiding needed. Guidance: - The live region should exist before the message text is inserted. - When updating the region, clear it first and set the new text on the next tick (`region.textContent = ''; requestAnimationFrame(() => { region.textContent = message; })`). Some older screen readers (e.g. JAWS, NVDA in certain modes) do not announce text injected into a region that was empty on first load; the clear-then-set pattern avoids that silent failure. - Use the same region for Rails flash, React toasts, and async status such as "Saving", "Saved", and "Failed". - Use `role="alert"` only for urgent messages that require interruption. - Do not auto-dismiss messages before users have time to read them. For general live-region behavior, see [MDN on live regions](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions). --- ## 10. Fragment caching and accessibility freshness When Rails caches HTML around a `react_component` call, it can also cache accessible names, ARIA attributes, and visible controls. If the cache key is too broad, screen readers get stale or wrong information. Fix this by including every accessibility-affecting input in the cache key, or by keeping that state out of the cached fragment. Cache keys must include anything that affects: - Locale and text direction. - Translated visible text and accessible names. - Permissions and role-based controls. - User-specific labels, such as "Log out, Jane". - Feature-flagged controls and their labels. Do not cache per-request or interactive ARIA state: - `aria-expanded` - `aria-pressed` - `aria-selected` - `aria-current` - live-region text Before caching a fragment, ask: does any label, role, ARIA attribute, or visible control depend on user, request, locale, or feature flag state? If yes, put that input in the key or render that piece outside the cache. --- ## 11. Internationalization through railsContext / RSC When Rails and React choose locale or direction separately, the server HTML can say one thing and the hydrated client can replace it with another. Screen readers may pronounce text with the wrong language rules, and React may hit hydration mismatches. Fix this by using one request-level source for locale and direction. Guidance: - Set `<html lang>` and `dir` in the Rails layout from the request locale. - Use `railsContext` in render-functions when a component needs request-level data such as locale. - Pass the same locale and direction into islands that branch on language or layout direction. - Apply the same rule to RSC output: server-rendered content and hydrated client components should use the same locale and direction. - Do not re-detect locale on the client if Rails already knows it. In production, prefer a single source of truth for direction — many i18n setups expose it (for example `rails-i18n` locale files carry direction metadata), and a shared helper avoids duplicating a language list. The snippet below is a minimal, **non-exhaustive** illustration; the `rtl_subtags` list omits many RTL locales (`ks`, `ku-Arab`, `pa-Arab`, …) and should not be copied verbatim into an app that needs broad coverage. ```erb <%# Minimal example only — derive `dir` from your i18n metadata in real apps. %> <% rtl_subtags = %w[ar he fa ur yi ug dv ps sd ckb] %> <% primary_subtag = I18n.locale.to_s.split(/[-_]/).first # handles ar-EG and ar_EG %> <%= react_component( "LocalizedNav", props: { locale: I18n.locale.to_s, dir: rtl_subtags.include?(primary_subtag) ? "rtl" : "ltr" }, prerender: true ) %> ``` For general RTL and `dir` behavior, see [MDN on `dir`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/dir). --- ## 12. Testing in React on Rails When a React on Rails page uses SSR, the first HTML response and the hydrated browser page can have different accessibility bugs. Testing only the hydrated React tree misses the no-JS baseline. Fix this by testing both states. Guidance: - Run automated checks against the server-rendered HTML from `prerender: true`. - Run automated checks again after hydration in a real browser. - Test important pages with JavaScript disabled. This confirms the accessible baseline exists before hydration. - For `stream_react_component`, wait for the streamed content to finish before asserting. - For forms, test the server-rendered error state and the hydrated error state. - If strict CSP blocks injected axe scripts or streaming test scripts, fix the test setup rather than weakening production accessibility checks. Use tools such as `jest-axe`, `vitest-axe`, `axe-core`, `pa11y`, Lighthouse, Capybara system tests, or Playwright with `@axe-core/playwright`. Add manual keyboard and screen reader passes for streaming, navigation, dialogs, and live-region flows. --- ## 13. Hydration and accessibility debugging When an accessibility bug appears only after the JavaScript bundle loads, debug the Rails output and the hydrated React output separately. | Symptom | Likely cause | Where to look | | ------------------------------------------------- | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Screen reader reads stale or duplicated labels | Duplicate IDs from a component mounted more than once | Section 4; pass a per-mount `idPrefix` (`useId` alone collides across roots on the OSS package and every Pro path except the default RSC-provider path, which sets `identifierPrefix` automatically) | | `aria-describedby` points at nothing after load | ID differs between server and client | Non-deterministic ID generation | | Button is announced but does nothing | Control rendered before hydration attached handlers | Section 3; add no-JS fallback or pending state | | Hydration warning and visual flicker | Server markup differs from client markup | Dates, random values, locale, browser-only branches | | Streamed content is read in the wrong order | DOM order differs from logical reading order | Section 5; align `Suspense` boundaries | | Announcement is missed or doubled while streaming | Live-region text changed before content committed, or changed twice | Section 5; update after commit and guard repeats | | Content is missing for no-JS users | `prerender: false`, or SSR failed and the page fell back to client-only output | Sections 1 and 3; check the Rails log for `ReactOnRails::PrerenderError` and the Node render-server output (stdout of the JS server process). `config.raise_on_prerender_error` (on by default in development) surfaces these failures instead of silently falling back to client-only output. | **Portals and modals (SSR note).** If a dialog's DOM is created only after hydration, keyboard and screen reader users do not get a usable dialog in the first response. Fix this by not showing the dialog until JavaScript is ready, or by rendering an accessible non-portal fallback. After hydration, follow the [APG dialog pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/) or use a vetted dialog component. --- ## General Web Accessibility References Short checklist: follow the links for the actual rules. This page does not restate them. - **WCAG 2.2 AA** - the standard we target. [Quick reference](https://www.w3.org/WAI/WCAG22/quickref/). - **Semantic HTML** - native elements first. [MDN HTML elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Element), [WAI tutorials](https://www.w3.org/WAI/tutorials/). - **ARIA fundamentals** - ARIA is not a substitute for native HTML. [WAI-ARIA APG](https://www.w3.org/WAI/ARIA/apg/). - **Complex widget keyboard patterns** - combobox, menu, dialog, tabs, and similar widgets. [APG patterns](https://www.w3.org/WAI/ARIA/apg/patterns/). - **Color contrast, reduced motion, target size** - PR checklist items. [WCAG contrast](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html), [`prefers-reduced-motion`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion), [target size](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html). - **Images, icons, media** - for alt text and captions. [WAI images tutorial](https://www.w3.org/WAI/tutorials/images/). - **Screen reader usage** - driving [VoiceOver](https://www.apple.com/voiceover/info/guide/), [NVDA](https://www.nvaccess.org/), and JAWS for manual testing. ================================================================================ PAGE: https://reactonrails.com/docs/building-features/forms SOURCE: docs/oss/building-features/forms.md ================================================================================ # Forms and Mutations with `useRailsForm` Wiring a React form to a Rails controller by hand means reading the CSRF token, building a `fetch` call, serializing the body, mapping Rails model errors back onto fields, and tracking a `processing` flag. `useRailsForm` makes that turnkey while keeping Rails as the mutation layer: your form posts JSON to a **real Rails controller action** — the same strong parameters, ActiveModel validations, and authorization a server-rendered form would use. No API layer, no client-side validation duplication, no new protocol. There are two pieces, both opt-in: 1. **`useRailsForm`** (npm package) — a React hook with `data`/`setData`, `errors`, `processing`, submit verbs, and automatic CSRF attachment. 2. **`ReactOnRails::Controller::FormResponders`** (gem) — a controller concern whose `render_model_errors(record)` renders ActiveModel errors in the JSON shape the hook expects. The contract between them is one blessed error shape: ```json // HTTP 422 { "errors": { "name": ["can't be blank"], "email": ["is invalid"] } } ``` The hook works against **any** endpoint returning that shape; the concern is a convenience, not a requirement. For the framework-level comparison with Next.js Server Actions and TanStack Start server functions, see [Mutations without Server Actions](./mutations.md). Compatibility: `react-on-rails/useRailsForm` requires React 16.8 or newer because it is a hook. Apps still on React 16.0-16.7 can continue using the package's other React 16 APIs, but this subpath throws a clear error until React is upgraded to a hooks-capable version. ## Quick start ### Client ```tsx import React from 'react'; import { useRailsForm } from 'react-on-rails/useRailsForm'; export default function ContactForm() { const form = useRailsForm({ name: '', email: '', message: '' }); const handleSubmit = (event: React.FormEvent<HTMLFormElement>) => { event.preventDefault(); void form .post('/contact_messages', { onSuccess: () => form.reset(), }) .catch(() => { form.setError('base', 'Something went wrong. Please try again.'); }); }; return ( <form onSubmit={handleSubmit}> <input value={form.data.name} onChange={(e) => form.setData('name', e.target.value)} /> {form.errors.name?.[0] && <p className="error">{form.errors.name[0]}</p>} <input value={form.data.email} onChange={(e) => form.setData('email', e.target.value)} /> {form.errors.email?.[0] && <p className="error">{form.errors.email[0]}</p>} <textarea value={form.data.message} onChange={(e) => form.setData('message', e.target.value)} /> {form.errors.message?.[0] && <p className="error">{form.errors.message[0]}</p>} <button type="submit" disabled={form.processing}> {form.processing ? 'Sending…' : 'Send'} </button> </form> ); } ``` ### Server ```ruby 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) # 422 + { errors: { field: [messages] } } end end private def contact_message_params # useRailsForm posts a flat JSON body; Rails JSON params wrapping (on by # default for new apps) may also nest it under :contact_message — accept both. if params.key?(:contact_message) params.require(:contact_message).permit(:name, :email, :message) else params.permit(:name, :email, :message) end end end ``` That's the whole round trip: submitting invalid data renders per-field errors under each input; fixing them and resubmitting succeeds. Validations stay in the model — the client renders whatever the server says. A runnable example lives in the dummy app: `react_on_rails/spec/dummy/client/app/startup/RailsFormExample.client.tsx` (rendered at `/rails_form`) posting to `react_on_rails/spec/dummy/app/controllers/contact_messages_controller.rb`. ## What the hook sends Every submit issues a `fetch` with: - the HTTP method you chose (`post`, `put`, `patch`, `delete`, or `submit(method, url)`), - `Content-Type: application/json` and `Accept: application/json`, - `X-CSRF-Token` read from the standard Rails `<meta name="csrf-token">` tag (via the same `authenticityToken`/`authenticityHeaders` utilities exposed on the `ReactOnRails` object) plus `X-Requested-With: XMLHttpRequest`, - `credentials: 'same-origin'` so the Rails session cookie is included, - `JSON.stringify(data)` as the body — except for `delete`, which sends **no body** (DELETE bodies are legal per RFC 9110 but are stripped or rejected by many proxies and CDNs in practice; put the resource identifier in the URL). The CSRF token is read from the meta tag at submit time, so a token rendered with the page is picked up without any configuration. Your layout must render `<%= csrf_meta_tags %>` (the Rails default) — without the meta tag the hook throws before calling `fetch`, so the form cannot accidentally submit as an anonymous or reset session. If your app rotates tokens during long-lived sessions, refresh the meta tag (e.g., re-render it after sign-in) — the next submit reads the current value. Field keys are passed through untouched: if your Rails model says `errors: { first_name: [...] }`, the hook gives you `form.errors.first_name`. Use snake_case keys in `data` to match your strong parameters (a `transform` option for key mapping is planned — see [Scope and roadmap](#scope-and-roadmap)). ## Hook API ```ts const form = useRailsForm(initialData); ``` | Member | Description | | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `data` | Current form data (typed from `initialData`). | | `setData(key, value)` | Set one field. Also accepts a partial object (`setData({ a, b })`) or an updater function. | | `errors` | `{ field: ["message", ...] }` from the last 422 response. | | `hasErrors` | `true` when `errors` is non-empty. | | `processing` | `true` while a submission is in flight. | | `wasSuccessful` | `true` once the most recent submission succeeded. | | `post/put/patch/delete(url, options?)` | Submit `data` with that verb. Returns a promise of the submit result. `delete` sends no request body — put the resource id in the URL. | | `submit(method, url, options?)` | Submit with an explicit method. | | `reset(...fields)` | Restore all (or the given) fields to their initial values; clears matching errors and `wasSuccessful`. Initial values are the `initialData` from the first render — later prop changes are not tracked (Inertia `useForm` semantics); remount to re-seed. | | `clearErrors(...fields)` | Clear all (or the given) field errors. | | `setError(field, messages)` | Set errors for one field manually. | | `RailsFormRequestError` | Exported error class (import separately; it is not a `form` member) for non-2xx responses other than a mappable 422; carries the unread `Response` plus `responseBody` (parsed JSON) for an unmappable 422. | Per-submit `options`: `headers` (merged in; CSRF headers always win), `onSuccess(result)`, and `onError(errors)`. Calling `reset()` inside `onSuccess` starts a fresh editing cycle immediately, so `wasSuccessful` is also reset to `false`. Keep separate success-message state if the UI needs to keep showing a success banner after clearing the fields. Response handling: - **2xx** — `wasSuccessful` flips on, `errors` clears, and `onSuccess` receives `{ responseData, redirectTo, response }`. - **422 with the documented `errors` shape** — `errors` is populated per field (single strings are normalized to arrays) and `onError` is called. An empty `errors` object is still handled as a validation response with `{ ok: false, errors: {}, response }`. The promise resolves with `{ ok: false, errors, response }`. - **Anything else** (including a 422 whose body doesn't match) — the promise rejects with `RailsFormRequestError`; network failures reject with the original fetch error. - **Superseded submissions** — when an older in-flight submit settles after a newer submit has started, it resolves with `{ ok: false, stale: true }` plus the stale `response` or `error`. Stale submits do not update form state, call submit callbacks, or reject into an older `.catch()` handler after the newer submit has won. ## Redirects and `onSuccess` The hook never navigates on its own. After a successful submit it surfaces a redirect target as `result.redirectTo` when the JSON body contains a `redirect_to` (or `redirectTo`) string hint pointing to a same-origin URL. Native fetch redirects are disabled for CSRF-bearing submissions (`redirect: 'error'`), so a Rails `redirect_to` response rejects instead of being followed in v1. Relative hints resolve like browser URLs against the current page URL: for example, `"?saved=1"` preserves the current path and changes only the query. Return an explicit root-relative path such as `"/posts/1?saved=1"` when the redirect should ignore the current page path. Pass it to whatever owns navigation in your app: ```tsx void form.post('/posts', { onSuccess: ({ redirectTo }) => { if (redirectTo) window.location.assign(redirectTo); }, }); ``` This design is intentionally forward-compatible with the client-routing integration tracked in [Issue 3873](https://github.com/shakacode/react_on_rails/issues/3873): when a client router is present, hand `redirectTo` to the router instead of `window.location`. ## The controller concern `ReactOnRails::Controller::FormResponders` ships with the `react_on_rails` gem and adds one helper: ```ruby render_model_errors(record, status: 422) ``` It renders `record.errors.messages` (any ActiveModel/ActiveRecord object) as `{ errors: { field: [messages] } }`. It is deliberately tiny: if your API already returns errors another way (JSON:API, custom serializers), keep it — just map your shape to the documented one at the endpoint the form posts to. Pass numeric HTTP status codes such as `400` or `422`; Rails status symbols are intentionally rejected so Rack/Rails status-symbol renames cannot change the wire response. Because those ActiveModel messages are sent to the browser verbatim, review custom validations for internal IDs, admin-only details, or security-sensitive wording before using the concern on a model. ## Comparison with Inertia's `useForm` `useRailsForm` deliberately mirrors the parts of [Inertia.js `useForm`](https://inertia-rails.dev/guide/forms) teams use for CRUD, without coupling your controllers to a response protocol — the endpoint stays a normal Rails JSON action you can curl or reuse for mobile clients. | Inertia `useForm` | `useRailsForm` | | ---------------------------------- | ---------------------------------------- | | `data`, `setData` | `data`, `setData` (same overloads) | | `errors` (`string` per field) | `errors` (`string[]` per field) | | `processing` | `processing` | | `wasSuccessful` | `wasSuccessful` | | `post/put/patch/delete(url)` | `post/put/patch/delete(url)` | | `reset`, `clearErrors`, `setError` | `reset`, `clearErrors`, `setError` | | `transform(fn)` | Planned (v2) | | `recentlySuccessful` | Planned (v2) | | `progress` (file uploads) | Planned (v2 — requires an XHR transport) | | Automatic visit/redirect | Not automatic — `redirectTo` is surfaced | Versus React 19 / Next.js `useActionState` + `useFormStatus`: those pair with Server Actions (`'use server'`), which introduce an RPC endpoint per action. React on Rails intentionally keeps mutations in Rails controllers — `useRailsForm` is the ergonomic path for that, and the separate [Server Functions RFC (Issue 3867)](https://github.com/shakacode/react_on_rails/issues/3867) explores the complementary RSC-side story. The two are designed to compose: if Server Functions land, this hook remains the plain-controller bridge. For side-by-side migration examples, see [Mutations without Server Actions](./mutations.md). ## Scope and roadmap v1 is fetch-only and covers submit verbs, `data`/`setData`, `errors`, `processing`, `wasSuccessful`, CSRF auto-attach, and 422 error mapping ([Issue 3872](https://github.com/shakacode/react_on_rails/issues/3872)). Deferred to a follow-up release: `transform`, `recentlySuccessful`, `onFinish`, and file uploads with `progress` (which needs an `XMLHttpRequest`/duplex-stream transport). Navigation, prefetching, and router integration belong to [Issue 3873](https://github.com/shakacode/react_on_rails/issues/3873). ================================================================================ PAGE: https://reactonrails.com/docs/building-features/mutations SOURCE: docs/oss/building-features/mutations.md ================================================================================ # Mutations without Server Actions React on Rails keeps mutations in Rails. React Server Components change how read-only UI can be rendered and streamed, but they do not move writes into the Node renderer. A React form, button, or TanStack Query mutation should submit to a Rails route, let the controller run the same authentication, authorization, strong parameters, ActiveRecord transactions, and validations that a server-rendered Rails form would use, then return JSON or navigate. Do **not** add `'use server'` to React on Rails application code. In React on Rails, the Node renderer is a rendering process. It does not own Rails models, sessions, cookies, CSRF verification, or transactions. Use a Client Component, a standard Rails form, or a TanStack Query mutation that calls a Rails controller endpoint. ## Side-by-side map | Concern | Next.js Server Actions | TanStack Start server functions | React on Rails | | ----------------------- | ------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Client call site | `<form action={createPost}>`, `formAction`, or an event handler that invokes a Server Function. | `createServerFn({ method: 'POST' })`, often called from a component, loader, hook, event handler, or TanStack Query mutation. | `form_with`, `useRailsForm`, `createRailsAction`, or a CSRF-aware `fetch`/TanStack Query mutation. | | Where server logic runs | The Next.js app server, inside an async function marked with `'use server'` or exported from a `'use server'` file. | The TanStack Start server, inside the `createServerFn` handler. | The Rails controller action, backed by Rails models, policies, jobs, mailers, and transactions. | | Request shape | Framework-owned POST request to the Server Action endpoint. | Framework-owned same-origin RPC request to the server function endpoint. | Ordinary Rails HTTP route, usually JSON for React islands or a normal HTML form post for full-page flows. | | Security boundary | Verify authentication and authorization inside the action; Next.js applies same-origin Server Action protections. | Validate input in the server function; Start documents same-origin RPC and CSRF middleware for server functions. | Use Rails sessions, `csrf_meta_tags`, controller filters, strong parameters, and policy checks. React helpers attach CSRF headers for JSON requests. | | Validation errors | Return serializable error state or throw/redirect according to the action pattern. | Return serializable error state, throw, redirect, or feed TanStack Query mutation state. | Return `422` JSON such as `{ "errors": { "name": ["can't be blank"] } }`; `useRailsForm` maps this to field errors. | | After the write | Call Next cache revalidation helpers, redirect, or return updated UI/data. | Invalidate TanStack Query cache, redirect, or update route state. | Let Rails redirect for full-page flows, return a safe `redirect_to` JSON hint, invalidate TanStack Query cache, or let the next Rails render stream fresh props. | The practical translation is: - **Next.js Server Action**: "call this server function from my form." - **TanStack Start server function**: "call this typed same-origin server function from my app." - **React on Rails**: "call this Rails controller route from my React UI." ## Same mutation in three stacks The same "create a project" mutation lands in a different server boundary in each stack. In Next.js, the form can call a Server Action; the database write, authorization, and cache refresh live in the Next.js server runtime: ```tsx // app/projects/actions.ts 'use server'; import { revalidatePath } from 'next/cache'; import { redirect } from 'next/navigation'; import { db } from '@/lib/db'; export async function createProjectAction(formData: FormData) { const name = String(formData.get('name') ?? '').trim(); const status = String(formData.get('status') ?? 'draft'); if (!name) { return { errors: { name: ["can't be blank"] } }; } const project = await db.project.create({ data: { name, status } }); revalidatePath('/projects'); redirect(`/projects/${project.id}`); } ``` ```tsx // app/projects/form.tsx import { createProjectAction } from './actions'; export function ProjectForm() { return ( <form action={createProjectAction}> <input name="name" /> <select name="status" defaultValue="draft"> <option value="draft">Draft</option> <option value="active">Active</option> </select> <button type="submit">Create project</button> </form> ); } ``` In TanStack Start, the component can call a server function. The handler still runs in Start's server runtime, not in Rails: ```ts // src/projects/projects.functions.ts import { createServerFn } from '@tanstack/react-start'; import { z } from 'zod'; import { db } from '~/server/db'; const projectSchema = z.object({ name: z.string().min(1), status: z.enum(['draft', 'active']), }); export const createProject = createServerFn({ method: 'POST' }) .validator(projectSchema) .handler(async ({ data }) => { const project = await db.project.create({ data }); return { project }; }); ``` ```tsx // src/projects/ProjectForm.tsx import { createProject } from './projects.functions'; await createProject({ data: { name: 'Apollo', status: 'draft' } }); ``` In React on Rails, the Client Component calls an ordinary Rails route. The Rails controller, shown in the recipe below, owns authentication, authorization, strong parameters, transactions, validation errors, redirects, jobs, and cache expiry: ```ts import { createRailsAction } from 'react-on-rails/railsAction'; type ProjectFormData = { name: string; status: 'draft' | 'active'; }; type ProjectResponse = { project: { id: number; name: string; status: string }; }; const createProject = createRailsAction<{ project: ProjectFormData }, ProjectResponse>({ path: '/projects', }); await createProject({ project: { name: 'Apollo', status: 'draft' } }); ``` ## Choose the Rails entry point Use the narrowest path that matches the UI: - **Standard Rails forms**: best when a full-page submit and redirect are acceptable, or when the feature should work without JavaScript. - **[`useRailsForm`](./forms.md)**: best for React-controlled forms that need field errors, `processing`, reset behavior, CSRF handling, and a small `useForm`-style API. - **[`createRailsAction`](./generated-rails-response-types.md#use-with-typed-rails-actions) with TanStack Query**: best for buttons, tables, optimistic updates, and typed mutation responses. - **Manual `fetch` with React on Rails authenticity helpers**: fine for one-off calls, but centralize same-origin, JSON, and CSRF behavior once the pattern repeats. ## Recipe: React form, Rails controller This is the Rails-native equivalent of a Next.js `<form action={createPost}>` Server Action or a TanStack Start `createServerFn({ method: 'POST' })` mutation: keep the server logic in Rails and make the Client Component submit JSON to that route. ### Rails route and controller ```ruby # config/routes.rb resources :projects, only: [:new, :create, :show] ``` ```ruby # app/controllers/projects_controller.rb class ProjectsController < ApplicationController include ReactOnRails::Controller::FormResponders def create project = current_account.projects.build(project_params) # Run your normal authorization here, for example `authorize project`. if project.save render json: { project: { id: project.id, name: project.name, status: project.status }, redirect_to: project_path(project) }, status: :created else render_model_errors(project) end end private def project_params if params.key?(:project) params.require(:project).permit(:name, :status) else params.permit(:name, :status) end end end ``` ### Client Component ```tsx 'use client'; import type { FormEvent } from 'react'; import { useRailsForm } from 'react-on-rails/useRailsForm'; type ProjectFormData = { name: string; status: 'draft' | 'active'; }; export default function ProjectForm({ action }: { action: string }) { const form = useRailsForm<ProjectFormData>({ name: '', status: 'draft' }); const handleSubmit = (event: FormEvent<HTMLFormElement>) => { event.preventDefault(); void form .post(action, { onSuccess: ({ redirectTo }) => { if (redirectTo) { window.location.assign(redirectTo); } else { form.reset(); } }, }) .catch(() => { form.setError('base', 'Something went wrong. Please try again.'); }); }; return ( <form onSubmit={handleSubmit}> <label> Name <input value={form.data.name} onChange={(event) => form.setData('name', event.target.value)} /> </label> {form.errors.name?.map((message) => ( <p className="error" key={message}> {message} </p> ))} <label> Status <select value={form.data.status} onChange={(event) => form.setData('status', event.target.value as ProjectFormData['status'])} > <option value="draft">Draft</option> <option value="active">Active</option> </select> </label> {form.errors.status?.map((message) => ( <p className="error" key={message}> {message} </p> ))} {form.errors.base?.map((message) => ( <p className="error" key={message}> {message} </p> ))} <button type="submit" disabled={form.processing}> {form.processing ? 'Creating...' : 'Create project'} </button> </form> ); } ``` `base` is not special to Rails; it is just a conventional field name for errors that are not attached to one input. Use any key your app renders consistently. ### Render it from Rails or RSC For an ordinary React island: ```erb <%= react_component("ProjectForm", props: { action: projects_path }) %> ``` For a React Server Components page, keep the form as a Client Component and pass ordinary serializable props from the Server Component: ```tsx // ProjectPage.tsx -- Server Component import ProjectForm from './ProjectForm.client'; export default function ProjectPage({ projectsPath }: { projectsPath: string }) { return <ProjectForm action={projectsPath} />; } ``` The write still goes to `ProjectsController#create`. The Server Component can render the initial page from Rails-provided props or async props, but the mutation belongs to Rails. ## Recipe: TanStack Query mutation When the UI is a live table, command button, optimistic update, or cache-managed island, use TanStack Query for client state and keep the write endpoint in Rails. ```tsx 'use client'; import { useMutation, useQueryClient } from '@tanstack/react-query'; import { createRailsAction, RailsActionRequestError } from 'react-on-rails/railsAction'; type ProjectFormData = { name: string; status: 'draft' | 'active'; }; type ProjectResponse = { project: { id: number; name: string; status: string }; }; type ValidationErrors = Record<string, string[]>; type ErrorResponse = { errors?: unknown; }; const fallbackError: ValidationErrors = { base: ['Something went wrong. Please try again.'] }; const isValidationErrors = (errors: unknown): errors is ValidationErrors => Boolean(errors) && typeof errors === 'object' && !Array.isArray(errors) && Object.keys(errors).length > 0 && Object.values(errors).every( (messages) => Array.isArray(messages) && messages.every((message) => typeof message === 'string'), ); const createProject = createRailsAction<{ project: ProjectFormData }, ProjectResponse>({ path: '/projects', }); export function useCreateProjectMutation(setValidationErrors: (errors: ValidationErrors) => void) { const queryClient = useQueryClient(); return useMutation({ mutationFn: createProject, onSuccess: ({ project }) => { queryClient.setQueryData(['project', String(project.id)], { project }); queryClient.invalidateQueries({ queryKey: ['projects'] }); }, onError: (error) => { if (error instanceof RailsActionRequestError && error.response.status === 422) { const responseBody = error.responseBody; const errors = responseBody && typeof responseBody === 'object' && 'errors' in responseBody ? (responseBody as ErrorResponse).errors : undefined; setValidationErrors(isValidationErrors(errors) ? errors : fallbackError); return; } setValidationErrors(fallbackError); }, }); } ``` This is close to a TanStack Start server-function call at the component boundary, but the server code is still the Rails controller. If your app generates TypeScript response types from Rails, replace the hand-written `ProjectResponse` with [`RailsResponseType<'projects.create'>`](./generated-rails-response-types.md#use-with-typed-rails-actions). ## RSC and cache refresh React on Rails RSC pages usually read data from Rails controller props or [`stream_react_component_with_async_props`](../migrating/rsc-data-fetching.md#data-fetching-in-react-on-rails-pro). After a mutation, choose the refresh mechanism that matches the UI: - Full-page Rails flow: redirect from the controller or return a same-origin `redirect_to` JSON hint and navigate to it. - TanStack Query island: invalidate or update the affected query keys. - RSC route: navigate to a route that Rails renders again, or trigger the app's client router to load the next page state. - Fragment/component cache: expire Rails-owned cache keys from callbacks, jobs, or controller code, then use the matching page, query, or route refresh path above to re-read the data. Do not rely on a Node-renderer Server Action for cache invalidation. For the migration-specific warning, see [Mutations: Rails Controllers, Not Server Actions](../migrating/rsc-data-fetching.md#mutations-rails-controllers-not-server-actions). ## Testing checklist - Controller/request spec: valid write, invalid `422` error JSON, authorization failure, and redirect hint when used. - Client component test: submit state, CSRF-backed request helper behavior, validation-error rendering, and cache invalidation or navigation callback. - System test: only for full user flows where routing, streaming, or hydration is the risk. ## Related docs - [Forms and Mutations with `useRailsForm`](./forms.md) - [Using TanStack Query](./tanstack-query.md) - [Generated Rails response types](./generated-rails-response-types.md) - [RSC data fetching and mutation guidance](../migrating/rsc-data-fetching.md#mutations-rails-controllers-not-server-actions) - [React on Rails Pro and Next.js: RSC Architectures Compared](../../pro/react-server-components/nextjs-comparison.md) - [React on Rails Pro and TanStack Start: Two Ways to Own the Full Stack](../../pro/react-server-components/tanstack-start-comparison.md) - [Next.js Mutating Data](https://nextjs.org/docs/app/getting-started/mutating-data) - [TanStack Start Server Functions](https://tanstack.com/start/latest/docs/framework/react/guide/server-functions) ================================================================================ PAGE: https://reactonrails.com/docs/building-features/react-and-redux SOURCE: docs/oss/building-features/react-and-redux.md ================================================================================ # Legacy Redux Reducer Guidance Redux remains supported for existing React on Rails apps and advanced pages that need one client store shared across multiple React roots. For new apps, prefer local component state for island-specific UI, Rails props plus server-state tools for server-owned data, and reach for Redux only when those smaller patterns do not fit. ## Communication Between Components See [Sharing State Between Components](https://react.dev/learn/sharing-state-between-components). ## Redux Reducers The `helloWorld/reducers/helloWorldReducer.js` example from the hidden legacy Redux generator may be slightly confusing because of its simplicity. For clarity, what follows is a more fleshed-out example of what a reducer might look like: ```javascript import { combineReducers } from 'redux'; import usersReducer from './usersReducer'; import blogPostsReducer from './blogPostsReducer'; import commentsReducer from './commentsReducer'; // ... import { $$initialState as $$usersState } from './usersReducer'; import { $$initialState as $$blogPostsState } from './blogPostsReducer'; import { $$initialState as $$commentsState } from './commentsReducer'; // ... const rootReducer = combineReducers({ $$usersStore: usersReducer, $$blogPostsStore: blogPostsReducer, $$commentsStore: commentsReducer, // ... }); export default rootReducer; export const initialStates = { $$usersState, $$blogPostsState, $$commentsState, // ... }; ``` ================================================================================ PAGE: https://reactonrails.com/docs/building-features/tanstack-query SOURCE: docs/oss/building-features/tanstack-query.md ================================================================================ # Using TanStack Query [TanStack Query](https://tanstack.com/query) (formerly React Query) manages **server state in the browser**: caching, request deduplication, background refetching, retries, and cache invalidation. Rails is excellent at server-side data; TanStack Query gives the React side a disciplined way to consume that data without hand-rolling loading flags, retry logic, and ad-hoc caches. It is the recommended client-side server-state layer for Rails-backed React apps. Rails keeps owning data, routes, auth, sessions, CSRF, validations, mailers, and jobs. TanStack Query does not replace any of that; it consumes the JSON Rails already knows how to produce. ## Support Model - **Client-side TanStack Query works in open-source React on Rails** with no special integration. It is a standard React library; register a component that mounts `QueryClientProvider` and you are done. - **First-paint data seeding** (rendering useful rows in the server HTML, then letting the client reuse them) needs nothing more than React on Rails passing the first screen's data as props. The client adopts it through `useQuery({ initialData })`. This works in OSS and Pro alike. - **Full TanStack Router SSR** (server-rendering the route tree and hydrating it) **requires React on Rails Pro**. See [Using TanStack Router](./tanstack-router.md). TanStack Query composes with that boundary but does not depend on it. This guide mirrors the official [React on Rails + TanStack starter](https://github.com/shakacode/react-on-rails-starter-tanstack) ([live demo](https://starter.reactonrails.com)). Every snippet below is drawn from that app. ## Install ```bash pnpm add @tanstack/react-query ``` ## Rails Stays the Source of Truth A normal Rails controller returns explicit JSON, never raw Active Record: ```ruby # app/controllers/api/projects_controller.rb module Api class ProjectsController < BaseController def index result = ProjectsQuery.from_params(Current.user.projects, params).result render json: { projects: result[:records].map { |project| ProjectSerializer.one(project) }, meta: result[:meta] } end end end ``` Filtering, sorting, pagination, and authorization stay in Rails. The React side never reaches past this boundary. ## One CSRF-Aware Fetch Helper Put the same-origin and CSRF handling in exactly one place so every query and mutation goes through it: ```ts // app/javascript/lib/apiFetch.ts import { getCsrfToken } from './getCsrfToken'; type ApiFetchOptions = RequestInit & { json?: unknown }; export async function apiFetch<T>(path: string, options: ApiFetchOptions = {}): Promise<T> { const headers = new Headers(options.headers); headers.set('Accept', 'application/json'); if (options.json !== undefined) headers.set('Content-Type', 'application/json'); const csrfToken = getCsrfToken(); // reads <meta name="csrf-token"> if (csrfToken) headers.set('X-CSRF-Token', csrfToken); const response = await fetch(path, { ...options, headers, credentials: 'same-origin', body: options.json === undefined ? options.body : JSON.stringify(options.json), }); const body = await response.json(); // the starter also handles non-JSON and throws ApiError on !response.ok return body as T; } ``` `getCsrfToken()` reads the token Rails already renders into the page via `csrf_meta_tags`. Because requests are same-origin with the CSRF header, Rails session auth keeps working. Pair this helper with [generated Rails response types](./generated-rails-response-types.md) to avoid hand-writing `ProjectsResponse` and similar TanStack Query result interfaces. ## Shared QueryClient Defaults Create the `QueryClient` from a single factory so SSR and client use identical defaults: ```ts // app/javascript/lib/queryClient.ts import { QueryClient } from '@tanstack/react-query'; export const createQueryClient = () => new QueryClient({ defaultOptions: { queries: { staleTime: 30_000, retry: 1, refetchOnWindowFocus: false, }, }, }); ``` Mount the provider once, and keep the client stable across renders with `useMemo` (or `useState`). Creating `new QueryClient()` inline on every render throws the cache away on each render. See [Mistake 5 in the RSC context & state guide](../migrating/rsc-context-and-state.md#mistake-5-creating-new-queryclient-on-every-render) for the failure mode. ```tsx const queryClient = useMemo(() => createQueryClient(), []); return ( <QueryClientProvider client={queryClient}> {children} {showDevtools ? <ReactQueryDevtools initialIsOpen={false} /> : null} </QueryClientProvider> ); ``` ## Reading Server State With Stable Query Keys Every server-side input belongs in the query key, so the cache entry is unique per filter/sort/page and refetches when any of them change: ```tsx const projectsQuery = useQuery({ queryKey: ['projects', status, sort, dir, page], queryFn: () => { const params = new URLSearchParams({ sort, dir, page: String(page), per_page: '8' }); if (status) params.set('status', status); return apiFetch<ProjectsResponse>(`${api.projectsPath}?${params}`); }, }); ``` The same query key identifies the same data on the server and the client. That is what lets the server-rendered cache and the client cache line up. ## First Paint Without Spinners The common failure mode is rendering useful HTML on the server, then immediately showing a spinner and refetching everything on the client. Avoid it by seeding the first screen's data from Rails. **Rails renders the first page into props** (only on the route that shows the table, using the same query object as the JSON API so the seed equals a later refetch): ```ruby # app/controllers/dashboard_controller.rb def show @dashboard_props = { api: { projectsPath: api_projects_path }, initialProjects: projects_table_initial_load? ? initial_projects : nil, # ... } end # Seed only on the initial full-page load of the table route. Seeding on other # routes can let a pre-mount mutation leave a stale seed the table later adopts # as fresh (staleTime: 30s). See starter PR #174. def projects_table_initial_load? request.path == projects_path end ``` ```erb <%# app/views/dashboard/show.html.erb %> <%= react_component("DashboardApp", props: @dashboard_props, prerender: !Rails.env.test?) %> ``` **The client adopts the seed as `initialData`** only when its params match the active query key, so the rows render in the initial HTML with no spinner and TanStack Query owns freshness from there: ```tsx const { initialProjects } = useDashboardProps(); const initialData = initialProjects && initialProjects.params.status === status && initialProjects.params.sort === sort && initialProjects.params.dir === dir && initialProjects.params.page === page ? initialProjects.response : undefined; const projectsQuery = useQuery({ queryKey: ['projects', status, sort, dir, page], queryFn: () => apiFetch<ProjectsResponse>(/* ... */), initialData, // first page seeded from Rails; any other filter/sort/page fetches normally }); ``` Because the seed is passed as `initialData` without `initialDataUpdatedAt`, TanStack Query timestamps it at `0`, so the table does one background refetch on mount to confirm freshness — the rows still paint immediately, with no spinner. To treat the seed as fresh for `staleTime` and skip that first refetch, also pass `initialDataUpdatedAt` set to the server's render time. > **`initialData` vs `dehydrate`/`HydrationBoundary`.** TanStack Query also ships a server-prefetch pattern: build a `QueryClient`, `prefetchQuery`, `dehydrate` it into the HTML, and wrap the client tree in `HydrationBoundary`. See the [TanStack Query SSR guide](https://tanstack.com/query/latest/docs/framework/react/guides/ssr). The starter uses the simpler props-to-`initialData` seed because Rails already renders the first page; reach for `dehydrate`/`HydrationBoundary` when you need to seed many queries at once. Note that the `prefetchQuery`/`dehydrate` path needs an awaitable server-render boundary (the Pro [TanStack Router SSR](./tanstack-router.md) path), whereas the props-to-`initialData` seed works in open source. ## Mutations and Cache Invalidation Mutations write through the same `apiFetch` helper, then invalidate or directly update the affected cache entries so the table and metrics refresh once: ```tsx const queryClient = useQueryClient(); const mutation = useMutation({ mutationFn: (values: ProjectFormValues) => apiFetch<ProjectResponse>(api.projectsPath, { method: 'POST', json: { project: values } }), onSuccess: ({ project }) => { queryClient.setQueryData(['project', String(project.id)], { project }); queryClient.invalidateQueries({ queryKey: ['projects'] }); queryClient.invalidateQueries({ queryKey: ['metrics'] }); }, }); ``` If your app generates Rails response types with `react_on_rails:generate_response_types`, use the package's thin Rails action caller so the mutation response stays tied to the Rails-side contract: ```tsx import { useMutation, useQueryClient } from '@tanstack/react-query'; import { createRailsAction } from 'react-on-rails/railsAction'; import type { RailsResponseType } from '../generated/react_on_rails_response_types'; type ProjectFormValues = { name: string; status: string; }; const createProject = createRailsAction<{ project: ProjectFormValues }, RailsResponseType<'projects.create'>>( { path: '/api/projects', }, ); function useCreateProjectMutation() { const queryClient = useQueryClient(); return useMutation({ mutationFn: createProject, onSuccess: ({ project }) => { queryClient.setQueryData(['project', String(project.id)], { project }); queryClient.invalidateQueries({ queryKey: ['projects'] }); queryClient.invalidateQueries({ queryKey: ['metrics'] }); }, }); } ``` `createRailsAction` shares the same-origin, JSON-only, and CSRF assumptions as the starter's `apiFetch` pattern, but returns a standalone function that drops directly into `useMutation`. It does not replace Rails routes, strong parameters, authorization, or runtime response validation. Endpoints should return JSON for 2xx responses unless the caller's response type is `null`; browser redirects reject like network failures, so Rails auth failures should return JSON `401` or `403` responses for mutation endpoints. This is cleaner than threading "reload this section" callbacks through many components: the cache is the single place that knows what is stale. ## TanStack Query and React Server Components With React on Rails Pro's [React Server Components](../../pro/react-server-components/index.md), the two split the work: - **RSC** fetches data for server-rendered, non-interactive pieces. A server component can query a Rails model directly and stream HTML, with no `/api` round-trip and no serializer for that piece. - **TanStack Query** owns the interactive "live app" islands: refetching, mutations, optimistic updates, pagination, infinite scroll, background refresh, and cache invalidation. If you are migrating an existing React Query setup into an RSC app, see [Migrating from React Query / TanStack Query](../migrating/rsc-data-fetching.md#migrating-from-react-query--tanstack-query). ## Why This Fits Rails Apps - **Less frontend state boilerplate.** Server state ("current user," "projects," "messages," search results) belongs in the query cache, not in Redux or a hand-rolled global store. - **Better perceived performance.** The page ships with useful data already present, then stays fresh on the client. You keep the SEO and first-load benefits of server rendering. - **Gradual modernization.** Adopt it one React island or one page at a time. No single-page-app rewrite, no framework swap. ## Working Example The [React on Rails + TanStack starter](https://github.com/shakacode/react-on-rails-starter-tanstack) (Rails 8 + React 19 + React on Rails Pro) implements every pattern above. The relevant files, each marked with a `REFERENCE PATTERN` comment: - Shared fetch + client: `app/javascript/lib/apiFetch.ts`, `app/javascript/lib/getCsrfToken.ts`, `app/javascript/lib/queryClient.ts` - Queries, mutations, provider: `app/javascript/src/Dashboard/ror_components/DashboardApp.tsx` - Rails JSON API: `app/controllers/api/projects_controller.rb` - SSR seed: `app/controllers/dashboard_controller.rb`, `app/views/dashboard/show.html.erb` Try it live at [starter.reactonrails.com](https://starter.reactonrails.com). ## References - [Using TanStack Router](./tanstack-router.md) (the Pro SSR boundary this pairs with) - [Migrating from React Query / TanStack Query](../migrating/rsc-data-fetching.md#migrating-from-react-query--tanstack-query) - [RSC Context & State](../migrating/rsc-context-and-state.md) - [TanStack Query docs](https://tanstack.com/query/latest) - [TanStack Query SSR guide](https://tanstack.com/query/latest/docs/framework/react/guides/ssr) ================================================================================ PAGE: https://reactonrails.com/docs/building-features/generated-rails-response-types SOURCE: docs/oss/building-features/generated-rails-response-types.md ================================================================================ # Generated Rails Response Types React on Rails can generate TypeScript declarations for the JSON response shapes your Rails app exposes to client-side data consumers such as TanStack Query. Rails stays the source of truth for the data and authorization; the generated `.d.ts` file gives the React side importable response types instead of hand-written interfaces that drift. This first supported path is an explicit Rails contract. Register static contracts from `config/initializers/react_on_rails_response_types.rb` or another non-reloadable boot path, then run a rake task to emit TypeScript. Keep helper methods or schema constants next to the serializer, query object, or controller when that keeps ownership clear, but avoid top-level `define_response` or `define_type` calls in reloadable app files because Rails development reloads can run those files again. The task depends on the Rails `:environment` task, so initializers run before declarations are generated. Keep initializer contracts literal or reference non-reloadable constants only; if a contract depends on reloadable app constants, load those constants explicitly before registration or move the registration to an app hook that runs after the constants are available. ## Define Response Contracts Register reusable object types and endpoint response types from Rails: ```ruby # config/initializers/react_on_rails_response_types.rb ReactOnRails::TypeScriptResponseTypes.define_type( "Project", fields: { id: :number, name: :string, status: :string, archived: :boolean } ) ReactOnRails::TypeScriptResponseTypes.define_response( "projects.index", type_name: "ProjectsIndexResponse", fields: { projects: { array: "Project" }, meta: { fields: { page: :number, per_page: :number, total: :number } } } ) ``` Use the same shape in the Rails response: ```ruby # app/controllers/api/projects_controller.rb def index result = ProjectsQuery.from_params(Current.user.projects, params).result render json: { projects: result[:records].map { |project| ProjectSerializer.one(project) }, meta: result[:meta] } end ``` ## Generate the TypeScript File Run: ```bash bundle exec rake react_on_rails:generate_response_types ``` By default, the task writes: ```text app/javascript/types/react_on_rails_response_types.d.ts ``` Override the destination when needed: ```bash REACT_ON_RAILS_RESPONSE_TYPES_OUT=app/frontend/types/rails_response_types.d.ts \ bundle exec rake react_on_rails:generate_response_types ``` The override must resolve inside `Rails.root`; the task rejects absolute paths or traversal outside the app. The generated file contains named interfaces and a response lookup map: ```ts export interface Project { id: number; name: string; status: string; archived: boolean; } export interface ProjectsIndexResponse { projects: Project[]; meta: { page: number; per_page: number; total: number; }; } export interface RailsResponseTypes { "projects.index": ProjectsIndexResponse; } export type RailsResponseTypeName = keyof RailsResponseTypes; export type RailsResponseType<TName extends RailsResponseTypeName> = RailsResponseTypes[TName]; ``` ## Use With TanStack Query Import either the concrete response type or the keyed lookup helper: ```tsx import { useQuery } from '@tanstack/react-query'; import type { RailsResponseType } from '../types/react_on_rails_response_types'; import { apiFetch } from '../lib/apiFetch'; type ProjectsIndexResponse = RailsResponseType<'projects.index'>; const projectsQuery = useQuery({ queryKey: ['projects', status, page], queryFn: () => apiFetch<ProjectsIndexResponse>(`/api/projects?status=${status}&page=${page}`), }); ``` The key string in `RailsResponseTypes` is intentionally independent of the route path. Use a stable controller/action-style name such as `projects.index` so later route changes do not churn client types. ## Use With Typed Rails Actions For mutations, pair the generated response lookup with the CSRF-aware caller from `react-on-rails/railsAction`. The helper does not generate routes or validate payloads at runtime; Rails still owns the route, strong parameters, authorization, and JSON rendering. The generated type only connects the client call site to the response contract you declared in Rails: ```ruby ReactOnRails::TypeScriptResponseTypes.define_response( "projects.create", type_name: "ProjectsCreateResponse", fields: { project: "Project" } ) ``` ```tsx import { useMutation, useQueryClient } from '@tanstack/react-query'; import { createRailsAction, RailsActionRequestError } from 'react-on-rails/railsAction'; import type { RailsResponseType } from '../generated/react_on_rails_response_types'; type ProjectFormValues = { name: string; status: string; }; type CreateProjectVariables = { project: ProjectFormValues; }; type CreateProjectResponse = RailsResponseType<'projects.create'>; const createProject = createRailsAction<CreateProjectVariables, CreateProjectResponse>({ path: '/api/projects', }); function NewProjectButton() { const queryClient = useQueryClient(); const mutation = useMutation({ mutationFn: createProject, onSuccess: ({ project }) => { queryClient.setQueryData(['project', String(project.id)], { project }); queryClient.invalidateQueries({ queryKey: ['projects'] }); }, onError: (error) => { if (error instanceof RailsActionRequestError && error.response.status === 422) { // Map your app's validation-error JSON into form state here. } }, }); return <button onClick={() => mutation.mutate({ project: { name: 'Apollo', status: 'active' } })}>Create</button>; } ``` React on Rails Pro apps that depend on `react-on-rails-pro` can use the mirrored `react-on-rails-pro/railsAction` export. Use `body` when the Rails endpoint expects a wrapper that differs from the variables passed to `mutation.mutate`, and use a `path` function for member actions: ```ts const archiveProject = createRailsAction<{ id: number }, RailsResponseType<'projects.archive'>>({ method: 'PATCH', path: ({ id }) => `/api/projects/${id}/archive`, body: () => null, }); ``` ## Supported Field Specs | Rails contract spec | TypeScript output | | ------------------------------------ | --------------------------------- | | `:string` | `string` | | `:number`, `:integer`, `:float` | `number` | | `:boolean`, `:bool` | `boolean` | | `:date` | `string` | | `:json` | `JsonValue` | | `:any` | `any` | | `:unknown` | `unknown` | | `:null` | `null` | | `"Project"` | `Project` | | `{ raw: "Record<string, string>" }` | `Record<string, string>` | | `{ array: "Project" }` or `[:string]` | `Project[]` or `string[]` | | `{ fields: { id: :number } }` | `{ id: number; }` | | `{ type: :string, optional: true }` | `field?: string` | | `{ type: :string, nullable: true }` | `field: string \| null` | Use symbols for built-in scalar aliases and strings for named TypeScript contract references. String references must match a registered contract `type_name`; unknown identifiers fail generation. Use `{ raw: "..." }` for built-in or third-party JSON-safe TypeScript types that should be emitted verbatim, such as `Record<string, string>`. When an object field itself uses option-like property names (`type`, `array`, `fields`, `raw`, `nullable`, or `optional`), wrap it in `fields:` so the contract is unambiguous: ```ruby fields: { event: { fields: { type: :string, optional: :boolean, payload: :json } } } ``` ## Boundary This task generates TypeScript declarations only. It does not validate payloads at runtime, infer schema from serializers, create routes, or generate route-specific callers. The optional `react-on-rails/railsAction` helper builds on the same `RailsResponseTypes` map by letting the client choose `RailsResponseType<'projects.create'>` for the response generic. ## Related - [Using TanStack Query](./tanstack-query.md) - [React on Rails Pro and TanStack Start](../../pro/react-server-components/tanstack-start-comparison.md) ================================================================================ PAGE: https://reactonrails.com/docs/building-features/styling-with-tailwind SOURCE: docs/oss/building-features/styling-with-tailwind.md ================================================================================ # Styling with Tailwind CSS v4 React on Rails can generate a Tailwind CSS v4 setup for the server-rendered HelloWorld example. The generator uses Tailwind's CSS-first setup, the `@tailwindcss/postcss` plugin, and the same shared bundler template for Webpack and Rspack. ## New Apps For a fresh Rails app, pass `--tailwind` to `create-react-on-rails-app`: ```bash npx create-react-on-rails-app my-app --tailwind cd my-app bin/rails db:prepare bin/dev ``` The CLI forwards `--tailwind` to `rails generate react_on_rails:install`, so the generated `/hello_world` page is server-rendered and styled by Tailwind CSS v4. ## Existing Apps For an existing Rails app, pass the generator flag directly: ```bash bundle exec rails generate react_on_rails:install --tailwind ``` The generator installs these published packages: ```bash pnpm add tailwindcss@^4.3.0 @tailwindcss/postcss@^4.3.0 postcss@^8.5.15 postcss-loader@^8.2.1 npm install tailwindcss@^4.3.0 @tailwindcss/postcss@^4.3.0 postcss@^8.5.15 postcss-loader@^8.2.1 yarn add tailwindcss@^4.3.0 @tailwindcss/postcss@^4.3.0 postcss@^8.5.15 postcss-loader@^8.2.1 ``` It also creates `app/javascript/stylesheets/application.css`: <!-- prettier-ignore --> ```css @import "tailwindcss" source("../.."); ``` The generator also creates `app/javascript/packs/react_on_rails_tailwind.js` to import the Tailwind stylesheet and declares that pack from `app/views/layouts/react_on_rails_default.html.erb`: ```erb <% prepend_javascript_pack_tag "react_on_rails_tailwind" %> <%= stylesheet_pack_tag "react_on_rails_tailwind", media: "all" %> <%= javascript_pack_tag %> ``` The generated `HelloWorld.client.jsx` or `HelloWorld.client.tsx` uses Tailwind utility classes but does not import the global stylesheet. The shared `commonWebpackConfig.js` template inserts `postcss-loader` after `css-loader` and configures `@tailwindcss/postcss`, regardless of whether the project uses Webpack or Rspack. ## Server Rendering Without a Flash of Unstyled Content The generated example keeps three pieces together: 1. `app/views/hello_world/index.html.erb` renders the component with `prerender: true`. 2. `app/javascript/packs/react_on_rails_tailwind.js` imports the Tailwind stylesheet as an app-level pack. 3. `app/views/layouts/react_on_rails_default.html.erb` keeps `<%= stylesheet_pack_tag "react_on_rails_tailwind", media: "all" %>` before `<%= javascript_pack_tag %>`. Tailwind is layout-owned because it is global app styling. The generated components only reference Tailwind class names. Do not move the Tailwind CSS import back into a generated component; pages that use Tailwind classes but do not load that component would then depend on the wrong pack for global styles. In development, CSS can be injected by the dev server instead of extracted as a static link. Use a production build when validating the no-FOUC path. ## Adding Tailwind Manually If you are not rerunning the generator, add the packages yourself: ```bash pnpm add tailwindcss@^4.3.0 @tailwindcss/postcss@^4.3.0 postcss@^8.5.15 postcss-loader@^8.2.1 npm install tailwindcss@^4.3.0 @tailwindcss/postcss@^4.3.0 postcss@^8.5.15 postcss-loader@^8.2.1 yarn add tailwindcss@^4.3.0 @tailwindcss/postcss@^4.3.0 postcss@^8.5.15 postcss-loader@^8.2.1 ``` Then create a CSS entry, import it from an app-level client pack that your layout declares, and add `postcss-loader` after `css-loader` in your shared bundler config: ```javascript { loader: 'postcss-loader', options: { postcssOptions: { plugins: [require('@tailwindcss/postcss')], }, }, } ``` Keep the SSR view prerendered and keep the Tailwind stylesheet pack tag in the layout head so the app-level Tailwind CSS can be emitted before the JavaScript runs when Shakapacker is configured to emit stylesheet links. Tailwind v3 projects should use Tailwind's v3 PostCSS setup instead of this v4 recipe. ================================================================================ PAGE: https://reactonrails.com/docs/building-features/i18n SOURCE: docs/oss/building-features/i18n.md ================================================================================ # Internationalization You can use [Rails internationalization (i18n)](https://guides.rubyonrails.org/i18n.html) in your client code. 1. Set `config.i18n_dir` in `config/initializers/react_on_rails.rb`: ```ruby # Replace the following line by the directory containing your translation.js and default.js files. config.i18n_dir = Rails.root.join("PATH_TO", "YOUR_JS_I18N_FOLDER") ``` If you do not want to use the YAML files from `Rails.root.join("config", "locales")` and installed gems, you can also set `config.i18n_yml_dir`: ```ruby # Replace the following line by the location of your client i18n yml files # Without this option, all YAML files from Rails.root.join("config", "locales") and installed gems are loaded config.i18n_yml_dir = Rails.root.join("PATH_TO", "YOUR_YAML_I18N_FOLDER") ``` 2. Add that directory (or just the generated files `translations.json` and `default.json`) to your `.gitignore`. 3. The locale files must be generated before building (e.g., `npm run build`, `yarn build`, or `pnpm build`). **Option A: Direct Ruby API** (best when you have a custom `bin/dev` script or multiple build steps) Use the `ReactOnRails::Locales.compile` method directly in your `bin/dev` script: ```ruby # In bin/dev require_relative "../config/environment" # Generate locales using direct Ruby API (faster than rake task) ReactOnRails::Locales.compile if ReactOnRails.configuration.i18n_dir.present? ``` Benefits: - Faster execution (no shell spawning overhead) - Better version manager compatibility (mise, asdf, rbenv) - Single place to manage all precompile tasks - Can be combined with other build steps in one script To force regeneration: ```ruby ReactOnRails::Locales.compile(force: true) ``` **Option B: Rake task** (simplest for projects using `precompile_hook` or one-off generation) Use `rake react_on_rails:locale` from the command line: ```bash bundle exec rake react_on_rails:locale # Subsequent calls will skip if already up-to-date ``` To force regeneration: ```bash bundle exec rake react_on_rails:locale force=true ``` The locale generation is idempotent - it will skip generation if files are already up-to-date. This makes it safe to call multiple times without duplicate work. **Recommended: Use Shakapacker's precompile_hook with bin/dev** (React on Rails 16.2.0+, Shakapacker 9.3+) Configure the idempotent task in `config/shakapacker.yml` to run automatically before webpack: ```yaml # config/shakapacker.yml default: &default precompile_hook: 'bundle exec rake react_on_rails:locale' ``` With this configuration, `bin/dev` will: - Run the precompile hook **once** before starting development processes - Set `SHAKAPACKER_SKIP_PRECOMPILE_HOOK=true` to prevent duplicate execution - Pass the environment variable to all spawned processes (Rails, webpack, etc.) > [!TIP] > **For HMR with SSR setups** (two webpack processes), use a script-based hook > instead of a direct command. Script-based hooks can include a self-guard that prevents > duplicate execution regardless of Shakapacker version: > > ```ruby > #!/usr/bin/env ruby > # bin/shakapacker-precompile-hook > exit 0 if ENV["SHAKAPACKER_SKIP_PRECOMPILE_HOOK"] == "true" > system("bundle", "exec", "rake", "react_on_rails:locale", exception: true) > ``` > > Then configure: `precompile_hook: 'bin/shakapacker-precompile-hook'` **Upgrading existing apps** If your app already uses a direct command hook: ```yaml precompile_hook: 'bundle exec rake react_on_rails:locale' ``` switch to `precompile_hook: 'bin/shakapacker-precompile-hook'` and place the self-guard near the top of that script: ```ruby exit 0 if ENV["SHAKAPACKER_SKIP_PRECOMPILE_HOOK"] == "true" ``` This keeps locale generation reliable in SSR + HMR environments across Shakapacker versions. This eliminates the need for sleep hacks and manual coordination in `Procfile.dev`. See the [Process Managers documentation](./process-managers.md#precompile-hook-integration) for details. **Alternative: Manual coordination** For development, you can adjust your startup scripts (`Procfile`s) so that they run `bundle exec rake react_on_rails:locale` before running any Webpack watch process (e.g., `npm run build:development`, `yarn run build:development`, or `pnpm run build:development`). If you are not using the React on Rails test helper, you may need to configure your CI to run `bundle exec rake react_on_rails:locale` before any Webpack process as well. > [!NOTE] > If you try to lint before running tests, and you depend on the test helper to build your locales, linting will fail because the translations won't be built yet. > > The fix is either: > > 1. to run the rake task to build the translations before running the lint command, or > 2. to run the tests first. 4. If your locale files (or one of the gems locale files) contains unsafe YAML, you may need to configure `config.i18n_yml_safe_load_options` if you can't fix such YAML files properly. ```ruby config.i18n_yml_safe_load_options = { permitted_classes: [Symbol] } ``` By default, the locales are generated as JSON, but you can also generate them as JavaScript with [`react-intl`](https://formatjs.io/docs/getting-started/installation/) support: 1. Specify the i18n output format in `config/initializers/react_on_rails.rb`: ```rb config.i18n_output_format = "js" ``` 2. Add `react-intl` & `intl` to your root `package.json`, and remember to run `bundle install` and your package manager's install command (e.g., `npm install`, `yarn install`, or `pnpm install`). The minimum supported versions are: ```js "dependencies": { ... "intl": "^1.2.5", "react-intl": "^2.1.5", ... } ``` 3. In React, you need to initialize `react-intl`, and set its parameters: ```js ... import { addLocaleData } from 'react-intl'; import en from 'react-intl/locale-data/en'; import de from 'react-intl/locale-data/de'; import { translations } from 'path_to/i18n/translations'; import { defaultLocale } from 'path_to/i18n/default'; ... // Initialize all locales for react-intl. addLocaleData([...en, ...de]); ... // Set locale and messages for IntlProvider. const locale = method_to_get_current_locale() || defaultLocale; const messages = translations[locale]; ... return ( <IntlProvider locale={locale} key={locale} messages={messages}> <CommentScreen {...{ actions, data }} /> </IntlProvider> ) ``` In your component: ```js import { defaultMessages } from 'path_to/i18n/default'; ... return ( { formatMessage(defaultMessages.yourLocaleKeyInCamelCase) } ) ``` ## Using i18n with React Server Components The build-time locale system described above generates flat dot-separated keys (e.g., `"product.title"`) and converts Rails `%{variable}` placeholders to ICU `{variable}` syntax. This works well with `react-intl`'s `defineMessages` in Client Components. For apps with both **Server Components** and **Client Components**, `react-intl` provides a unified i18n story: - **Server Components** — use `createIntl` from `react-intl/server` (the official server-safe subpath export, added in react-intl v8.2.0). It provides the same `formatMessage`, `formatNumber`, and `formatDate` APIs without React Context or the `'use client'` directive. Wrap it in `React.cache()` so every Server Component in the same request shares one intl instance. - **Client Components** — use the standard `<IntlProvider>` + `useIntl()` / `<FormattedMessage>` pattern. A Server Component creates the provider boundary and passes `locale` and `messages` down. This keeps a single translation pipeline (`react-intl`) across the entire component tree — Server Components call `intl.formatMessage()` directly, and Client Components consume the same messages through Context. See [Sharing Per-Request Data in Server Components](../../pro/react-server-components/per-request-data.md) _(React on Rails Pro)_ for the complete pattern with `React.cache()`, including a full working example with `RSCRoute` and locale switching. For Context migration patterns, see the [RSC i18n Provider guide](../migrating/rsc-context-and-state.md#i18n-provider). ## Notes - See why using JSON can perform better compared to JS for large amounts of data [https://v8.dev/blog/cost-of-javascript-2019#json](https://v8.dev/blog/cost-of-javascript-2019#json). - See [Support for Rails' i18n pluralization #1000](https://github.com/shakacode/react_on_rails/issues/1000) for a discussion of issues around pluralization. - _Outdated:_ You can refer to [react-webpack-rails-tutorial](https://github.com/shakacode/react-webpack-rails-tutorial) and [PR #340](https://github.com/shakacode/react-webpack-rails-tutorial/pull/340), [committed](https://github.com/shakacode/react-webpack-rails-tutorial/commit/ef369ed9d922aea5116ca7e50208169fd7831389) for a complete example. ================================================================================ PAGE: https://reactonrails.com/docs/building-features/images SOURCE: docs/oss/building-features/images.md ================================================================================ # Configuring Images and Assets with Webpack This page covers the **bundling** side of images: configuring webpack so images imported from your JavaScript/SCSS resolve correctly. For the **performance** side — responsive `srcset`, lazy loading, CLS prevention, LCP preloading, and AVIF/WebP — see [Fast Images in React on Rails](./fast-images.md). A leading slash is necessary on the `name` option for file-loader/url-loader and the `publicPath` option for output. ```javascript const assetLoaderRules = [ { test: /\.(jpe?g|png|gif|ico|woff)$/, use: { loader: 'url-loader', options: { limit: urlFileSizeCutover, // Leading slash is 100% needed name: 'images/[hash].[ext]', }, }, }, { test: /\.(ttf|eot|svg)$/, use: { loader: 'file-loader', options: { // Leading slash is 100% needed name: '/images/[hash].[ext]', }, }, }, ]; ``` A full example can be found at [react_on_rails/spec/dummy/client/app/startup/ImageExample.tsx](../../../react_on_rails/spec/dummy/client/app/startup/ImageExample.tsx) You are free to use images either in image tags or as background images in SCSS files. In current apps, prefer relative imports from files under `app/javascript`, or define your own webpack alias if you want a global asset path. React on Rails does not define an `images` alias by default. If you want one, add it explicitly. For example, if your images live in `app/javascript/images`, then `"images/foobar.jpg"` can point to `app/javascript/images/foobar.jpg` with a custom alias like this: ```javascript resolve: { alias: { images: join(process.cwd(), 'app', 'javascript', 'images'), }, }, ``` ## See also - [Fast Images in React on Rails](./fast-images.md) — responsive `srcset`, lazy loading, CLS prevention, LCP preloading, and modern formats using Rails primitives. - [Font Optimization](./fonts.md) — self-hosting and optimizing web fonts (preload, `font-display`, and a `size-adjust` metric-matched fallback to eliminate layout shift). ================================================================================ PAGE: https://reactonrails.com/docs/building-features/fast-images SOURCE: docs/oss/building-features/fast-images.md ================================================================================ # Fast Images in React on Rails Next.js markets `next/image` as a single component that solves responsive images, lazy loading, modern formats, layout-shift (CLS) prevention, and LCP prioritization. Rails already ships the primitives for every one of those concerns — no hosted image service, no Vercel lock-in. This recipe shows how to combine them in a React on Rails app, both in ERB views and in React components rendered with `react_component`. > **A first-party `<Image>` component is under consideration** for React on > Rails (see [issue #3874](https://github.com/shakacode/react_on_rails/issues/3874)). > Everything on this page works today with stock Rails — the proposed component > would only package these defaults, not replace them. For configuring webpack to _bundle_ images imported from your JavaScript (the asset-loading side), see [Configuring Images and Assets with Webpack](./images.md). This page is about the _markup and serving_ side: what the browser receives. ## The checklist A "fast image" means: 1. **Responsive `srcset` + `sizes`** — the browser downloads a size appropriate for the layout, not a 2400px original on a phone. 2. **Intrinsic `width`/`height` (+ CSS `aspect-ratio`)** — layout space is reserved before the image loads, so there is no CLS. 3. **`loading="lazy"` + `decoding="async"`** on everything below the fold. 4. **`fetchpriority="high"` + `loading="eager"` + a preload** on the LCP/hero image only. 5. **AVIF/WebP with a fallback** via `<picture>`. ## Responsive `srcset` from the asset pipeline For images that ship with your app (Sprockets/Propshaft), commit the size variants and let `image_tag` build the `srcset`. Hash keys are resolved through the asset pipeline just like the main `src`, so fingerprinting works: ```erb <%= image_tag("team-photo-800.jpg", srcset: { "team-photo-400.jpg" => "400w", "team-photo-800.jpg" => "800w", "team-photo-1600.jpg" => "1600w" }, sizes: "(max-width: 600px) 100vw, 600px", width: 800, height: 533, loading: "lazy", decoding: "async", alt: "The team at launch") %> ``` `sizes` tells the browser how wide the image will render at each viewport width; without it the browser assumes `100vw` and over-downloads. ## Responsive `srcset` from Active Storage variants For user-uploaded images, generate the width set with [Active Storage variants](https://guides.rubyonrails.org/active_storage_overview.html#transforming-images). You need the `image_processing` gem (libvips recommended): ```ruby # Gemfile gem "image_processing", "~> 1.2" ``` ```erb <%# app/views/products/show.html.erb %> <% widths = [400, 800, 1600] %> <% variants = widths.index_with { |w| @product.photo.variant(resize_to_limit: [w, nil]) } %> <%= image_tag url_for(variants[800].processed), srcset: widths.map { |w| "#{url_for(variants[w].processed)} #{w}w" }.join(", "), sizes: "(max-width: 600px) 100vw, 600px", width: 800, height: (800 * @product.photo_aspect_ratio).round, loading: "lazy", decoding: "async", alt: @product.name %> ``` :::warning Request-time variant generation is a performance footgun `variant(...)` does **not** resize anything until the variant is first served. With the default redirect mode, the first visitor to hit each width pays the transformation cost (or times out on large images), and a cold cache after a storage migration pays it again for every image on the page — multiplied by every width in your `srcset`. Treat request-time generation as a fallback, not the plan: - **Pre-generate variants** when the upload happens, in a background job, by calling `.processed` (which transforms and uploads the variant if missing): ```ruby class Product < ApplicationRecord has_one_attached :photo do |attachable| attachable.variant :w400, resize_to_limit: [400, nil], preprocessed: true attachable.variant :w800, resize_to_limit: [800, nil], preprocessed: true attachable.variant :w1600, resize_to_limit: [1600, nil], preprocessed: true end end ``` Named variants with `preprocessed: true` (Rails 7.1+) enqueue transformation right after upload instead of on first request. Reference them as `@product.photo.variant(:w800)`. - **Run `analyze` on attach** (Active Storage does this by default via a job) so `metadata[:width]`/`metadata[:height]` are available for CLS attributes without downloading the blob. Until that job has run, `attachment.analyzed?` is `false` and the dimensions are missing — guard for it and fall back to a default aspect ratio, as the snippets below do. - **Serve through a CDN.** Put a CDN in front of your storage service (or use [proxy mode](https://guides.rubyonrails.org/active_storage_overview.html#putting-a-cdn-in-front-of-active-storage) plus a CDN in front of the app) so each generated variant is transformed once and cached at the edge — not re-served by your Rails dynos. ::: To get intrinsic dimensions for the `width`/`height` attributes, read the analyzed metadata instead of hardcoding: ```ruby # app/models/product.rb # Height ÷ width (≈0.667 for a 3:2 landscape photo) — the multiplier that # turns a display width into the matching height attribute. Note that CSS # `aspect-ratio` is the inverse: width / height. def photo_aspect_ratio meta = photo.metadata return 2.0 / 3 unless meta["width"].to_i.positive? && meta["height"].to_i.positive? meta["height"].to_f / meta["width"] end ``` Guard on **both** dimensions: until the analyzer job has run (`photo.analyzed?` is `false`), either value can be missing, and a zero height would emit `height="0"` and an `aspect-ratio` of 0. ## Passing image props to a React component When the `<img>` lives inside a React component, keep the URL math in Rails — where the asset pipeline and Active Storage live — and hand React a plain props hash via `react_component`. Compute the props in a helper: ```ruby # app/helpers/images_helper.rb module ImagesHelper # Must match the named variants on the model (:w400, :w800, :w1600), # pre-generated at upload time with preprocessed: true — see the # variant-generation warning above. RESPONSIVE_WIDTHS = [400, 800, 1600].freeze # Returns {src:, srcSet:, sizes:, width:, height:} for an Active Storage attachment. def responsive_image_props(attachment, sizes: "100vw", display_width: 800) # Snap to the closest generated width so an unlisted value can't produce # a nil variant lookup. display_width = RESPONSIVE_WIDTHS.min_by { |w| (w - display_width).abs } meta = attachment.metadata aspect_ratio = if meta["width"].to_i.positive? && meta["height"].to_i.positive? meta["height"].to_f / meta["width"] else 2.0 / 3 # analysis hasn't run yet — see the warning above end srcset = RESPONSIVE_WIDTHS.map { |w| "#{url_for(attachment.variant(:"w#{w}"))} #{w}w" } { src: url_for(attachment.variant(:"w#{display_width}")), srcSet: srcset.join(", "), sizes: sizes, width: display_width, height: (display_width * aspect_ratio).round } end end ``` If you cannot define named variants (or are on Rails < 7.1), the request-time form — `attachment.variant(resize_to_limit: [w, nil]).processed` — is a drop-in replacement for `attachment.variant(:"w#{w}")`. But it transforms on first request, which is exactly the footgun the warning above describes: acceptable for a low-traffic admin page, not for anything user-facing. ```erb <%# app/views/products/show.html.erb %> <%= react_component("ProductHero", props: { name: @product.name, image: responsive_image_props(@product.photo, sizes: "(max-width: 600px) 100vw, 600px") }) %> ``` The React side is just an `<img>` spreading those attributes — it renders identically on the server and client, so there is nothing to hydrate incorrectly: ```jsx // app/javascript/src/ProductHero/ror_components/ProductHero.jsx export default function ProductHero({ name, image }) { return ( <figure> <img src={image.src} srcSet={image.srcSet} sizes={image.sizes} width={image.width} height={image.height} loading="lazy" decoding="async" alt={name} /> <figcaption>{name}</figcaption> </figure> ); } ``` For asset-pipeline images the same pattern applies — build the hash with `image_path`/`image_url` instead of `url_for(variant)`. ## CLS prevention: intrinsic size + `aspect-ratio` Always emit `width` and `height` attributes (the intrinsic pixel dimensions, not the display size). Browsers use them to reserve the correct box before the bytes arrive, which is what keeps CLS at zero. Then let CSS control the actual display size: ```css img { max-width: 100%; height: auto; /* keep the reserved aspect ratio when width is constrained */ } ``` If you size an image with CSS alone (e.g. a `background-size: cover`-style crop), reserve the space explicitly: ```css .card-thumb { aspect-ratio: 3 / 2; width: 100%; object-fit: cover; } ``` ## Defaults for non-hero images Every image that can start below the fold should opt out of competing with critical resources: - `loading="lazy"` — the browser defers the download until the image nears the viewport. - `decoding="async"` — decode off the main thread instead of blocking paint. These are plain attributes in both ERB (`loading: "lazy", decoding: "async"`) and JSX (`loading="lazy" decoding="async"`). They are the right default for everything **except** the LCP image — lazy-loading the hero is one of the most common LCP regressions. ## The LCP/hero image: prioritize and preload For the one image that is your [Largest Contentful Paint](https://web.dev/articles/optimize-lcp) element, invert the defaults: ```erb <%= image_tag("hero-1600.jpg", srcset: { "hero-800.jpg" => "800w", "hero-1600.jpg" => "1600w" }, sizes: "100vw", width: 1600, height: 900, loading: "eager", fetchpriority: "high", alt: "Hand-thrown ceramic mugs lined up on a workbench") %> ``` - `fetchpriority="high"` tells the browser to fight for bandwidth for this request. - `loading="eager"` (the default, but explicit beats accidental `lazy`). - Give the hero real `alt` text — it is usually meaningful content. Reserve `alt: ""` for purely decorative images. Additionally, preload it from your **layout's `<head>`**, so the fetch starts before the browser has parsed down to the `<img>` (or, for client-rendered components, before React renders at all): ```erb <%# app/views/layouts/application.html.erb %> <head> <%= yield :preloads %> <%# ... %> </head> ``` If the hero has a single source, [`preload_link_tag`](https://api.rubyonrails.org/classes/ActionView/Helpers/AssetTagHelper.html#method-i-preload_link_tag) is the right tool: ```erb <%# app/views/home/index.html.erb %> <% content_for :preloads do %> <%= preload_link_tag image_path("hero-1600.jpg"), as: "image", fetchpriority: "high" %> <% end %> ``` For a **responsive** hero (the `srcset` case above), the preload must carry `imagesrcset`/`imagesizes` so the browser preloads the same candidate the `<img>` will pick. Use a plain `<link>` here — **not** `preload_link_tag`: besides the tag, `preload_link_tag` also sends an HTTP `Link: rel=preload` header built only from the fixed `href` (it does not include `imagesrcset`/`imagesizes`), so browsers that honor the header would fetch the full-size image on every viewport, duplicating the download the responsive preload was supposed to avoid. ```erb <%# app/views/home/index.html.erb %> <% content_for :preloads do %> <link rel="preload" as="image" fetchpriority="high" imagesrcset="<%= image_path('hero-800.jpg') %> 800w, <%= image_path('hero-1600.jpg') %> 1600w" imagesizes="100vw" /> <% end %> ``` This is deliberately a **layout-level** concern: the preload belongs in the document `<head>` your layout owns, declared by the page that knows its hero. You do not need (and React on Rails does not currently provide) a head-injection helper for it. Preload at most one or two images per page — preloading more steals bandwidth from the things you actually wanted to prioritize. ## Modern formats: AVIF/WebP with fallback AVIF and WebP are typically 30–50% smaller than JPEG at equivalent quality. Active Storage variants can transcode formats too (libvips must be built with AVIF support for `:avif`). Define them as named, pre-generated variants, like the width variants earlier: ```ruby # app/models/product.rb — add format variants next to the width variants attachable.variant :w800_avif, resize_to_limit: [800, nil], format: :avif, preprocessed: true attachable.variant :w800_webp, resize_to_limit: [800, nil], format: :webp, preprocessed: true ``` ```erb <picture> <source srcset="<%= url_for(@product.photo.variant(:w800_avif)) %>" type="image/avif" /> <source srcset="<%= url_for(@product.photo.variant(:w800_webp)) %>" type="image/webp" /> <%= image_tag url_for(@product.photo.variant(:w800)), width: 800, height: 533, loading: "lazy", decoding: "async", alt: @product.name %> </picture> ``` The browser picks the first `<source>` it supports and falls back to the `<img>` otherwise — older browsers never download the modern formats. On Rails 7.1+ you can also use the [`picture_tag`](https://api.rubyonrails.org/classes/ActionView/Helpers/AssetTagHelper.html#method-i-picture_tag) helper. In JSX the same markup is `<picture>` + `<source>` elements with `srcSet`/`type` props. For brevity this example is **fixed-width** — one 800px candidate per format. In production, make each `<source>` responsive exactly like [the plain `<img>` above](#responsive-srcset-from-active-storage-variants): define the format variants at every width (`:w400_avif`, `:w800_avif`, `:w1600_avif`, …) and give each `<source>` the multi-width `srcset` plus the same `sizes` value. Otherwise the browser always downloads the one listed candidate and you lose the responsive savings. Note the multiplication — two formats × three widths is six variants per image — which is why these are defined with `preprocessed: true` rather than transformed at request time. ## Putting it together | Concern | Non-hero image | LCP/hero image | | ---------------- | ------------------------- | --------------------------------------- | | `srcset`/`sizes` | yes | yes | | `width`/`height` | always | always | | `loading` | `lazy` | `eager` | | `decoding` | `async` | (default) | | `fetchpriority` | (default) | `high` | | Preload | no | preload `<link>` in the layout `<head>` | | Formats | AVIF/WebP via `<picture>` | AVIF/WebP via `<picture>` | To verify the result, check LCP and CLS in Chrome DevTools (Performance panel) or with the [web-vitals](https://github.com/GoogleChrome/web-vitals) library: the hero should be discovered in the preload scanner's first pass, and CLS from images should be ~0. ## See also - [Configuring Images and Assets with Webpack](./images.md) — bundling images imported from JavaScript/SCSS. - [Font Optimization](./fonts.md) — the companion recipe for the other classic CLS source. - [web.dev: Optimize LCP](https://web.dev/articles/optimize-lcp) and [web.dev: CLS](https://web.dev/articles/cls). ================================================================================ PAGE: https://reactonrails.com/docs/building-features/fonts SOURCE: docs/oss/building-features/fonts.md ================================================================================ # Font Optimization (a `next/font/local` analog) Web fonts are a classic source of two performance problems: 1. **Render-blocking external requests** when you load fonts from a third-party host (e.g. the Google Fonts CDN) — an extra origin connection plus a privacy/GDPR consideration. 2. **Cumulative Layout Shift (CLS)** when the browser re-renders text after the web font replaces the fallback font, because the two fonts have different metrics. `next/font` solves both by self-hosting the font, preloading it, setting `font-display`, and generating a metric-matched fallback face. React on Rails ships a small first-party helper that does the same thing on Rails — no third-party dependency, no build plugin. You self-host (commit + fingerprint) a `.woff2` through your asset pipeline and the helper emits the correct `<head>` markup. > This is the OSS v1: the **`next/font/local`** path (you commit the font file). > Build-time Google-Fonts fetching (`next/font/google`) and automatic per-font > metric derivation are tracked as follow-ups. See also: [Configuring Images and Assets with Webpack](./images.md). ## The helper `ReactOnRails::FontHelper#react_on_rails_font_face` is mixed into the standard view helpers. It returns markup for the document `<head>`: 1. `<link rel="preload" as="font" type="font/woff2" crossorigin>` so the browser fetches the font in parallel with first paint; 2. an `@font-face` rule with `font-display: swap`; 3. an optional **metric-matched fallback** `@font-face` (`size-adjust` plus `ascent-override` / `descent-override` / `line-gap-override`) so the system fallback occupies the same space as the web font. It uses the same `<head>`-injection convention as [`react_component_hash`](./react-helmet.md): wrap the return value in `content_for :head`, and yield it from your layout's `<head>`. ```erb <%# app/views/layouts/application.html.erb %> <head> <%= yield :head %> <%# ... %> </head> ``` ```erb <%# your view %> <% content_for :head do %> <%= react_on_rails_font_face( family: "Inter", src: asset_path("inter-latin-400-normal.woff2"), weight: 400, fallback: { family: "Arial", size_adjust: "107.12%", ascent_override: "90.44%", descent_override: "22.52%", line_gap_override: "0.0%" } ) %> <% end %> ``` Then set your CSS font stack to the web font, then the generated fallback face, then a generic family: ```css body { font-family: 'Inter', 'Inter Fallback', Arial, sans-serif; } ``` ### Options | Option | Default | Notes | | ---------------- | ---------- | -------------------------------------------------------------- | | `family:` | (required) | CSS `font-family` name for the web font. | | `src:` | (required) | URL to the `.woff2`. Use `asset_path(...)` for fingerprinting. | | `weight:` | `400` | A range like `"100 900"` is valid for variable fonts. | | `style:` | `"normal"` | `font-style`. | | `display:` | `"swap"` | `font-display`. `swap` shows fallback text immediately. | | `unicode_range:` | `nil` | Emit a `unicode-range` to subset the face (see below). | | `preload:` | `true` | Emit the preload `<link>`. | | `fallback:` | `nil` | Metric-matched fallback face (see below). | > **Trusted input only.** Every argument is interpolated verbatim into the CSS/HTML this helper emits into `<head>`, and the result is marked HTML-safe. Pass developer-controlled values (font names, asset paths) — never end-user input. Values containing `<`, `>`, `"`, or a newline raise `ArgumentError`. ## Self-hosting through the asset pipeline Commit the `.woff2` file into your asset pipeline so it is fingerprinted and served with a far-future cache header. With Sprockets/Propshaft, place it under `app/assets/fonts/` (or `vendor/assets`) and reference it with `asset_path("inter-latin-400-normal.woff2")`. With Shakapacker, import the font from your pack and pass the resolved URL. Either way the font is served from your own origin — there is no runtime request to a third-party font host. ## `font-display: swap` `swap` tells the browser to render text immediately with the fallback font and swap in the web font when it arrives. This avoids invisible text (the "FOIT" flash of invisible text) at the cost of a "FOUT" flash of unstyled text — which the fallback-metrics technique below makes nearly invisible. ## The `size-adjust` fallback (eliminating CLS) `font-display: swap` shows fallback text first, then swaps in the web font. If the fallback and the web font have different metrics, text **reflows** on the swap — that reflow is CLS. The fix (the same one `next/font` uses) is a second `@font-face` that takes a **local** system font and adjusts its metrics with `size-adjust`, `ascent-override`, `descent-override`, and `line-gap-override` so it occupies exactly the space the real web font will. The helper also emits `font-weight` and `font-style` on this fallback face matching the primary face, so the browser applies it to the same elements (without this, the size-adjust protection silently fails for non-`400` weights or non-`normal` styles — just as `next/font` generates a weight-matched fallback). See [web.dev: font best practices](https://web.dev/articles/font-best-practices) and [Chrome: improved font fallbacks](https://developer.chrome.com/blog/font-fallbacks/). ### Deriving the numbers (worked example: Inter over Arial) These values must be derived from the actual font metrics — do not guess. The example below uses metrics from [`@capsizecss/metrics`](https://github.com/seek-oss/capsize) `v4.0.0` (the same data source `next/font` and `fontaine` use). All values share `unitsPerEm: 2048`. | Metric | Inter (web font) | Arial (fallback) | | ------------ | ---------------- | ---------------- | | `xWidthAvg` | 978 | 913 | | `ascent` | 1984 | 1854 | | `descent` | -494 | -434 | | `lineGap` | 0 | 67 | | `unitsPerEm` | 2048 | 2048 | `size-adjust` scales the fallback so its average character width matches the web font: ``` size-adjust = (inter.xWidthAvg / inter.unitsPerEm) / (arial.xWidthAvg / arial.unitsPerEm) = (978 / 2048) / (913 / 2048) = 1.0712 -> 107.12% ``` The overrides describe the **web font's** vertical metrics, scaled by `size-adjust` so the adjusted fallback's line box matches: ``` ascent-override = (inter.ascent / inter.unitsPerEm) / size-adjust = 0.9044 -> 90.44% descent-override = (|inter.descent| / inter.unitsPerEm) / size-adjust = 0.2252 -> 22.52% line-gap-override = (inter.lineGap / inter.unitsPerEm) / size-adjust = 0.0 -> 0.0% ``` These match the values `next/font/local` generates for Inter with an Arial fallback. For other fonts, plug the font's own metrics into the same formulas, or read the generated numbers from your `next/font` setup if you are migrating. ## Subsetting guidance Ship only the glyphs you need. A full font can be hundreds of KB; a `latin` subset is typically 15–30 KB. Sensible default: **start with the `latin` subset** for English-language sites, then add `latin-ext` if you need accented European characters. Declare the covered range with `unicode_range:` so the browser can skip the download when a page has no matching glyphs: ```erb <%= react_on_rails_font_face( family: "Inter", src: asset_path("inter-latin-400-normal.woff2"), unicode_range: "U+0000-00FF, U+0131, U+0152-0153, U+2000-206F" ) %> ``` Most font distributions (e.g. [Fontsource](https://fontsource.org)) ship per-subset `.woff2` files plus the matching `unicode-range` for each — commit the subset you need and copy its range. ## Core Web Vitals (CLS) note Self-hosting + preload removes the render-blocking third-party request; the `size-adjust` fallback removes the layout shift on swap. Together they target two Core Web Vitals at once (LCP/render time and CLS). To verify, record CLS in Chrome DevTools (Performance panel) or the [web-vitals](https://github.com/GoogleChrome/web-vitals) library before and after adding the fallback face: the font-swap layout shift should drop to ~0. ## Runnable example A working example lives in the dummy app: - View: `react_on_rails/spec/dummy/app/views/pages/font_optimization_example.html.erb` - Vendored font: `react_on_rails/spec/dummy/public/fonts/inter-latin-400-normal.woff2` (Inter, OFL-1.1 — see `public/fonts/LICENSE-Inter.txt`) - Unit spec: `react_on_rails/spec/react_on_rails/font_helper_spec.rb` - Request spec: `react_on_rails/spec/dummy/spec/requests/font_optimization_spec.rb` ## Known follow-ups (not in v1) - **Build-time Google-Fonts fetching** (the `next/font/google` path): fetch and vendor a Google font at build time instead of committing the file. - **Automatic per-font metric derivation**: compute the `size-adjust` and override values programmatically from the font binary instead of hardcoding documented numbers. - **Pro streaming-shell coverage**: ensure the preload `<link>` lands in the streaming shell before the first body flush (see `react_on_rails_pro/lib/react_on_rails_pro/concerns/stream.rb`). v1 covers the non-streaming `react_component_hash` head-injection path only. ================================================================================ PAGE: https://reactonrails.com/docs/building-features/rails-engine-integration SOURCE: docs/oss/building-features/rails-engine-integration.md ================================================================================ # Integrating React on Rails with Rails Engines ## In your engine - At the top of `config/initializers/react_on_rails.rb` ```ruby ActiveSupport.on_load(:action_view) do include ReactOnRailsHelper end ``` - In your `<engine_name>.gemspec`: ```ruby s.add_dependency 'react_on_rails', '~> 6' ``` - In your `lib/<engine_name>.rb` (the entry point for your engine) ```ruby require "react_on_rails" ``` ## In the project including your engine Place `gem 'react_on_rails', '~> 6'` before the gem pointing at your engine in your gemfile. Requiring `react_on_rails` and including the helper will get rid of any issues where `ReactOnRails` or `react_component` is undefined. As far as solving the assets issue, `lib/tasks/assets.rake` in `react_on_rails` would somehow have to know that `react_on_rails` was included in an engine, and decide the path accordingly. This might be impossible, especially in the case of multiple engines using `react_on_rails` in a single application. Another solution would be to detach this rake task from the `rails assets:precompile` task. This can be done by adding `REACT_ON_RAILS_PRECOMPILE=false` to your environment. If you do so, then React assets will have to be bundled separately from `rails assets:precompile`. ## Github Issues - [Integration with an engine #342](https://github.com/shakacode/react_on_rails/issues/342) - [Feature: target destination option for the install generator #459](https://github.com/shakacode/react_on_rails/issues/459) - [Integration with Rails 5 Engines #562](https://github.com/shakacode/react_on_rails/issues/562) - [Run inside a Rails engine? #257](https://github.com/shakacode/react_on_rails/issues/257) ================================================================================ PAGE: https://reactonrails.com/docs/building-features/web-components SOURCE: docs/oss/building-features/web-components.md ================================================================================ # Web Components React on Rails supports native [Web Components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components) (Custom Elements) alongside React components. You can use web components in server-rendered React components, client-only React components, and directly in ERB templates. ## How It Works Web components are browser-native custom HTML elements. React on Rails treats them like any other HTML tag — the custom element tags pass through server rendering as-is, then upgrade to interactive components once JavaScript loads on the client. ``` Server renders: <my-counter value="5"></my-counter> ← plain HTML tag Browser receives: empty custom element (no shadow content) JS loads: connectedCallback() fires → builds the UI ``` > [!NOTE] > Web component tags appear in the server-rendered HTML, but their **internal content** (shadow DOM, dynamically created children) is only created client-side after JavaScript loads and the element class is registered with `customElements.define()`. ## Defining a Web Component Create a TypeScript (or JavaScript) file that defines your custom element class: ```typescript // client/app/web-components/app-greeting.ts export class AppGreeting extends HTMLElement { static observedAttributes = ['name', 'variant']; constructor() { super(); this.attachShadow({ mode: 'open' }); } connectedCallback() { this.render(); } attributeChangedCallback(_name: string, _oldValue: string | null, _newValue: string | null) { this.render(); } private render() { const name = this.getAttribute('name') || 'World'; this.shadowRoot!.innerHTML = ` <style> :host { display: block; } .greeting { padding: 16px; border-radius: 8px; border: 1px solid #e5e7eb; } </style> <div class="greeting"> <p class="name"></p> <slot></slot> </div> `; this.shadowRoot!.querySelector('.name')!.textContent = `Hello, ${name}!`; } } if (typeof customElements !== 'undefined' && !customElements.get('app-greeting')) { customElements.define('app-greeting', AppGreeting); } ``` The `typeof customElements !== 'undefined'` guard prevents errors during server-side rendering, where browser APIs are not available. ## Registering Web Components Create a central registration file that imports all your web component definitions: ```typescript // client/app/web-components/register.ts export {}; if (typeof window !== 'undefined') { void import('./app-greeting'); void import('./app-counter'); void import('./app-toggle'); } ``` Import this file from your client bundle entry point: ```typescript // client/app/packs/client-bundle.ts import ReactOnRails from 'react-on-rails/client'; import '../web-components/register'; // ... rest of your registrations ``` The `typeof window` guard ensures dynamic imports only run in the browser. On the server, only the custom element tags are rendered — no JavaScript class registration occurs. ## Using in React Components ### Server-Rendered Components (`prerender: true`) Web component tags work in server-rendered React components. The tags are included in the initial HTML response with their attributes: If you use TypeScript, declare your custom element tags so JSX type-checking accepts them: ```typescript // client/app/types/web-components.d.ts import 'react'; declare module 'react' { namespace JSX { interface IntrinsicElements { 'app-greeting': React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement> & { name?: string; variant?: string; }; 'app-counter': React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement> & { value?: string; label?: string; }; } } } ``` Then use the tags in your component: ```tsx // client/app/startup/Dashboard.tsx const Dashboard: React.FC<{ userName: string }> = ({ userName }) => ( <div> <h1>Welcome</h1> <app-greeting name={userName} variant="primary"> <span>Your dashboard is ready.</span> </app-greeting> <app-counter value="0" label="Tasks" /> </div> ); export default Dashboard; ``` ```erb <%# app/views/pages/dashboard.html.erb %> <%= react_component("Dashboard", props: { userName: @user.name }, prerender: true) %> ``` The server output will contain: ```html <app-greeting name="Alice" variant="primary"> <span>Your dashboard is ready.</span> </app-greeting> <app-counter value="0" label="Tasks"></app-counter> ``` These are plain HTML tags until JavaScript loads and the custom element classes are registered. Slotted content (children inside the tags) is part of the server HTML and is visible immediately. ### Client-Only Components (`prerender: false`) Client-rendered React components work identically. Use refs and event listeners to sync web component state with React: ```tsx // client/app/startup/InteractiveDemo.tsx import React, { useEffect, useRef, useState } from 'react'; const InteractiveDemo: React.FC = () => { const counterRef = useRef<HTMLElement>(null); const [count, setCount] = useState(0); useEffect(() => { const el = counterRef.current; if (!el) return; const handler = (e: Event) => { setCount((e as CustomEvent).detail.value); }; el.addEventListener('counter-change', handler); return () => el.removeEventListener('counter-change', handler); }, []); return ( <div> <app-counter ref={counterRef} value={String(count)} label="Items" /> <p>React sees count: {count}</p> </div> ); }; export default InteractiveDemo; ``` Web components are already registered by the `client-bundle.ts` import shown above — there is no need to import `register.ts` again in individual components. > [!TIP] > React 19 sets properties directly on custom elements when a property of that name exists on the element instance. For attributes that must be strings (like `value`), explicitly convert with `String()`. ## Using Directly in ERB Web components work in ERB templates without any React wrapper: ```erb <%# app/views/pages/status.html.erb %> <app-greeting name="<%= @user.name %>" variant="success"> <span>Welcome back!</span> </app-greeting> <app-counter value="<%= @initial_count %>" label="Page Views"></app-counter> ``` This requires the client bundle (which imports `register.ts`) to be loaded on the page. ## Shadow DOM Modes Web components support three encapsulation levels: | Mode | External CSS Affects It? | External JS Can Access Children? | `element.shadowRoot` | | ------------------------- | ------------------------ | --------------------------------------------- | -------------------- | | **Light DOM** (no shadow) | Yes | Yes, via `querySelector` | `null` | | **Open Shadow** | No | Yes, via `element.shadowRoot.querySelector()` | Accessible | | **Closed Shadow** | No | No | `null` | ### Light DOM (No Shadow) Children are part of the regular DOM. External CSS styles them, and external JavaScript can query them directly. ```typescript export class WcLightDom extends HTMLElement { connectedCallback() { this.innerHTML = `<p class="message">I'm in the light DOM</p>`; } } ``` ### Open Shadow DOM Styles are encapsulated. External JavaScript can access the shadow tree via `element.shadowRoot`: ```typescript export class WcOpenShadow extends HTMLElement { constructor() { super(); this.attachShadow({ mode: 'open' }); } connectedCallback() { this.shadowRoot!.innerHTML = ` <style>.message { color: blue; }</style> <p class="message">I'm in open shadow DOM</p> `; } } ``` ### Closed Shadow DOM Maximum encapsulation. External code cannot access the shadow tree. Expose behavior through public methods: ```typescript export class WcClosedShadow extends HTMLElement { private _shadow: ShadowRoot; constructor() { super(); this._shadow = this.attachShadow({ mode: 'closed' }); } connectedCallback() { this._shadow.innerHTML = ` <style>.count { font-size: 24px; }</style> <span class="count">0</span> `; } getCount(): number { return parseInt(this._shadow.querySelector('.count')!.textContent || '0', 10); } reset(): void { this._shadow.querySelector('.count')!.textContent = '0'; } } ``` ## Event Communication Web components communicate with React through [Custom Events](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent). Two key options control event propagation: - **`bubbles: true`** — event propagates up the DOM tree - **`composed: true`** — event crosses shadow DOM boundaries ```typescript // Inside a shadow DOM web component: this.dispatchEvent( new CustomEvent('status-change', { detail: { status: 'active' }, bubbles: true, composed: true, // required to reach React listeners outside shadow DOM }), ); ``` In React, listen with `addEventListener` on a ref: ```tsx useEffect(() => { const el = ref.current; const handler = (e: Event) => { const { status } = (e as CustomEvent).detail; setStatus(status); }; el?.addEventListener('status-change', handler); return () => el?.removeEventListener('status-change', handler); }, []); ``` > [!WARNING] > Events with `composed: false` are **trapped inside shadow DOM** and will not reach React event listeners. Always use `composed: true` when you need React to observe events dispatched from inside a shadow root. ## CSS Behavior ### Style Encapsulation Shadow DOM prevents external CSS from affecting internal elements. This means global stylesheets and Tailwind classes do not reach inside shadow DOM components. ### CSS Custom Properties Pierce Shadow DOM CSS custom properties (variables) are the exception — they inherit through all shadow boundaries: ```css /* In your global CSS or ERB layout */ :root { --brand-color: #3b82f6; --brand-bg: #eff6ff; } ``` ```typescript // Inside a shadow DOM web component: this.shadowRoot!.innerHTML = ` <style> .card { background: var(--brand-color, #000); } </style> <div class="card">Themed by CSS variables</div> `; ``` ### `::part()` for Selective External Styling Open shadow DOM components can expose elements for external styling with the `part` attribute: ```typescript // Web component template: this.shadowRoot!.innerHTML = ` <h2 part="title">Component Title</h2> <p part="body">Component body text</p> `; ``` ```css /* External CSS can style exposed parts: */ my-component::part(title) { color: navy; font-size: 24px; } ``` ## Slots Slots project light DOM content into shadow DOM layout positions. Slotted content lives in the light DOM — it is visible in the server-rendered HTML and can be queried with `querySelector` from outside: ```tsx <wc-card> <span slot="header">This is SSR'd and visible immediately</span> <p>Default slot content, also in the server HTML</p> </wc-card> ``` ```typescript // Web component definition: this.shadowRoot!.innerHTML = ` <div class="card"> <div class="header"><slot name="header"></slot></div> <div class="body"><slot></slot></div> </div> `; ``` ## Server Rendering Behavior Both React on Rails server rendering and client rendering output web component tags the same way — as plain HTML elements with attributes. The key points: 1. **Tags are in the initial HTML.** The server response includes `<app-greeting name="Alice"></app-greeting>`. 2. **Shadow DOM content is not in the server HTML.** The `connectedCallback` that builds the shadow tree only runs client-side. 3. **Slotted content IS in the server HTML.** Children inside the tags (including named slots) are part of the light DOM and render immediately. 4. **Attributes are preserved.** String attributes set in JSX appear as HTML attributes in the server output. 5. **Object/function props are dropped during SSR.** React's server renderer only serializes primitive attribute values. Non-primitive props are set client-side as properties after hydration. > [!NOTE] > The browser standard for server-rendering shadow DOM content is [Declarative Shadow DOM](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM#declarative_shadow_dom) (`<template shadowrootmode="open">`). React does not support emitting or hydrating Declarative Shadow DOM. This is a React limitation, not a React on Rails limitation. Web component shadow content is always created client-side. ## Avoiding Flash of Unstyled Content (FOUC) Since shadow DOM content only appears after JavaScript loads, users may see a brief flash of empty or unstyled custom elements. Mitigation strategies: **Hide undefined elements with CSS:** ```css :not(:defined) { visibility: hidden; } ``` The `:defined` pseudo-class matches elements that have been registered with `customElements.define()`. Unregistered elements are hidden until their class loads. **Use slotted content for critical text:** Place important visible content in slots rather than inside shadow DOM. Slotted content is in the server HTML and visible before JavaScript loads: ```tsx <app-card> <h2 slot="title">Product Name</h2> <p>This text is visible immediately from SSR.</p> </app-card> ``` ## Testing with Playwright Playwright's built-in selector engine pierces **open** shadow DOM automatically when using `page.locator()`. This is a Playwright feature — native `document.querySelector()` does not cross shadow boundaries. For **closed** shadow DOM, Playwright cannot pierce it either. Expose public methods on your element class and use `page.evaluate()`: ```javascript // Open shadow — Playwright's selector engine pierces open shadow roots: await expect(page.locator('.shadow-inner-class')).toBeVisible(); // Closed shadow — use public API methods via page.evaluate(): await page.evaluate(() => { const el = document.querySelector('my-closed-component'); el.reset(); }); const count = await page.evaluate(() => { return document.querySelector('my-closed-component').getCount(); }); expect(count).toBe(0); ``` ================================================================================ PAGE: https://reactonrails.com/docs/building-features/turbolinks SOURCE: docs/oss/building-features/turbolinks.md ================================================================================ # Turbolinks and Turbo Support ## React on Rails Updated to support Turbo, August 2024 - See [PR 1620](https://github.com/shakacode/react_on_rails/pull/1620). - See [PR 1374](https://github.com/shakacode/react_on_rails/pull/1374). - Ability to use with [Turbo (`@hotwired/turbo`)](https://turbo.hotwired.dev/), as Turbolinks becomes obsolete. ## Using Turbo Turbo is the modern replacement for Turbolinks, providing fast navigation through your Rails app without full page reloads. ### Basic Setup **1. Install Turbo** Add the Turbo Rails gem and JavaScript package: ```bash # Gemfile gem "turbo-rails" # JavaScript yarn add @hotwired/turbo-rails # or: npm install @hotwired/turbo-rails # or: pnpm add @hotwired/turbo-rails ``` **2. Enable Turbo in React on Rails** Import Turbo and configure React on Rails to work with it: ```js // app/javascript/packs/application.js import '@hotwired/turbo-rails'; ReactOnRails.setOptions({ turbo: true, // Enable Turbo support (not auto-detected) }); ``` **3. Use Turbo Frames** (works out of the box) Turbo Frames work with React components without any special configuration: ```erb <%# app/views/items/index.html.erb %> <%= turbo_frame_tag 'item-list' do %> <%= react_component("ItemList", props: @items) %> <% end %> <%# Clicking a link that responds with another turbo_frame_tag will update just that frame %> ``` ### Turbo with Auto-Bundling When using React on Rails' [auto-bundling feature](../core-concepts/auto-bundling-file-system-based-automated-bundle-generation.md) (`auto_load_bundle: true`) with Turbo, there's a specific ordering requirement to address: **The Challenge:** 1. **Turbo's requirement**: Turbo must be loaded in the `<head>` to avoid script re-evaluation warnings during page navigation 2. **Auto-registration's behavior**: `react_component` with `auto_load_bundle: true` calls `append_javascript_pack_tag` during body rendering 3. **Shakapacker's requirement**: All `append_javascript_pack_tag` calls must occur before the final `javascript_pack_tag` This creates a conflict: the `<head>` (with `javascript_pack_tag`) renders before the `<body>` (where `react_component` triggers auto-appends). **The Solution: `content_for :body_content` Pattern** Use `content_for` to render your body content first, capturing auto-appends before the head renders: ```erb <%# Step 1: Capture body content FIRST - this triggers all auto-appends %> <% content_for :body_content do %> <%= react_component "NavigationBarApp", prerender: true %> <div class="container"> <%= yield %> </div> <%= react_component "Footer", prerender: true %> <%= redux_store_hydration_data %> <% end %> <!DOCTYPE html> <html> <head> <%= csrf_meta_tags %> <%= csp_meta_tag %> <%# Optional: Explicitly load non-React packs (Stimulus, shared stores, etc.) %> <%# React component bundles are already auto-appended by react_component calls above %> <%# Do NOT manually append component bundles here - they're already included %> <%= append_stylesheet_pack_tag('stimulus-bundle') %> <%= append_javascript_pack_tag('stimulus-bundle') %> <%= append_javascript_pack_tag('stores-registration') %> <%# Step 2: Pack tags now include all component bundles from auto-appends above %> <%= stylesheet_pack_tag(media: 'all') %> <%= javascript_pack_tag(defer: true) %> </head> <body> <%# Step 3: Output the captured body content %> <%= yield :body_content %> </body> </html> ``` **Why This Works:** 1. Rails processes the `content_for` block first, which executes all `react_component` calls 2. Each `react_component` with `auto_load_bundle: true` triggers `append_javascript_pack_tag` 3. When the `<head>` renders, `javascript_pack_tag` includes all accumulated appends 4. Turbo loads early in `<head>`, satisfying its requirement 5. Component bundles load in the correct order **Note:** While defining body content before `<!DOCTYPE html>` may look unusual, Rails processes `content_for` blocks during template evaluation, not document output order. The final HTML is correctly structured. **Common Pitfalls:** - ❌ Don't place `javascript_pack_tag` before `content_for` blocks that call `react_component` - ❌ Don't manually append component bundles if using `auto_load_bundle: true` - ✅ Do let `react_component` handle bundle appending automatically **Additional Resources:** - [Shakapacker Preventing FOUC guide](https://github.com/shakacode/shakapacker/blob/main/docs/preventing_fouc.md#the-content_for-body_content-pattern) - [Turbo Handbook - Working with Script Elements](https://turbo.hotwired.dev/handbook/building#working-with-script-elements) ### Turbo Streams (Requires React on Rails Pro) > **⚡️ React on Rails Pro Feature** > > Turbo Streams rely on Pro's early hydration behavior, which hydrates components as soon as they are inserted into the DOM. This is a [React on Rails Pro](../../pro/react-on-rails-pro.md) licensed feature that is always on for Pro users. **Why Turbo Streams Need Special Handling:** Unlike Turbo Frames, Turbo Streams don't dispatch the normal `turbo:render` events that React on Rails uses to hydrate components. Instead, they directly manipulate the DOM. React on Rails Pro hydrates components immediately when they are inserted into the DOM, without waiting for page load events, so Turbo Stream updates work out of the box. **Example: Create a Turbo Stream Response** ```erb <%# app/views/items/index.html.erb - Initial page with frame %> <%= turbo_frame_tag 'item-list' do %> <%= button_to "Load Items", items_path, method: :post %> <% end %> ``` ```erb <%# app/views/items/create.turbo_stream.erb - Turbo Stream response %> <%= turbo_stream.update 'item-list' do %> <%= react_component("ItemList", props: @items) %> <% end %> ``` **What Happens:** 1. User clicks "Load Items" button 2. Rails responds with `create.turbo_stream.erb` 3. Turbo Stream updates the `item-list` frame with the new React component 4. React on Rails Pro hydrates the inserted component immediately **Learn More:** - See [Streaming Server Rendering](./streaming-server-rendering.md) for another Pro use case - Working example in codebase: `react_on_rails/spec/dummy/app/views/pages/turbo_stream_send_hello_world.turbo_stream.erb` - Contact [justin@shakacode.com](mailto:justin@shakacode.com) for React on Rails Pro licensing ## Legacy Turbolinks Support _The following documentation covers older Turbolinks versions (2.x and 5.x). While still supported by React on Rails, we recommend migrating to Turbo when possible._ React on Rails currently supports: - **Turbolinks 5.x** (e.g., 5.0.0+) - Auto-detected - **Turbolinks 2.x** (Classic) - Auto-detected - See [Turbolinks on Github](https://github.com/rails/turbolinks) You may include Turbolinks either via npm/yarn/pnpm (recommended) or via the gem. ### Why Turbolinks? As you switch between Rails HTML controller requests, you will only load the HTML and you will not reload JavaScript and stylesheets. This definitely can make an app perform better, even if the JavaScript and stylesheets are cached by the browser, as they will still require parsing. ### Requirements for Using Turbolinks 1. Either **avoid using [React Router](https://reactrouter.com/)** or be prepared to deal with any conflicts between it and Turbolinks. 2. **Use one JS and one CSS file** throughout your app. Otherwise, you will have to figure out how best to handle multiple JS and CSS files throughout the app given Turbolinks. ### Why Not Turbolinks 1. [React Router](https://reactrouter.com/) handles the back and forward buttons, as does Turbolinks. You _might_ be able to make this work. _Please share your findings._ 1. You want to do code splitting to minimize the JavaScript loaded. ### Installation #### Install Checklist 1. Include turbolinks via your package manager as shown in the [react-webpack-rails-tutorial](https://github.com/shakacode/react-webpack-rails-tutorial/blob/8a6c8aa2e3b7ae5b08b0a9744fb3a63a2fe0f002/client/webpack.client.base.config.js#L22) or include the gem "turbolinks". 1. Included the proper "track" tags when you include the javascript and stylesheet: **For Turbolinks 5.x:** ```erb <%= stylesheet_link_tag 'application', media: 'all', 'data-turbolinks-track' => 'reload' %> <%= javascript_include_tag 'application', 'data-turbolinks-track' => 'reload' %> ``` **For Turbolinks 2.x (Classic):** ```erb <%= stylesheet_link_tag 'application', media: 'all', 'data-turbolinks-track' => true %> <%= javascript_include_tag 'application', 'data-turbolinks-track' => true %> ``` **Note:** If you're using modern Turbo (recommended), use `'data-turbo-track' => 'reload'` instead of `'data-turbolinks-track'`. See the "Using Turbo" section at the top of this document. 1. Add turbolinks to your `application.js` file: ```javascript //= require turbolinks ``` #### Turbolinks from NPM See the [instructions on installing from NPM](https://github.com/turbolinks/turbolinks#installation-using-npm). ```js import Turbolinks from 'turbolinks'; Turbolinks.start(); ``` ##### Async script loading Async script loading can be done like this (starting with Shakapacker 8.2): ```erb <%= javascript_include_tag 'application', async: Rails.env.production? %> ``` If you use `document.addEventListener("turbolinks:load", function() {...});` somewhere in your code, you will notice that Turbolinks 5 does not fire `turbolinks:load` on initial page load. A quick workaround for React on Rails earlier than 15 is to use `defer` instead of `async`: ```erb <%= javascript_include_tag 'application', defer: Rails.env.production? %> ``` More information on this issue can be found here: https://github.com/turbolinks/turbolinks/issues/28 When loading your scripts asynchronously your components may not be registered correctly. Call `ReactOnRails.reactOnRailsPageLoaded()` to re-initialize like so: ```js document.addEventListener('turbolinks:load', function () { ReactOnRails.reactOnRailsPageLoaded(); }); ``` React on Rails 15 fixes both issues, so if you still have the listener it can be removed (and should be as `reactOnRailsPageLoaded()` is now async). > [!WARNING] > **Async Scripts with Turbolinks Require Pro** > > If you use async script loading with Turbolinks, you need Pro's early hydration behavior to prevent race conditions. This is a React on Rails Pro licensed feature. > > Without Pro's early hydration, async scripts may not be ready when Turbolinks fires navigation events, causing components to fail hydration. > > **Alternatives:** > > - Use `defer` instead of `async` (waits for full page load before hydration) > - Upgrade to modern Turbo (recommended) > - Use React on Rails Pro (early hydration is automatic for Pro users) ### Turbolinks 5 Specific Information React on Rails will automatically detect which version of Turbolinks you are using (2.x or 5.x) and use the correct event handlers. For more information on Turbolinks 5: [https://github.com/turbolinks/turbolinks](https://github.com/turbolinks/turbolinks) ### Technical Details and Troubleshooting #### CSRF and MIME Type Handling - **CSRF tokens**: Turbolinks 5 changes the head element by JavaScript (not only body) on page changes with the correct csrf meta tag. Be thorough checking CSRF tokens, especially when multiple windows are opened, as the CSRF helper in ReactOnRails needs to work with Turbolinks5. - **MIME type handling**: Turbolinks 5 sends requests with `Accept: text/html` only (not `Accept: */*`), which makes Rails behave differently compared to normal requests. For more details on the special handling of `*/*` you can read [Mime Type Resolution in Rails](http://blog.bigbinary.com/2010/11/23/mime-type-resolution-in-rails.html). - **Multiple Webpack bundles**: If you're using multiple Webpack bundles, make sure that there are no name conflicts between JS objects or Redux store paths. #### Debugging Turbolinks Events To turn on tracing of Turbolinks events, put this in your registration file, where you register your components. ```js ReactOnRails.setOptions({ traceTurbolinks: true, turbo: true, }); ``` Rather than setting the value to true, you could set it to TRACE_TURBOLINKS, and then you could place this in your `webpack.client.base.config.js`: Define this const at the top of the file: ```js const devBuild = process.env.NODE_ENV !== 'production'; ``` Add this DefinePlugin option: ```js plugins: [ new webpack.DefinePlugin({ TRACE_TURBOLINKS: devBuild, }), ``` At Webpack compile time, the value of devBuild is inserted into your file. Once you do that, you'll see messages prefixed with **TURBO:** like this in the browser console: Turbolinks Classic: ```text TURBO: WITH TURBOLINKS: document page:before-unload and page:change handlers installed. (program) TURBO: reactOnRailsPageLoaded ``` Turbolinks 5: ```text TURBO: WITH TURBOLINKS 5: document turbolinks:before-render and turbolinks:render handlers installed. (program) TURBO: reactOnRailsPageLoaded ``` We've noticed that Turbolinks doesn't work if you use the RubyGem versions of jQuery and jQuery ujs. Therefore, we recommend using the JS packages instead. See the [tutorial app](https://github.com/shakacode/react-webpack-rails-tutorial) for how to accomplish this.  ================================================================================ PAGE: https://reactonrails.com/docs/building-features/dev-server-and-testing SOURCE: docs/oss/building-features/dev-server-and-testing.md ================================================================================ # HMR, Dev Server Modes, and Testing > Run `bin/dev --help` for all development server modes and options. `bin/dev` starts your Rails server alongside webpack-dev-server with Hot Module Replacement (HMR) by default. HMR is great for development — changes appear instantly in the browser — but it affects how tests find compiled assets. This guide covers how each `bin/dev` mode interacts with your test framework and how to configure things so tests work reliably. Your test setup depends on which testing framework you use. Pick your path: - [**Capybara / Rails System Tests**](#capybara--rails-system-tests-rspec-and-minitest) — Standard Rails integration tests. Capybara boots its own server; assets must be on disk. - [**Playwright / Cypress E2E**](#playwright--cypress-e2e) — External browser tools that connect to your running dev server. Any `bin/dev` mode works. ## How `bin/dev` Modes Affect Tests `bin/dev` defaults to HMR mode (Hot Module Replacement). HMR serves JavaScript from webpack-dev-server's memory at `http://localhost:3035` — great for development, but those assets don't exist as files on disk. | `bin/dev` Mode | Assets on disk? | Capybara tests work? | Playwright/Cypress work? | | ------------------------ | ---------------------------------------------- | ----------------------------------------------- | ------------------------ | | `bin/dev` (HMR, default) | No — in memory only | Only with TestHelper (auto-compiles separately) | Yes | | `bin/dev static` | Yes — written to `public/webpack/development/` | Yes — auto-detected and reused | Yes | | `bin/dev test-watch` | Yes — written to `public/webpack/test/` | Yes | Yes | **The key takeaway:** With [TestHelper properly configured](#test-helper-configuration), all `bin/dev` modes work with all test types. TestHelper auto-compiles test assets when needed, regardless of whether HMR or static mode is running. ## Generated Bundle Files and Cache Cleanup Most `bin/dev` commands are intentionally conservative: they start, watch, rebuild, or stop the processes for the selected mode, but they do not wipe every generated bundle directory or bundler cache first. That keeps normal restarts fast, but stale files can survive branch switches, package-version changes, and Shakapacker configuration changes. Use `bin/dev clean` when you want the cleanup step too. The exact output directories come from `config/shakapacker.yml`. The paths below use the defaults shown in this guide. | Command | Generated bundles it uses or writes | What it clears automatically | | ------------------------------------ | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `bin/dev` (HMR, default) | Browser bundles are served from webpack-dev-server memory, not from `public/webpack/development/`. | No generated bundle directories or build caches. Existing disk outputs are left alone. | | `bin/dev static` | Writes development bundles to the development `public_output_path`, usually `public/webpack/development/`. | No output directories or build caches. Watch rebuilds update known outputs but do not remove stale files from old branches. | | `bin/dev test-watch` | Writes test bundles to the test `public_output_path`, usually `public/webpack/test/`. | No output directories or build caches. Watch rebuilds update known outputs but do not remove stale files from old branches. | | TestHelper / `build_test_command` | Writes test bundles when assets are stale. | No output directories or build caches unless your custom `build_test_command` deletes them. | | `bin/dev prod` / `production-assets` | Runs `rails assets:precompile` with production bundler optimizations. | No `public/assets`, `public/webpack/*`, or build-cache cleanup unless your Rails tasks do it. | | `bin/dev kill` | Does not build bundles. | Stops known dev processes and removes process/socket files such as Overmind sockets and `tmp/pids/server.pid`; it does not delete bundles, `tmp/cache`, `node_modules/.cache`, or renderer bundle caches. | | `bin/dev clean` | Does not build bundles. | Runs the `kill` cleanup, reads `config/shakapacker.yml` or `SHAKAPACKER_CONFIG`, removes configured Shakapacker output/cache paths, and clears common build caches. Unsafe paths outside the app root are skipped. | If a branch switch or package update leaves confusing asset errors, stop watchers and clear generated outputs first, then reinstall packages if the lockfile changed before rebuilding: ```bash bin/dev clean # If package versions changed, reinstall with your package manager. pnpm install # or: yarn install # or: npm install ``` `bin/dev clean` derives Shakapacker public and private output paths from every top-level section in `shakapacker.yml` (including custom sections such as `staging`, plus the standard `default`, `development`, `test`, and `production` sections), then clears those directories plus configured `cache_path` directories, `public/assets`, `tmp/cache`, `node_modules/.cache`, `.node-renderer-bundles`, and `tmp/node-renderer-bundles-test-*`. For React Server Components or the React on Rails Pro node renderer, `bin/dev clean` handles the default generated renderer cache paths above and app-local paths configured with `RENDERER_SERVER_BUNDLE_CACHE_PATH`. If that environment variable points outside the app root, the safety guard skips it; clear that external path manually. The [RSC testing setup](./testing-configuration.md#rsc-and-node-renderer-system-tests) explains why each parallel test worker should use its own renderer bundle cache. ## Capybara / Rails System Tests (RSpec and Minitest) Capybara boots its **own** Puma server for each test run. That server reads `manifest.json` to find asset paths, so assets must exist as files on disk. HMR manifests contain `http://localhost:3035/...` URLs that Capybara's Puma can't serve — but this doesn't matter if TestHelper is configured, because it compiles separate test assets. ### Making It Just Work Configure TestHelper once, and Capybara tests work with any `bin/dev` mode — or no dev server at all: **1. Set the build command:** ```ruby # config/initializers/react_on_rails.rb ReactOnRails.configure do |config| config.build_test_command = "RAILS_ENV=test bin/shakapacker" end ``` **2. Wire TestHelper into your test framework:** ```ruby # spec/rails_helper.rb (RSpec) require "react_on_rails/test_helper" RSpec.configure do |config| ReactOnRails::TestHelper.configure_rspec_to_compile_assets(config) end ``` ```ruby # test/test_helper.rb (Minitest) require "react_on_rails/test_helper" class ActiveSupport::TestCase setup do ReactOnRails::TestHelper.ensure_assets_compiled end end ``` **3. Use separate output paths** (the default). These are the key settings — see your full `shakapacker.yml` for the complete config: ```yaml # config/shakapacker.yml (key differences only) development: public_output_path: webpack/development test: compile: false # TestHelper handles compilation public_output_path: webpack/test # Must differ from development ``` That's it. Now: ```bash bin/dev # Terminal 1 — develop with HMR as usual bundle exec rspec # Terminal 2 — TestHelper auto-compiles test assets ``` ### Speeding Up Test Runs TestHelper compiles once per test run when assets are stale. To skip this wait: ```bash bin/dev static # Assets written to disk, auto-reused by tests (fastest) # OR bin/dev test-watch # Keeps test assets fresh in background alongside HMR ``` When `bin/dev static` is running, `DevAssetsDetector` automatically reuses those assets — no compilation step needed at all. ## Playwright / Cypress E2E Playwright and Cypress launch a real browser that connects to your running Rails server via HTTP. The browser fetches JavaScript from wherever the HTML points — including `http://localhost:3035` when HMR is active. **Any `bin/dev` mode works.** Just start your server and run tests: ```bash bin/dev # Terminal 1 (HMR or static — both work) pnpm test:e2e # Terminal 2 ``` ### Playwright Configuration ```js // playwright.config.js export default defineConfig({ use: { baseURL: 'http://localhost:3000/', }, webServer: { command: 'bin/dev static', url: 'http://localhost:3000', reuseExistingServer: !process.env.CI, timeout: 120 * 1000, }, }); ``` The `webServer` block starts `bin/dev static` if no server is already running. Locally it reuses your running dev server; in CI it always starts fresh. ## CI (No Dev Server) In CI there's no dev server. TestHelper compiles assets automatically: ```bash bundle exec rspec # TestHelper runs build_test_command if assets are stale ``` Or precompile explicitly for faster parallel runs: ```bash RAILS_ENV=test bin/shakapacker bundle exec rspec ``` ## Test Helper Configuration Full configuration reference — see [Testing Configuration](./testing-configuration.md) for `build_test_command` vs `compile: true` and all options. **RSpec** — add to `spec/rails_helper.rb`: ```ruby require "react_on_rails/test_helper" RSpec.configure do |config| # Compiles assets before first test that needs them. # Triggers for :js, :server_rendering, and :controller specs by default. ReactOnRails::TestHelper.configure_rspec_to_compile_assets(config) # Optional: also trigger for request/feature specs that need webpack assets # ReactOnRails::TestHelper.configure_rspec_to_compile_assets(config, :requires_webpack_assets) # config.define_derived_metadata(file_path: %r{spec/(features|requests)}) do |metadata| # metadata[:requires_webpack_assets] = true # end end ``` **Minitest** — add to `test/test_helper.rb`: ```ruby require "react_on_rails/test_helper" class ActiveSupport::TestCase setup do ReactOnRails::TestHelper.ensure_assets_compiled end end ``` **Config** — add to `config/initializers/react_on_rails.rb`: ```ruby ReactOnRails.configure do |config| # Command to compile test assets. Runs automatically when assets are stale. config.build_test_command = "RAILS_ENV=test bin/shakapacker" # Files to check when determining if assets are stale (default: manifest.json) # config.webpack_generated_files = %w(manifest.json) end ``` ## Advanced: External Server Mode If you want Capybara to connect to your running dev server instead of starting its own, you get the benefit of HMR working during tests — the browser goes through the full dev stack. The tradeoff: `bin/dev` must be running for tests to pass. Use an environment variable to toggle this so CI still boots its own server: ```ruby # spec/rails_helper.rb if ENV["CAPYBARA_EXTERNAL_SERVER"] # Local development: connect to your running `bin/dev` server. # Start `bin/dev` first, then run tests with: # CAPYBARA_EXTERNAL_SERVER=1 bundle exec rspec Capybara.app_host = "http://localhost:3000" Capybara.run_server = false else # CI and default: Capybara boots its own Puma server. # TestHelper compiles test assets automatically. end ``` **Local usage** — start your dev server, then run tests with the env var: ```bash bin/dev # Terminal 1 — HMR running CAPYBARA_EXTERNAL_SERVER=1 bundle exec rspec # Terminal 2 — tests use your dev server ``` **CI** — no env var needed, tests run as normal: ```bash bundle exec rspec # Capybara boots its own server, TestHelper compiles assets ``` ## Verifying Your Setup ```bash bundle exec rake react_on_rails:doctor # Check for misconfigurations FIX=true bundle exec rake react_on_rails:doctor # Auto-fix common issues ``` The doctor detects: - Missing or conflicting test asset compilation settings - Shared output paths with HMR enabled - Minitest system tests without `ensure_assets_compiled` - External server mode (`Capybara.run_server = false`) ## Troubleshooting Each error includes a link to this documentation and suggests `bin/dev --help`. ### `React on Rails: build_test_command is not configured.` ```text React on Rails: build_test_command is not configured. You are using the React on Rails test helper (configure_rspec_to_compile_assets or ensure_assets_compiled), but config.build_test_command is not set. ``` **Fix:** Add `config.build_test_command = "RAILS_ENV=test bin/shakapacker"` to `config/initializers/react_on_rails.rb`, or switch to `compile: true` in `shakapacker.yml` and remove the TestHelper calls. ### `React on Rails: Stale test assets detected` ```text React on Rails: Stale test assets detected: public/webpack/test/manifest.json Compiling with: `RAILS_ENV=test bin/shakapacker` ``` This is informational — compilation starts automatically. To skip the wait, run `bin/dev static` or `bin/dev test-watch` in another terminal. ### `React on Rails: Development assets use HMR` ```text React on Rails: Development assets use HMR (manifest contains http:// URLs). HMR assets cannot be reused for tests — they exist in webpack-dev-server memory, not on disk. ``` **Fix:** Use `bin/dev static` instead, or run `bin/dev test-watch` alongside HMR. If you have TestHelper configured, this is just informational — it will compile test assets separately. ### `React on Rails: Error building test assets!` ```text React on Rails: Error building test assets! The build_test_command failed. This means test assets could not be compiled. ``` **Fix:** Check the build output above this message for the actual build error. Quick workarounds: `bin/dev static`, `bin/dev test-watch`, or rerun your configured `build_test_command` manually. ### Blank pages in Capybara system tests (no Ruby error) This happens when HMR manifest URLs end up in the test asset path. The manifest resolves but points to `http://localhost:3035/...`, which Capybara's Puma can't serve. The browser gets 404s for JS/CSS, resulting in blank pages. **Fix:** Ensure test and development use separate `public_output_path` values in `shakapacker.yml`. Run `bundle exec rake react_on_rails:doctor` to detect this. ### `Shakapacker::Manifest::MissingEntryError` ```text Shakapacker::Manifest::MissingEntryError: Shakapacker can't find application.js in /path/to/public/webpack/test/manifest.json ``` No assets have been compiled at all. **Fix:** Wire up TestHelper (see [Test Helper Configuration](#test-helper-configuration)), or compile manually: `RAILS_ENV=test bin/shakapacker`. ## How It Works Under the Hood When tests run, TestHelper checks if assets are stale. If they are, it tries `DevAssetsDetector` first: 1. Is `public/webpack/development/manifest.json` present? 2. Does it contain relative paths (not `http://` HMR URLs)? 3. Is it newer than all source files? If all three pass, Shakapacker's test config is temporarily overridden to read from the development output (zero compilation). If not, `build_test_command` runs. ## Related Documentation - [Testing Configuration](./testing-configuration.md) — `build_test_command` vs `compile: true` in detail - [HMR and Hot Reloading](./hmr-and-hot-reloading-with-the-webpack-dev-server.md) — Setting up HMR - [Process Managers](./process-managers.md) — Foreman/overmind for `bin/dev` ================================================================================ PAGE: https://reactonrails.com/docs/building-features/testing-configuration SOURCE: docs/oss/building-features/testing-configuration.md ================================================================================ # Testing Configuration This guide explains how to configure React on Rails for optimal testing with RSpec, Minitest, or other test frameworks. ## Quick Start For most applications, the recommended approach is React on Rails TestHelper with `build_test_command`: ```ruby # config/initializers/react_on_rails.rb ReactOnRails.configure do |config| config.build_test_command = "RAILS_ENV=test bin/shakapacker" # NODE_ENV is derived from RAILS_ENV by Shakapacker end ``` Leave `NODE_ENV` unset for Shakapacker asset builds: Shakapacker automatically sets `NODE_ENV` to match `RAILS_ENV`, so `RAILS_ENV=test` is sufficient. Set `NODE_ENV=test` explicitly only when running a JavaScript test runner such as Jest directly. Then wire TestHelper into your test framework. If your app uses both RSpec and Minitest, wire both files. **RSpec** — add to `spec/rails_helper.rb`: ```ruby require "react_on_rails/test_helper" RSpec.configure do |config| ReactOnRails::TestHelper.configure_rspec_to_compile_assets(config) end ``` **Minitest** — add to `test/test_helper.rb`: ```ruby require "react_on_rails/test_helper" class ActiveSupport::TestCase setup do ReactOnRails::TestHelper.ensure_assets_compiled end end ``` ## RSC and Node Renderer System Tests React Server Components add one more moving part to the standard test setup: system tests need compiled client, server, and RSC bundles, and the Rails test process must be able to reach a node-renderer process that uses the test bundle cache. Use this recipe for Capybara, system, and end-to-end tests that exercise `stream_react_component`, `RSCRoute`, or the `rsc_payload_route`. This recipe uses the React on Rails TestHelper with `build_test_command`: Rails checks whether generated bundles are stale, runs your test build command when needed, and fails fast if compilation fails. The Step 3 renderer-lifecycle helper is **RSpec-focused** because it uses `before(:suite)` and `after(:suite)` hooks; for Minitest, see [Minitest Equivalent](#minitest-equivalent) for a parallel adaptation that reuses the same safety points from a `test/test_helper.rb` harness plus `Minitest.after_run`. See [Two Approaches to Test Asset Compilation](#two-approaches-to-test-asset-compilation) for the underlying compilation tradeoffs. ### 1. Set Renderer ENV Before Rails Boots The Pro initializer reads renderer settings while Rails boots. Set test renderer ENV values before requiring `config/environment` in `spec/rails_helper.rb`. Generated Pro apps read `REACT_RENDERER_URL`; some older or custom initializers read `RENDERER_URL`, so the example sets both names. Keep the worker ID normalization in a small support file so the Rails boot preamble and renderer lifecycle code cannot drift apart. ```ruby # spec/support/rsc_test_worker.rb module RscTestWorker ID = ENV.fetch("TEST_ENV_NUMBER", "") .gsub(/[^0-9]/, "") .then { |worker_id| worker_id.empty? ? "0" : worker_id } end ``` ```ruby # spec/rails_helper.rb ENV["RAILS_ENV"] ||= "test" require_relative "support/rsc_test_worker" ENV["RENDERER_PORT"] ||= (3900 + RscTestWorker::ID.to_i).to_s renderer_url = "http://127.0.0.1:#{ENV["RENDERER_PORT"]}" ENV["REACT_RENDERER_URL"] ||= renderer_url # used by config.renderer_url = ENV["REACT_RENDERER_URL"] ENV["RENDERER_URL"] ||= renderer_url # used by some older/custom initializers ENV["RENDERER_SERVER_BUNDLE_CACHE_PATH"] ||= File.expand_path("../tmp/node-renderer-bundles-test-#{RscTestWorker::ID}", __dir__) require_relative "../config/environment" ``` `TEST_ENV_NUMBER` is set by the `parallel_tests` gem. It uses `""` for the first worker, then `"2"`, `"3"`, and so on (skipping `"1"`), so the example uses ports 3900, 3902, 3903, and leaves a harmless gap at 3901. That unused 3901 port is expected; keeping the normalized worker ID stable matters more than filling every port number. Before adopting the 3900 range, check for existing listeners with `lsof -i :3900-3910`; if another service already uses these ports, set `RENDERER_PORT` before this snippet or change the base port in the example. If you use a different parallelization tool, update `spec/support/rsc_test_worker.rb` to normalize that tool's worker ID to a stable, path-safe `RscTestWorker::ID` so every worker gets a unique port, cache path, and renderer log. If you run tests in parallel, each worker needs its own `RENDERER_PORT` and `RENDERER_SERVER_BUNDLE_CACHE_PATH`. Sharing a renderer cache across parallel workers can produce stale-bundle and missing-bundle failures that look like flaky RSC timeouts. ### 2. Compile Test Bundles Up Front Configure the React on Rails test helper to compile assets before the first RSC example. Your `build_test_command` must build all bundles needed by the test environment, not only the browser bundle. ```ruby # config/initializers/react_on_rails.rb ReactOnRails.configure do |config| config.build_test_command = "NODE_ENV=test RAILS_ENV=test bin/shakapacker" end ``` The Quick Start command only sets `RAILS_ENV` for the minimal browser-bundle case. The RSC recipe also sets `NODE_ENV=test` so JavaScript build scripts, webpack/shakapacker config, and the node-renderer all see the test environment consistently. If your app's build does not branch on `NODE_ENV`, the simpler Quick Start command is still enough for non-RSC tests. > **Warning:** Three copy-paste hazards in the snippet below — read these before adapting it. > > - **The metatag list replaces TestHelper defaults.** Passing any metatags to `configure_rspec_to_compile_assets` replaces the defaults, so include `:js`, `:server_rendering`, and `:controller` alongside `:rsc` if your suite mixes RSC and non-RSC specs, or those tag groups will no longer trigger compilation. > - **`define_derived_metadata` tags every `spec/system` and `spec/features` example.** That is intentional so the first browser request cannot race ahead of RSC bundle compilation, but it compiles for unrelated system tests too. If only some directories exercise RSC, narrow the regex to something like `%r{spec/(system/rsc|features/rsc)}` or tag those examples manually. > - **Load `support/rsc_node_renderer` _after_ registering `configure_rspec_to_compile_assets`.** The Step 3 helper installs a `before(:suite)` hook that validates bundles when the renderer boots, so the compile hook must register first. On older RSpec, also compile assets in CI before running the spec process — see the Caveats note at the end of Step 3. ```ruby # spec/rails_helper.rb require "react_on_rails/test_helper" RSpec.configure do |config| ReactOnRails::TestHelper.configure_rspec_to_compile_assets( config, :rsc, :js, :server_rendering, :controller ) config.define_derived_metadata(file_path: %r{spec/(system|features)}) do |metadata| metadata[:rsc] = true end end require_relative "support/rsc_node_renderer" ``` Tag request specs that hit the RSC payload endpoint explicitly with `:rsc`. If your suite uses a different tag scheme, pass the complete list of tags that should trigger compilation. The important part is that the build runs before the first request that can upload bundles to the node renderer. ### 3. Start One Test Renderer Per Worker Start the renderer in `before(:suite)` after assets are compiled and stop it in `after(:suite)`. The example below assumes your app has a `node-renderer` package script that launches the node-renderer server, reads `RENDERER_PORT` and `RENDERER_SERVER_BUNDLE_CACHE_PATH` from ENV, and serves the RSC test bundle cache. See [Node Renderer JavaScript Configuration](node-renderer/js-configuration.md#example-launch-files) for launch-file and `package.json` script examples. Replace the package-manager command with the one your project uses. > **Warning:** The generated `renderer/node-renderer.js` template hardcodes `serverBundleCachePath` to `path.resolve(__dirname, '../.node-renderer-bundles')`, so it ignores `RENDERER_SERVER_BUNDLE_CACHE_PATH` until you change it. Without this edit every parallel worker shares the same cache directory and you will see stale-bundle and missing-bundle flakes that look like RSC timeouts. Update the launch file to read the env var: > > ```js > // renderer/node-renderer.js > const config = { > serverBundleCachePath: > process.env.RENDERER_SERVER_BUNDLE_CACHE_PATH || path.resolve(__dirname, '../.node-renderer-bundles'), > port: Number(process.env.RENDERER_PORT) || 3800, > // ... > }; > ``` > > The renderer package's built-in default chain is `RENDERER_SERVER_BUNDLE_CACHE_PATH || RENDERER_BUNDLE_PATH || '/tmp/react-on-rails-pro-node-renderer-bundles'`. The middle term is intentionally omitted here because `RENDERER_BUNDLE_PATH` is deprecated; if your existing renderer config relies on it, migrate to `RENDERER_SERVER_BUNDLE_CACHE_PATH` before adopting this snippet so the per-worker cache path actually takes effect. ```ruby # spec/support/rsc_node_renderer.rb require "fileutils" require "socket" require_relative "rsc_test_worker" module RscNodeRenderer module_function def wait_until_ready!(host:, port:, timeout_seconds: 30, log_path: nil, pid: nil) deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout_seconds saw_reset = false loop do begin Socket.tcp(host, port, connect_timeout: 1).close break rescue Errno::ECONNREFUSED, Errno::ETIMEDOUT # Port not yet open; renderer still booting. rescue Errno::ECONNRESET # Connection reset: renderer bound the port but closed the connection before accepting. # Fall through — the PID check below will detect a dead process and raise before the deadline. # If the deadline expires without a successful connect, the deadline error mentions the reset # so a port already used by another service is easier to diagnose than a generic timeout. saw_reset = true rescue Errno::EADDRNOTAVAIL, Errno::EHOSTUNREACH, SocketError => e raise "Cannot reach node renderer at #{host}:#{port}. " \ "Check the host configuration (#{e.class}: #{e.message})." end if pid begin # Heuristic early-exit check: if the launcher process has already died, raise now rather than # waiting for the deadline. For `pnpm run <script>`, pnpm typically stays resident while Node # is alive, but process managers that exec directly into Node (or daemonize) will exit here even # though the renderer is still starting, surfacing a misleading ESRCH. The TCP probe above is # the authoritative readiness signal; this check is only a fast-fail shortcut for the common # pnpm/npm/yarn case. Replace it with an app-specific health check if your launcher daemonizes. Process.kill(0, pid) rescue Errno::ESRCH hint = log_path ? " Check #{log_path} for startup errors." : "" raise "Node renderer process (pid #{pid}) exited before binding to #{host}:#{port}.#{hint}" rescue Errno::EPERM # Process exists but we lack permission to signal it (different UID, seccomp, container boundary). # Continue waiting for the TCP port — the port probe is authoritative for readiness. end end if Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline hint = log_path ? " Check #{log_path} for startup errors." : "" reset_hint = saw_reset ? " (TCP connections were reset — another process may already be using this port)" : "" raise "Node renderer did not boot on #{host}:#{port} within #{timeout_seconds}s.#{hint}#{reset_hint}" end sleep 0.1 end end end # Intentional suite-level closure state shared by before(:suite) and after(:suite). # This avoids relying on RSpec hook instance variables while keeping mutation local to this support file. rsc_node_renderer_pid = nil rsc_node_renderer_waiter = nil RSpec.configure do |config| config.before(:suite) do next unless ENV["RSC_NODE_RENDERER_TESTS"] == "1" cache_path = ENV.fetch("RENDERER_SERVER_BUNDLE_CACHE_PATH") do raise "RENDERER_SERVER_BUNDLE_CACHE_PATH is not set. " \ "Follow Step 1 of this guide to set it before Rails boots so every parallel worker " \ "gets a unique renderer bundle cache directory." end cache_path = cache_path.strip raise "RENDERER_SERVER_BUNDLE_CACHE_PATH is empty." if cache_path.empty? expanded_cache_path = File.expand_path(cache_path, Rails.root.to_s) FileUtils.mkdir_p(Rails.root.join("tmp")) tmp_root = Rails.root.join("tmp").to_s unless expanded_cache_path.start_with?("#{tmp_root}#{File::SEPARATOR}") raise "RENDERER_SERVER_BUNDLE_CACHE_PATH must be inside Rails.root/tmp " \ "(got: #{expanded_cache_path}). " \ "This path is deleted and recreated on every test run, so only paths " \ "inside Rails.root/tmp are permitted to prevent accidental data loss." end FileUtils.rm_rf(expanded_cache_path) FileUtils.mkdir_p(expanded_cache_path) renderer_env = { "NODE_ENV" => "test", "RAILS_ENV" => "test", "RENDERER_PORT" => ENV.fetch("RENDERER_PORT") do raise "RENDERER_PORT is not set. " \ "Follow Step 1 of this guide to set it before Rails boots so every parallel worker " \ "gets a unique renderer port." end, "RENDERER_SERVER_BUNDLE_CACHE_PATH" => expanded_cache_path } renderer_port = begin Integer(renderer_env["RENDERER_PORT"]) rescue ArgumentError raise "RENDERER_PORT must be an integer port number " \ "(got: #{renderer_env['RENDERER_PORT'].inspect})" end begin Socket.tcp("127.0.0.1", renderer_port, connect_timeout: 1).close raise "RENDERER_PORT #{renderer_env['RENDERER_PORT']} is already in use. " \ "A previous test run may have left an orphaned node renderer. " \ "Kill it manually or restart the CI job." rescue Errno::ECONNREFUSED # Port refused immediately — nothing is listening; safe to spawn. rescue Errno::ETIMEDOUT # SYN silently dropped (firewall/throttle). Unusual on 127.0.0.1, so surface it in # CI logs but proceed — treating it as fatal would block tests whenever a stray DROP # rule is present on loopback. warn "RENDERER_PORT #{renderer_env['RENDERER_PORT']} pre-spawn probe timed out on 127.0.0.1; " \ "this is unusual on loopback. Continuing under the assumption that the port is free." rescue Errno::ECONNRESET raise "RENDERER_PORT #{renderer_env['RENDERER_PORT']} accepted and reset a connection. " \ "Another service may already be using it." rescue Errno::EADDRNOTAVAIL, Errno::EHOSTUNREACH, SocketError => e raise "Cannot probe RENDERER_PORT #{renderer_env['RENDERER_PORT']}: #{e.class}: #{e.message}" end FileUtils.mkdir_p(Rails.root.join("log")) renderer_log_path = Rails.root.join("log/node-renderer-test-#{RscTestWorker::ID}.log").to_s rsc_node_renderer_pid = Process.spawn( renderer_env, "pnpm", # replace with "npm", "yarn", or "bun" if that is your package manager "run", "node-renderer", chdir: Rails.root.to_s, out: renderer_log_path, err: [:child, :out], pgroup: true # place pnpm and its child Node process in a new process group ) rsc_node_renderer_waiter = Process.detach(rsc_node_renderer_pid) renderer_timeout_value = ENV.fetch("RSC_NODE_RENDERER_BOOT_TIMEOUT", "30") renderer_timeout = begin Integer(renderer_timeout_value) rescue ArgumentError raise "RSC_NODE_RENDERER_BOOT_TIMEOUT must be an integer number of seconds " \ "(got: #{ENV['RSC_NODE_RENDERER_BOOT_TIMEOUT'].inspect})" end begin RscNodeRenderer.wait_until_ready!( host: "127.0.0.1", port: renderer_port, timeout_seconds: renderer_timeout, log_path: renderer_log_path, pid: rsc_node_renderer_pid ) rescue StandardError begin Process.kill("-TERM", rsc_node_renderer_pid) rescue Errno::ESRCH, Errno::EPERM # Already stopped or no permission to signal the process group; matches the after(:suite) # cleanup so the original startup failure isn't masked by an EPERM here. end rsc_node_renderer_waiter&.join(2) rsc_node_renderer_pid = nil rsc_node_renderer_waiter = nil raise end end config.after(:suite) do pid = rsc_node_renderer_pid next unless pid # Sends SIGTERM to the entire process group so pnpm and the Node child both stop. # Raises Errno::ESRCH if the group is already gone; caught by rescue below. Process.kill("-TERM", pid) # Thread#join returns the waiter thread when the process exits, and nil on timeout. # SIGKILL only fires when SIGTERM did not stop the process within the join window. unless rsc_node_renderer_waiter&.join(5) begin Process.kill("-KILL", pid) rescue Errno::ESRCH # Process stopped between the join timeout and the SIGKILL; nothing more to do. else unless rsc_node_renderer_waiter&.join(5) warn "Node renderer process group #{pid} did not stop after SIGKILL; " \ "it may still occupy the renderer port for the next CI retry." end end end rescue Errno::ESRCH # Already stopped. rescue Errno::EPERM warn "No permission to stop node renderer process group #{pid}; " \ "it may need manual cleanup." ensure rsc_node_renderer_pid = nil rsc_node_renderer_waiter = nil end end ``` Require this file from `spec/rails_helper.rb` after loading `react_on_rails/test_helper`, unless your suite already loads `spec/support/**/*.rb`. On slow CI workers, increase `RSC_NODE_RENDERER_BOOT_TIMEOUT` instead of adding sleeps. > **Note:** The setup writes per-worker artifacts to `tmp/node-renderer-bundles-test-*` and `log/node-renderer-test-*.log`. The default Rails `.gitignore` rules (`/tmp/*` and `/log/*`) cover both, but if you maintain a custom `.gitignore` confirm both paths are excluded so they do not show up as untracked changes on every test run. **Caveats:** - The TCP probe above is a fallback for renderers that do not expose a health endpoint; if your renderer has one, replace the probe with an HTTP health check. A successful TCP connection only proves the port is accepting connections, not that route handlers or bundle manifests are fully initialized. - The `start_with?` safety check on `Rails.root/tmp` compares raw paths; it does **not** resolve symlinks. If your project's `tmp/` directory is a symlink (for example, mounted to a tmpfs path), an absolute `RENDERER_SERVER_BUNDLE_CACHE_PATH` pointing inside the resolved target will fail the check. Resolve both paths with `Pathname#realpath` before comparing if you need to support a symlinked `tmp/`. - A reset during the pre-spawn probe usually means another service is already using the port and closing connections immediately. - The `connect_timeout` call is enough for `127.0.0.1` because an unused localhost port refuses the connection immediately. If you adapt the helper for a remote renderer, the operating system may still apply a longer TCP timeout. - The deadline is checked after each socket probe, so very tight timeouts can overshoot by up to `connect_timeout + sleep` per iteration (roughly 1.1 s with the defaults above). - If CI hard-kills the Ruby process before `after(:suite)` runs, clear any orphaned renderer processes or occupied renderer ports before retrying the job. - `pgroup: true` and the negative-PID `Process.kill("-TERM", pid)` / `Process.kill("-KILL", pid)` calls are POSIX-only. On Windows they raise `NotImplementedError`, so adapt the spawn options and shutdown calls (for example, kill only the spawned PID and rely on the renderer to clean up its child) if you need to run this guide on a native Windows host. CI on Linux/macOS and WSL is unaffected. - The helper relies on the Step 2 `configure_rspec_to_compile_assets` setup so bundles are available before renderer-backed examples run. Load `support/rsc_node_renderer` after registering `configure_rspec_to_compile_assets` so modern RSpec can trigger compilation with `when_first_matching_example_defined` before suite hooks start the renderer. Older RSpec falls back to `before(:example, metatag)`, so compile assets in your CI job before running the spec process if your launcher validates bundles at boot or your suite starts renderer-backed requests outside examples tagged for compilation. In CI, set `RSC_NODE_RENDERER_TESTS=1` for jobs that need the renderer. For local development, leaving it unset lets you run non-RSC specs without starting another process. ### 4. Write A Capybara RSC Smoke Test Keep the first system test boring: visit a route that streams one Server Component and assert on visible HTML plus one hydrated Client Component interaction. For specs that must prove the browser receives streamed RSC payload chunks, use a non-proxy browser driver and keep Puffing Billy out of the RSC payload path. See [System Specs for Streamed RSC Payloads](../../pro/react-server-components/system-spec-streaming-rsc.md) for the driver shape, Billy compatibility boundary, and hydration assertions. ```ruby RSpec.describe "Story page", :rsc, :js, type: :system do it "renders the streamed RSC page and hydrates client controls" do # Replace story_path and selectors with your app's RSC route and content. visit story_path("ruby-rails-react") expect(page).to have_css("h1", text: "Ruby, Rails, and React") expect(page).to have_button("Save") click_button "Save" expect(page).to have_text("Saved") end end ``` Request specs are still useful for the payload endpoint: ```ruby RSpec.describe "RSC payload endpoint", :rsc, type: :request do it "returns an RSC payload stream" do # Replace this path if your app customizes config.rsc_payload_generation_url_path # or rsc_payload_route. get "/rsc_payload/StoryPage", params: { props: { slug: "ruby-rails-react" }.to_json } expect(response).to have_http_status(:ok) expect(response.media_type).to eq("application/x-ndjson") chunks = response.body.lines.map(&:chomp).reject(&:empty?).map { |line| JSON.parse(line) } # "html" is emitted by the default React on Rails RSC renderer; verify custom renderer output explicitly. expect(chunks).to include(include("html" => anything)) end end ``` ### 5. Stub External APIs At The Right Boundary Ruby stubbing tools such as WebMock and VCR only intercept requests from the Rails process. They do not intercept HTTP requests made by JavaScript running inside the separate node-renderer process. Prefer one of these patterns: - Fetch external data in Rails, stub it with WebMock/VCR, and pass deterministic props into the RSC tree. - Point Node-rendered code at a local fake API server started by the test harness. - Inject an API base URL through props or environment variables so tests never call the real service. Avoid letting system tests depend on live third-party APIs. RSC failures from external API drift usually look like renderer timeouts or missing payload chunks, which sends debugging in the wrong direction. ### 6. Parallelization Checklist - Use one renderer port per worker. - Use one renderer bundle cache directory per worker. - Clear the renderer cache before starting the renderer. - Compile assets before the renderer accepts requests. - Do not share a mutable fake API server across workers unless it isolates state per worker. - If flakes remain, serialize the RSC system-test group first, then re-enable parallelism once port/cache isolation is proven. ### Minitest Equivalent Steps 1, 2, 5, and 6 apply to Minitest unchanged, with one path adjustment: Minitest-only projects (no `spec/` directory) should place the Step 1 `RscTestWorker` module at `test/support/rsc_test_worker.rb` so the `require_relative` below resolves correctly. For Step 4, adapt the RSpec system-test example to `ApplicationSystemTestCase` with `assert_css`/`assert_text`, and the request-spec example to an `ActionDispatch::IntegrationTest` subclass with `assert_response`/`assert_equal`. Only the suite-level renderer lifecycle differs: Minitest has no `before(:suite)` hook, so the renderer starts when `test/test_helper.rb` requires its support file (after assets compile) and stops in [`Minitest.after_run`](https://github.com/minitest/minitest/blob/master/lib/minitest.rb). The Rails.root/tmp containment check, port probe, spawn options, `wait_until_ready!` helper, and graceful SIGTERM→SIGKILL shutdown are all reused from [Step 3](#3-start-one-test-renderer-per-worker). Rails-generated Minitest apps often enable `parallelize(workers: :number_of_processors)`. The file-scope startup below assumes each worker is an independent Ruby test process that loads `test/test_helper.rb` separately, such as a `parallel_tests` CI shard. If Rails-native process parallelization remains enabled for RSC system tests, move the renderer startup and cleanup into `parallelize_setup` / `parallelize_teardown` and derive the worker ID from the hook argument, or serialize the RSC system-test group. In that Rails-native variant, keep one cleanup owner per renderer: do not leave the file-scope `Minitest.after_run` block below stopping the same PID that `parallelize_teardown` already stops. If a CI job can run the RSpec and Minitest RSC suites at the same time, give each suite a different renderer port range. For example, keep the RSpec recipe on the default `3900 + RscTestWorker::ID.to_i` range and set a Minitest-specific base such as `3950` before the `RENDERER_PORT` assignment below. Wire `test/test_helper.rb` with the same ENV-before-Rails-boot preamble used in `spec/rails_helper.rb`, then require the renderer lifecycle support file before any test runs. Keep the compilation check at file scope: it runs once for ordinary Minitest suites and, when `RSC_NODE_RENDERER_TESTS=1`, populates the renderer bundle cache before the support file starts the node renderer. ```ruby # test/test_helper.rb ENV["RAILS_ENV"] ||= "test" # Same module as Step 1. For Minitest-only projects, create test/support/rsc_test_worker.rb # with the same content as spec/support/rsc_test_worker.rb. require_relative "support/rsc_test_worker" ENV["RENDERER_PORT"] ||= (3900 + RscTestWorker::ID.to_i).to_s renderer_url = "http://127.0.0.1:#{ENV["RENDERER_PORT"]}" ENV["REACT_RENDERER_URL"] ||= renderer_url # used by config.renderer_url = ENV["REACT_RENDERER_URL"] ENV["RENDERER_URL"] ||= renderer_url # used by some older/custom initializers ENV["RENDERER_SERVER_BUNDLE_CACHE_PATH"] ||= File.expand_path("../tmp/node-renderer-bundles-test-#{RscTestWorker::ID}", __dir__) require_relative "../config/environment" require "rails/test_help" require "react_on_rails/test_helper" # Run once at suite start before the optional renderer spawns. ReactOnRails::TestHelper.ensure_assets_compiled require_relative "support/rsc_node_renderer" ``` The renderer support file mirrors `spec/support/rsc_node_renderer.rb`. The `RscNodeRenderer` module and `wait_until_ready!` helper are framework-agnostic; if your project uses both RSpec and Minitest, extract the module to a shared file (for example, `lib/test_support/rsc_node_renderer.rb`) and require it from both helper files instead of redefining it. ```ruby # test/support/rsc_node_renderer.rb require "fileutils" require "socket" require_relative "rsc_test_worker" module RscNodeRenderer module_function # Keep in sync with spec/support/rsc_node_renderer.rb (Step 3). # Keep in sync with spec/support/rsc_node_renderer.rb (Step 3). # Prefer extracting this to a shared file (e.g. lib/test_support/rsc_node_renderer.rb) # and requiring it from both helpers. Copy it here only for single-framework (Minitest-only) projects # where a shared lib/ location adds unnecessary indirection. def wait_until_ready!(host:, port:, timeout_seconds: 30, log_path: nil, pid: nil) deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout_seconds saw_reset = false loop do begin Socket.tcp(host, port, connect_timeout: 1).close break rescue Errno::ECONNREFUSED, Errno::ETIMEDOUT # Port not yet open; renderer still booting. rescue Errno::ECONNRESET # Connection reset: renderer bound the port but closed the connection before accepting. # Fall through — the PID check below will detect a dead process and raise before the deadline. # If the deadline expires without a successful connect, the deadline error mentions the reset # so a port already used by another service is easier to diagnose than a generic timeout. saw_reset = true rescue Errno::EADDRNOTAVAIL, Errno::EHOSTUNREACH, SocketError => e raise "Cannot reach node renderer at #{host}:#{port}. " \ "Check the host configuration (#{e.class}: #{e.message})." end if pid begin # Heuristic early-exit check: if the launcher process has already died, raise now rather than # waiting for the deadline. For `pnpm run <script>`, pnpm typically stays resident while Node # is alive, but process managers that exec directly into Node (or daemonize) will exit here even # though the renderer is still starting, surfacing a misleading ESRCH. The TCP probe above is # the authoritative readiness signal; this check is only a fast-fail shortcut for the common # pnpm/npm/yarn case. Replace it with an app-specific health check if your launcher daemonizes. Process.kill(0, pid) rescue Errno::ESRCH hint = log_path ? " Check #{log_path} for startup errors." : "" raise "Node renderer process (pid #{pid}) exited before binding to #{host}:#{port}.#{hint}" rescue Errno::EPERM # Process exists but we lack permission to signal it (different UID, seccomp, container boundary). # Continue waiting for the TCP port — the port probe is authoritative for readiness. end end if Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline hint = log_path ? " Check #{log_path} for startup errors." : "" reset_hint = saw_reset ? " (TCP connections were reset — another process may already be using this port)" : "" raise "Node renderer did not boot on #{host}:#{port} within #{timeout_seconds}s.#{hint}#{reset_hint}" end sleep 0.1 end end end # File-scope state shared by the eager startup below and the Minitest.after_run hook. rsc_node_renderer_pid = nil rsc_node_renderer_waiter = nil if ENV["RSC_NODE_RENDERER_TESTS"] == "1" cache_path = ENV.fetch("RENDERER_SERVER_BUNDLE_CACHE_PATH") do raise "RENDERER_SERVER_BUNDLE_CACHE_PATH is not set. " \ "Follow Step 1 of this guide to set it before Rails boots so every parallel worker " \ "gets a unique renderer bundle cache directory." end cache_path = cache_path.strip raise "RENDERER_SERVER_BUNDLE_CACHE_PATH is empty." if cache_path.empty? expanded_cache_path = File.expand_path(cache_path, Rails.root.to_s) FileUtils.mkdir_p(Rails.root.join("tmp")) tmp_root = Rails.root.join("tmp").to_s unless expanded_cache_path.start_with?("#{tmp_root}#{File::SEPARATOR}") raise "RENDERER_SERVER_BUNDLE_CACHE_PATH must be inside Rails.root/tmp " \ "(got: #{expanded_cache_path}). " \ "This path is deleted and recreated on every test run, so only paths " \ "inside Rails.root/tmp are permitted to prevent accidental data loss." end FileUtils.rm_rf(expanded_cache_path) FileUtils.mkdir_p(expanded_cache_path) renderer_env = { "NODE_ENV" => "test", "RAILS_ENV" => "test", "RENDERER_PORT" => ENV.fetch("RENDERER_PORT") do raise "RENDERER_PORT is not set. " \ "Follow Step 1 of this guide to set it before Rails boots so every parallel worker " \ "gets a unique renderer port." end, "RENDERER_SERVER_BUNDLE_CACHE_PATH" => expanded_cache_path } renderer_port = begin Integer(renderer_env["RENDERER_PORT"]) rescue ArgumentError raise "RENDERER_PORT must be an integer port number " \ "(got: #{renderer_env['RENDERER_PORT'].inspect})" end begin Socket.tcp("127.0.0.1", renderer_port, connect_timeout: 1).close raise "RENDERER_PORT #{renderer_env['RENDERER_PORT']} is already in use. " \ "A previous test run may have left an orphaned node renderer. " \ "Kill it manually or restart the CI job." rescue Errno::ECONNREFUSED # Port refused immediately — nothing is listening; safe to spawn. rescue Errno::ETIMEDOUT # SYN dropped (firewall/throttle); assume nothing is listening and proceed. rescue Errno::ECONNRESET raise "RENDERER_PORT #{renderer_env['RENDERER_PORT']} accepted and reset a connection. " \ "Another service may already be using it." rescue Errno::EADDRNOTAVAIL, Errno::EHOSTUNREACH, SocketError => e raise "Cannot probe RENDERER_PORT #{renderer_env['RENDERER_PORT']}: #{e.class}: #{e.message}" end FileUtils.mkdir_p(Rails.root.join("log")) renderer_log_path = Rails.root.join("log/node-renderer-test-#{RscTestWorker::ID}.log").to_s rsc_node_renderer_pid = Process.spawn( renderer_env, "pnpm", # replace with "npm", "yarn", or "bun" if that is your package manager "run", "node-renderer", chdir: Rails.root.to_s, out: renderer_log_path, err: [:child, :out], pgroup: true # place pnpm and its child Node process in a new process group ) rsc_node_renderer_waiter = Process.detach(rsc_node_renderer_pid) renderer_timeout_value = ENV.fetch("RSC_NODE_RENDERER_BOOT_TIMEOUT", "30") renderer_timeout = begin Integer(renderer_timeout_value) rescue ArgumentError raise "RSC_NODE_RENDERER_BOOT_TIMEOUT must be an integer number of seconds " \ "(got: #{ENV['RSC_NODE_RENDERER_BOOT_TIMEOUT'].inspect})" end begin RscNodeRenderer.wait_until_ready!( host: "127.0.0.1", port: renderer_port, timeout_seconds: renderer_timeout, log_path: renderer_log_path, pid: rsc_node_renderer_pid ) rescue StandardError begin Process.kill("-TERM", rsc_node_renderer_pid) rescue Errno::ESRCH, Errno::EPERM # Already stopped or no permission to signal; surfaces the original startup error. end rsc_node_renderer_waiter&.join(2) rsc_node_renderer_pid = nil rsc_node_renderer_waiter = nil raise end end Minitest.after_run do pid = rsc_node_renderer_pid next unless pid begin # Sends SIGTERM to the entire process group so pnpm and the Node child both stop. Process.kill("-TERM", pid) # Thread#join returns the waiter thread when the process exits, and nil on timeout. # SIGKILL only fires when SIGTERM did not stop the process within the join window. unless rsc_node_renderer_waiter&.join(5) begin Process.kill("-KILL", pid) rescue Errno::ESRCH # Stopped between the join timeout and the SIGKILL; nothing more to do. else unless rsc_node_renderer_waiter&.join(5) warn "Node renderer process group #{pid} did not stop after SIGKILL; " \ "it may still occupy the renderer port for the next CI retry." end end end rescue Errno::ESRCH # Already stopped. rescue Errno::EPERM warn "No permission to stop node renderer process group #{pid}; " \ "it may need manual cleanup." ensure rsc_node_renderer_pid = nil rsc_node_renderer_waiter = nil end end ``` The [caveats listed for the RSpec recipe](#3-start-one-test-renderer-per-worker) apply equally here: the TCP probe is a fallback for renderers without a health endpoint, `pgroup: true` and the negative-PID `Process.kill` calls are POSIX-only, and CI hard-kills bypass `Minitest.after_run` so clear orphaned renderer processes or occupied ports before retrying the job. Set `RSC_NODE_RENDERER_TESTS=1` on CI jobs that need the renderer; leaving it unset lets local non-RSC Minitest runs skip the renderer entirely. ## Two Approaches to Test Asset Compilation React on Rails supports two mutually exclusive approaches for compiling webpack assets during tests: ### Approach 1: React on Rails Test Helper + build_test_command (Recommended) **Best for:** Most applications, especially SSR, large suites, and explicit build control **Configuration:** ```ruby # config/initializers/react_on_rails.rb ReactOnRails.configure do |config| config.build_test_command = "RAILS_ENV=test bin/shakapacker" # NODE_ENV is derived from RAILS_ENV by Shakapacker # Or use your project's package manager with a custom script: # config.build_test_command = "pnpm run build:test" # or: npm run build:test, yarn run build:test end ``` In `config/shakapacker.yml`, keep test compilation off to avoid mixing approaches: ```yaml test: <<: *default compile: false public_output_path: webpack/test ``` Then configure your test framework: **RSpec:** ```ruby # spec/rails_helper.rb require "react_on_rails/test_helper" RSpec.configure do |config| # Ensures webpack assets are compiled before the test suite runs ReactOnRails::TestHelper.configure_rspec_to_compile_assets(config) end ``` See [lib/react_on_rails/test_helper.rb](https://github.com/shakacode/react_on_rails/blob/main/react_on_rails/lib/react_on_rails/test_helper.rb) for more details and customization options. By default, the helper triggers compilation for examples tagged with `:js`, `:server_rendering`, or `:controller`. You can pass custom metatags as an optional second parameter if you need compilation for other specs — for example, if you use Webpack to build CSS assets for request and feature specs: ```ruby # spec/rails_helper.rb RSpec.configure do |config| ReactOnRails::TestHelper.configure_rspec_to_compile_assets(config, :requires_webpack_assets) config.define_derived_metadata(file_path: %r{spec/(features|requests)}) do |metadata| metadata[:requires_webpack_assets] = true end end ``` **Minitest:** ```ruby # test/test_helper.rb require "react_on_rails/test_helper" class ActiveSupport::TestCase setup do ReactOnRails::TestHelper.ensure_assets_compiled end end ``` Alternatively, you can use a [Minitest plugin](https://github.com/minitest/minitest/blob/master/lib/minitest/test.rb#L119) to run the check in `before_setup`: ```ruby module MyMinitestPlugin def before_setup super ReactOnRails::TestHelper.ensure_assets_compiled end end class Minitest::Test include MyMinitestPlugin end ``` **Asset detection settings:** The following settings in `config/initializers/react_on_rails.rb` control how the test helper detects stale assets: ```ruby ReactOnRails.configure do |config| # Define the files to check for Webpack compilation when running tests. config.webpack_generated_files = %w( manifest.json ) # If you're not hashing the server bundle, include it in the list: # config.webpack_generated_files = %w( server-bundle.js manifest.json ) end ``` > **Important:** The `build_test_command` **must not** include the `--watch` option. If you have separate server and client bundles, the command **must** build all of them. **How it works:** - Compiles assets at most once per test run, and only when they're out of date (stale) - The helper checks the Webpack-generated files folder (configured via `public_root_path` and `public_output_path` in `config/shakapacker.yml`). If the folder is missing, empty, or contains files listed in `webpack_generated_files` with `mtime`s older than any source files, assets are recompiled. - Uses the `build_test_command` configuration - Fails fast if compilation has errors **Pros:** - ✅ Explicit control over compilation timing - ✅ Assets compiled only once per test run - ✅ Clear error messages if compilation fails - ✅ Can customize the build command - ✅ Reliable for SSR tests because assets are built before first render **Cons:** - ⚠️ Requires additional configuration in test helpers - ⚠️ More setup to maintain - ⚠️ Requires `build_test_command` to be set **When to use:** - You want to compile assets exactly once before tests - You need to customize the build command - You want explicit error handling for compilation failures - Your test suite is slow and you want to optimize compilation - You run SSR tests and need server bundles available before first request ### Approach 2: Shakapacker Auto-Compilation (Alternative) **Best for:** Simpler non-SSR test setups or teams that prefer minimal configuration **Configuration:** ```yaml # config/shakapacker.yml test: <<: *default compile: true public_output_path: webpack/test ``` And remove React on Rails TestHelper wiring: - Remove `config.build_test_command` - Remove `ReactOnRails::TestHelper` calls in `spec/rails_helper.rb` or `test/test_helper.rb` **How it works:** - Shakapacker compiles assets on demand when packs are requested - No React on Rails TestHelper setup is required **Pros:** - ✅ Simpler setup - ✅ Works across frameworks without helper wiring **Cons:** - ⚠️ Less explicit compilation timing - ⚠️ May compile multiple times in long or parallel runs - ⚠️ For SSR tests, first-request ordering can matter if server bundles are not prebuilt ## Don't Mix Approaches **Do not use both approaches together.** They are mutually exclusive: ```yaml # config/shakapacker.yml test: compile: true # ← Don't do this... ``` ```ruby # config/initializers/react_on_rails.rb config.build_test_command = "RAILS_ENV=test bin/shakapacker" # ← ...with this # spec/rails_helper.rb ReactOnRails::TestHelper.configure_rspec_to_compile_assets(config) # ← ...and this ``` This will cause assets to be compiled multiple times unnecessarily. ## Migrating Between Approaches ### From React on Rails Test Helper → Shakapacker Auto-Compilation 1. Set `compile: true` in `config/shakapacker.yml` test section: ```yaml test: compile: true public_output_path: webpack/test ``` 2. Remove test helper configuration from spec/test helpers: ```ruby # spec/rails_helper.rb - REMOVE these lines: require "react_on_rails/test_helper" ReactOnRails::TestHelper.configure_rspec_to_compile_assets(config) ``` 3. Remove or comment out `build_test_command` in React on Rails config: ```ruby # config/initializers/react_on_rails.rb # config.build_test_command = "RAILS_ENV=test bin/shakapacker" # ← Comment out ``` ### From Shakapacker Auto-Compilation → React on Rails Test Helper 1. Set `compile: false` in `config/shakapacker.yml` test section: ```yaml test: compile: false public_output_path: webpack/test ``` 2. Add `build_test_command` to React on Rails config: ```ruby # config/initializers/react_on_rails.rb config.build_test_command = "RAILS_ENV=test bin/shakapacker" ``` 3. Add test helper configuration: ```ruby # spec/rails_helper.rb (for RSpec) require "react_on_rails/test_helper" RSpec.configure do |config| ReactOnRails::TestHelper.configure_rspec_to_compile_assets(config) end ``` ## Verifying Your Configuration Use the React on Rails doctor command to verify your test configuration: ```bash bundle exec rake react_on_rails:doctor ``` To auto-apply supported test-setup fixes (recommended path), run: ```bash FIX=true bundle exec rake react_on_rails:doctor ``` The doctor will check: - Whether `compile: true` is set in shakapacker.yml - Whether `build_test_command` is configured - Whether test helpers are properly set up - Whether each detected framework (RSpec/Minitest) is wired independently - Whether you're accidentally using both approaches ## Troubleshooting ### Assets not compiling during tests **Problem:** Tests fail because JavaScript/CSS assets are not compiled. **Solution:** Check which approach you're using: 1. **If using Shakapacker auto-compilation:** ```yaml # config/shakapacker.yml test: compile: true # ← Make sure this is true ``` 2. **If using React on Rails test helper:** - Verify `build_test_command` is set - Check that test helper is configured in spec/test helper - Run `bundle exec rake react_on_rails:doctor` ### Assets compiling multiple times **Problem:** Tests are slow because assets compile repeatedly. **Solutions:** 1. **If using Shakapacker auto-compilation:** - Switch to React on Rails test helper for one-time compilation - Or ensure `cache_manifest: true` in shakapacker.yml 2. **If using React on Rails test helper:** - This shouldn't happen - assets should compile only once - Check that you don't also have `compile: true` in shakapacker.yml ### Stale assets not recompiling **Problem:** You added a source file but the test helper doesn't trigger recompilation. **Cause:** The test helper compares `mtime`s of source files against generated output files. If you add a source file that has an older timestamp than the existing output (e.g., copied from another directory or restored from version control), it won't be detected as a change. **Solution:** Clear out your Webpack-generated files directory to force recompilation: ```bash rm -rf public/webpack/test ``` If this started after switching branches or changing package versions, run `bin/dev clean` to stop any `bin/dev` watchers and clear the relevant generated bundles and build caches. See [Generated Bundle Files and Cache Cleanup](./dev-server-and-testing.md#generated-bundle-files-and-cache-cleanup) for the command-by-command cleanup behavior. ### Build command fails **Problem:** `build_test_command` fails with errors. **Check:** 1. Does `bin/shakapacker` exist and is it executable? ```bash ls -la bin/shakapacker chmod +x bin/shakapacker # If needed ``` 2. Can you run the command manually? ```bash RAILS_ENV=test bin/shakapacker ``` 3. Are your webpack configs valid for test environment? ### Test helper not found **Problem:** `LoadError: cannot load such file -- react_on_rails/test_helper` **Solution:** Make sure react_on_rails gem is available in test environment: ```ruby # Gemfile gem "react_on_rails" # Not in a specific group # Or explicitly in test group: group :test do gem "react_on_rails" end ``` ## Performance Considerations ### Asset Compilation Speed **Shakapacker auto-compilation:** - Compiles on first request per test process - May compile multiple times in parallel test environments - Good for: Small test suites, simple webpack configs **React on Rails test helper:** - Compiles once before entire test suite - Blocks test start until compilation complete - Good for: Large test suites, complex webpack configs ### Faster Development with Watch Mode If you're using the React on Rails test helper and want to avoid waiting for compilation on each test run, run your build command with the `--watch` flag in a separate terminal: ```bash RAILS_ENV=test bin/shakapacker --watch # Or with your package manager: # pnpm run build:test --watch # npm run build:test -- --watch # yarn run build:test --watch ``` This keeps webpack running and recompiling automatically when files change, so your tests start faster. > **Note:** The `--watch` flag should only be used in a separate terminal process — never include it in `build_test_command`, which must exit after compilation. ### Automatic Dev Asset Reuse (Static Mode) When you run `bin/dev static`, React on Rails automatically detects the fresh development assets and reuses them for tests — **no extra commands or environment variables needed**. ```bash # Terminal 1: Start static development bin/dev static # Terminal 2: Just run tests — they automatically use dev assets bundle exec rspec ``` **How it works:** When `bundle exec rspec` (or Minitest) runs and test assets are stale or missing, the TestHelper checks if development assets in `public/packs/` are: 1. Present (manifest.json exists) 2. Static mode (not HMR — no `http://` URLs in manifest entries) 3. Fresh (manifest newer than all source files) If all checks pass, React on Rails temporarily overrides Shakapacker's test config to point at the development output. You'll see: ```text ====> React on Rails: Reusing development assets from packs (detected fresh static-mode webpack output, skipping test compilation) ``` No `shakapacker.yml` changes are needed. The override only lasts for the test process. ### Running `bin/dev` (HMR) and Tests Together HMR assets are served from webpack-dev-server memory and contain `http://` URLs in the manifest, so they **cannot** be reused by tests. When using HMR mode, you have two options: **Option A: Let TestHelper compile on demand (simplest)** ```bash # Terminal 1 bin/dev # Terminal 2 — TestHelper runs build_test_command automatically if assets are stale bundle exec rspec ``` This works but adds compilation time to the first test run. **Option B: Use a test watcher for fast iteration** ```bash # Terminal 1 bin/dev # Terminal 2 — keeps test assets fresh in the background bin/dev test-watch # Terminal 3 bundle exec rspec ``` `bin/dev test-watch` auto-selects watch mode: - `auto` (default): picks `client-only` if another shakapacker watcher is already running; otherwise `full` - `full`: always builds test client + server bundles (`--test-watch-mode=full`) - `client-only`: only builds test client bundles (`--test-watch-mode=client-only`) ### Which Mode Should I Use? | Scenario | Recommendation | | --------------------------- | ------------------------------------------------------------ | | General development | `bin/dev static` — simpler, no FOUC, tests just work | | Need Hot Module Replacement | `bin/dev` + `bin/dev test-watch` for fast test iteration | | CI / no dev server running | Just `bundle exec rspec` — TestHelper compiles automatically | | Only running a few tests | `bin/dev static` + `bundle exec rspec spec/path/to_spec.rb` | ### Migration to `bin/dev test-watch` If you previously ran manual test watcher commands, migrate to the new wrapper: - Old: `RAILS_ENV=test bin/shakapacker --watch` - New: `bin/dev test-watch` - Old: `RAILS_ENV=test CLIENT_BUNDLE_ONLY=yes bin/shakapacker --watch` - New: `bin/dev test-watch --test-watch-mode=client-only` ### Advanced: Manual Shared Output (Alternative) If you prefer to manually share output paths instead of using automatic detection: 1. Set the test output path equal to development in `config/shakapacker.yml`: ```yaml development: public_output_path: packs test: public_output_path: packs ``` 2. Run static development mode and tests: ```bash bin/dev static # Terminal 1 bundle exec rspec # Terminal 2 ``` > [!WARNING] > Do not share output paths with `bin/dev` (HMR mode) — HMR manifests will cause test failures. ### Caching Strategies Improve compilation speed with caching: ```yaml # config/shakapacker.yml test: cache_manifest: true # Cache manifest between runs ``` ### Parallel Testing When running tests in parallel (with `parallel_tests` gem): **Shakapacker auto-compilation:** - Each process compiles independently (may be slow) - Consider precompiling assets before running parallel tests: ```bash RAILS_ENV=test bin/shakapacker bundle exec rake parallel:spec ``` **React on Rails test helper:** - Compiles once before forking processes (efficient) - Works well out of the box with parallel testing ## CI/CD Considerations ### GitHub Actions / GitLab CI **Option 1: Precompile before tests** ```yaml - name: Compile test assets run: RAILS_ENV=test bundle exec rake react_on_rails:assets:compile_environment - name: Run tests run: bundle exec rspec ``` **Option 2: Use Shakapacker auto-compilation** ```yaml # config/shakapacker.yml test: compile: true # CI workflow - name: Run tests (assets auto-compile) run: bundle exec rspec ``` ### Docker When running tests in Docker, consider: 1. Caching `node_modules` between builds 2. Precompiling assets in Docker build stage 3. Using bind mounts for local development ## Best Practices 1. **Choose one approach** - Don't mix Shakapacker auto-compilation with React on Rails test helper 2. **Use doctor command** - Run `rake react_on_rails:doctor` to verify configuration 3. **Precompile in CI** - Consider precompiling assets before running tests in CI 4. **Cache node_modules** - Speed up installation with caching 5. **Monitor compile times** - If tests are slow, check asset compilation timing ## Summary Decision Matrix | Scenario | Recommendation | | -------------------- | ---------------------------------------- | | Default setup | React on Rails test helper | | SSR test coverage | React on Rails test helper | | Large test suite | React on Rails test helper | | Parallel testing | React on Rails test helper or precompile | | CI/CD pipeline | Precompile before tests | | Quick local tests | Shakapacker `compile: true` | | Custom build command | React on Rails test helper | ## Related Documentation - [Dev Server and Testing](./dev-server-and-testing.md) — How `bin/dev` (HMR vs static) interacts with Capybara, Playwright, Minitest system tests, and SSR request specs - [Configuration Reference](../configuration/README.md#build_test_command) - [Shakapacker Configuration](https://github.com/shakacode/shakapacker#configuration) - [TestHelper Source Code](https://github.com/shakacode/react_on_rails/blob/main/react_on_rails/lib/react_on_rails/test_helper.rb) ## Need Help? - **Forum:** [ShakaCode Forum](https://forum.shakacode.com/) - **Docs:** [React on Rails Guides](https://reactonrails.com/docs/) - **Support:** [justin@shakacode.com](mailto:justin@shakacode.com) ================================================================================ PAGE: https://reactonrails.com/docs/building-features/extensible-precompile-pattern SOURCE: docs/oss/building-features/extensible-precompile-pattern.md ================================================================================ # Extensible bin/dev Precompile Pattern This guide describes an alternative approach to handling precompile tasks that provides more flexibility than the default `precompile_hook` mechanism. This pattern is especially useful for projects with custom build requirements. ## Overview React on Rails offers two approaches for running tasks before webpack compilation: | Approach | Best For | Complexity | | ----------------------------- | ---------------------------------------------------------- | ---------- | | **Default (precompile_hook)** | Simple projects, single precompile task | Low | | **Extensible (bin/dev)** | Custom build steps, multiple tasks, version manager issues | Medium | ## When to Use This Pattern Consider this approach if you: - Have multiple precompile tasks (ReScript, TypeScript compilation, custom locale generation) - Experience version manager issues (mise, asdf, rbenv) with rake tasks - Want cleaner Procfiles without embedded precompile logic - Need direct Ruby API access for faster execution - Want a single place to manage all precompile tasks ## Implementation ### Migration Checklist If you have not already completed Sections 1–4 below (start at [Section 1](#1-customize-bindev)), do that first so `bin/dev`, `config/shakapacker.yml`, your Procfiles, and your build commands are in place before you start removing duplicates. When moving custom build work out of `precompile_hook`, make the ownership change in one commit so the same task cannot run twice. The checklist uses letters (A–E) so the steps are easy to distinguish from the numbered Implementation sections referenced above. A. Add (or uncomment, if already present) custom one-time tasks to the `run_precompile_tasks` method in `bin/dev` (see [Section 1](#1-customize-bindev) for the generator-provided template). B. Ensure `build_test_command` and `build_production_command` each include every one-time build task those lifecycles need, such as ReScript builds, TypeScript checks or compilation, and locale generation. `bin/dev` is not invoked in CI or production, so these commands are the only mechanism those lifecycles have. C. After verifying the updated commands work locally, remove one-time build commands from individual Procfile process entries. If those same commands appear as standalone steps in CI/CD pipeline scripts, remove those duplicate invocations too. For example, remove a bare `yarn res:build` GitHub Actions step only after `build_test_command` or `build_production_command` includes it. Do not delete entire `.github/workflows`, `.circleci/config.yml`, or Heroku `app.json` files unless they exist solely for the migrated build step. D. Confirm `precompile_hook` has been removed from `config/shakapacker.yml` (per [Section 2](#2-configure-shakapackeryml)) so the same task does not also run during webpack compiles. E. Keep long-running watchers, such as `rescript: yarn res:watch`, as separate Procfile processes. The goal is one owner per lifecycle: `bin/dev` owns development startup, Procfile processes own long-running watchers, and React on Rails build commands own test and production compilation. ### 1. Customize bin/dev The React on Rails generator creates a `bin/dev` script with an extensible precompile pattern. Uncomment and customize the `run_precompile_tasks` method: ```ruby #!/usr/bin/env ruby # frozen_string_literal: true def run_precompile_tasks require_relative "../config/environment" puts "📦 Running precompile tasks..." # Example: Build ReScript files print " ReScript build... " unless system("yarn res:build") puts "❌" exit(1) end puts "✅" # Locale generation via direct Ruby API (faster, no shell issues) # compile handles all edge cases gracefully: prints warnings if no locale # files found, skips if output files are up-to-date, safe to call always. # Exceptions (e.g., missing directories) bubble up and stop the server, # which surfaces configuration issues early. print " Locale generation... " ReactOnRails::Locales.compile if ReactOnRails.configuration.i18n_dir.present? puts "✅" # Add more custom tasks as needed # print " Custom task... " # YourCustomModule.run # puts "✅" puts "" end require "bundler/setup" require "react_on_rails/dev" DEFAULT_ROUTE = "hello_world" argv_with_defaults = ARGV.dup argv_with_defaults.push("--route=#{DEFAULT_ROUTE}") unless argv_with_defaults.any? { |arg| arg.start_with?("--route") } # Run precompile tasks before starting server (except for kill/help commands) unless ARGV.include?("kill") || ARGV.include?("-h") || ARGV.include?("--help") || ARGV.include?("help") run_precompile_tasks end ReactOnRails::Dev::ServerManager.run_from_command_line(argv_with_defaults) ``` ### 2. Configure shakapacker.yml Remove the `precompile_hook` from `config/shakapacker.yml`, since `bin/dev` now handles precompile tasks directly: **Before (default precompile_hook approach):** ```yaml default: &default # ... other settings ... precompile_hook: 'bundle exec rake react_on_rails:locale' ``` **After (extensible bin/dev approach):** ```yaml default: &default # ... other settings ... # precompile_hook is not used here because: # - In development: bin/dev runs precompile tasks before starting processes # - In production: build_production_command includes all build steps # precompile_hook not configured - handled by bin/dev instead ``` ### 3. Clean Procfiles Remove precompile logic from your Procfiles: **Before (embedded precompile logic):** ```procfile # Procfile.dev - Old approach with duplicated precompile rescript: yarn res:watch rails: bundle exec rails server -p 3000 wp-client: sleep 15 && bundle exec rake react_on_rails:locale && bin/shakapacker-dev-server wp-server: SERVER_BUNDLE_ONLY=true bin/shakapacker --watch ``` **After (clean and simple):** ```procfile # Procfile.dev - Clean approach with precompile in bin/dev rescript: yarn res:watch rails: bundle exec rails server -p 3000 wp-client: bin/shakapacker-dev-server wp-server: SERVER_BUNDLE_ONLY=true bin/shakapacker --watch ``` ### 4. Configure Build Commands Handle test and production builds in `config/initializers/react_on_rails.rb`. These commands must include every build step that production deploys and CI test runs require, because `bin/dev` is not part of those lifecycles: In CI, ReactOnRails::TestHelper runs `build_test_command` when test assets need compilation. See [testing configuration](testing-configuration.md#quick-start) for the RSpec/Minitest wiring. During `assets:precompile`, React on Rails runs `build_production_command`. Choose one of the following configuration styles. Use only one: Option A sets the commands directly, while Option B points both commands at the helper script. #### Option A - Inline commands ```ruby ReactOnRails.configure do |config| # Build commands should include all necessary steps. # Shakapacker auto-derives NODE_ENV from RAILS_ENV, so the test command leaves NODE_ENV implicit. # The production command sets NODE_ENV=production explicitly as a belt-and-suspenders safeguard # against any pre-shakapacker step (e.g. a custom yarn script) that reads NODE_ENV directly. config.build_test_command = "yarn res:build && RAILS_ENV=test bin/shakapacker" config.build_production_command = "yarn res:build && RAILS_ENV=production NODE_ENV=production bin/shakapacker" end ``` #### Option B - Script wrapper (recommended for multi-step builds) If your build needs more than one pre-shakapacker step, such as a TypeScript check and a ReScript compile, prefer a small Ruby script over a very long command string. Create `bin/build-react-on-rails`: ```ruby #!/usr/bin/env ruby # frozen_string_literal: true require "rbconfig" # Pin the working directory to the Rails application root so the relative paths below resolve correctly even when # `config.node_modules_location` is a subdirectory. React on Rails prepends `cd "<node_modules_location>"` to # `build_test_command` and `build_production_command`, which would otherwise leave the script looking for # `bin/shakapacker` under that subdirectory. See the note under the configuration example below for invoking the # wrapper itself from a custom `node_modules_location`. Dir.chdir(File.expand_path("..", __dir__)) mode = ARGV.first unless %w[test production].include?(mode) abort "Usage: bin/build-react-on-rails test|production\nGot: #{mode.inspect}" end # Add your app's pre-build step(s) here. They run for both test and production. # Leave this section empty if shakapacker is the only build step. # If a pre-build command needs env vars, pass them via a hash: # system({ "SOME_VAR" => "value" }, "yarn", "custom:build") || abort("custom:build failed") # The mode-specific env hashes below are intentionally scoped to each shakapacker call. # For example, to run TypeScript then ReScript: # # --noEmit type-checks only; ts-loader/babel-loader handle transpilation during webpack bundling. # system("yarn", "tsc", "--noEmit") || abort("tsc type-check failed") # system("yarn", "res:build") || abort("res:build failed") # Mode-specific invocation below. `RbConfig.ruby` runs shakapacker with the same Ruby interpreter that launched this # wrapper, and the `Dir.chdir` above keeps `bin/shakapacker` resolvable from the Rails application root. The # shakapacker binstub is a Ruby file by convention, so passing it to `RbConfig.ruby` is portable; if your project # replaces `bin/shakapacker` with a shell wrapper, drop `RbConfig.ruby` and invoke the binstub directly (after # ensuring the right Ruby is on `PATH`). Add shared steps above, not inside the case blocks. case mode when "test" env = { "RAILS_ENV" => "test" } system(env, RbConfig.ruby, "bin/shakapacker") || abort("shakapacker (test) failed") when "production" env = { "RAILS_ENV" => "production", "NODE_ENV" => "production" } system(env, RbConfig.ruby, "bin/shakapacker") || abort("shakapacker (production) failed") end ``` On Unix-like filesystems, make the script executable so it can run locally, then stage the file so Git records the executable bit for CI and other checkouts: ```bash chmod +x bin/build-react-on-rails git add bin/build-react-on-rails ``` `git add --chmod=+x bin/build-react-on-rails` (Git 2.9 or newer) is a useful shortcut, but it only updates the executable bit in Git's index — the file mode on disk is left unchanged. The script will still not be runnable from this checkout until `chmod +x` is also applied. Use the shortcut when CI is the only consumer that needs the executable bit; otherwise keep the two-step `chmod +x` then `git add` so the file is executable both locally and in committed history. <details> <summary>Windows and Docker bind mounts</summary> On Windows or Docker bind mounts backed by a Windows filesystem, the filesystem may not preserve Unix modes, so `chmod` may not make the current checkout runnable. Record the executable bit in Git for CI and other checkouts, and invoke the script through Ruby when running it from that local filesystem: ```bash git update-index --chmod=+x bin/build-react-on-rails ruby bin/build-react-on-rails test ``` If the file has not been staged yet, use `git update-index --add --chmod=+x bin/build-react-on-rails` instead. Use `production` instead of `test` for the production build command. The `git update-index` command only updates Git metadata; it does not change the current working-tree file mode. Configure `react_on_rails.rb` once. Prefix the helper with `ruby` so the same commands work on Unix, macOS, CI, and Windows or Windows-backed Docker bind-mount checkouts without relying on the current filesystem's executable bit. The outer `ruby` is resolved via `PATH` when Rails runs the build command, which works under rbenv/asdf/mise and standard CI images. For hermetic environments where `PATH` may not select the project's interpreter (e.g. some Docker base images without active version-manager shims), invoke through Bundler or substitute an absolute Ruby path — for example `bundle exec ruby bin/build-react-on-rails test` or `$(rbenv which ruby) bin/build-react-on-rails test`. Inside the script, `RbConfig.ruby` already pins shakapacker to the same interpreter that launched the wrapper. </details> ```ruby # config/initializers/react_on_rails.rb ReactOnRails.configure do |config| config.build_test_command = "ruby bin/build-react-on-rails test" config.build_production_command = "ruby bin/build-react-on-rails production" end ``` > **If you set `config.node_modules_location`:** React on Rails prepends `cd "<node_modules_location>"` to both > build commands, so the bare `ruby bin/build-react-on-rails …` invocation above will not find the wrapper from a > subdirectory. Interpolate an absolute path from `Rails.root` so the script is locatable regardless of the > prepended `cd`. React on Rails passes these command strings to a shell, so escape the interpolated path with > `Shellwords.escape` (Ruby stdlib) — a bare `#{wrapper}` would break on any `Rails.root` containing spaces or > other shell metacharacters (e.g. `/Users/jane doe/my app`): > > ```ruby > require "shellwords" > > wrapper = Shellwords.escape(Rails.root.join("bin", "build-react-on-rails").to_s) > config.build_test_command = "ruby #{wrapper} test" > config.build_production_command = "ruby #{wrapper} production" > ``` > > The `Dir.chdir` inside the wrapper then re-pins the working directory to the Rails root for the inner > `bin/shakapacker` call. This keeps the migration reviewable and avoids duplicating custom build logic across `bin/dev`, Procfiles, and deploy scripts. ## Direct Ruby API Reference ### ReactOnRails::Locales.compile Generates locale files for i18n support. ```ruby # Basic usage - skips if files are up-to-date ReactOnRails::Locales.compile # Force regeneration ReactOnRails::Locales.compile(force: true) ``` This method: - Reads YAML locale files from `config.i18n_yml_dir` (or Rails i18n load path) - Generates JavaScript/JSON files in `config.i18n_dir` - Skips generation if output files are newer than source files (unless `force: true`) - Supports both JSON and JavaScript output formats based on `config.i18n_output_format` ### ReactOnRails::PacksGenerator Generates webpack pack files for auto-bundling. ```ruby # Generate packs if stale (used by bin/dev automatically) ReactOnRails::PacksGenerator.instance.generate_packs_if_stale ``` ## Benefits Comparison | Aspect | Default (precompile_hook) | Extensible (bin/dev) | | --------------------------------- | ------------------------------------ | --------------------------------------------- | | **Custom build steps** | Modify hook script (mixing concerns) | Add to `run_precompile_tasks` method | | **Procfile clarity** | May need embedded shell commands | Clean, single-purpose processes | | **Locale generation** | Via rake task (slow, shell issues) | Direct `ReactOnRails::Locales.compile` (fast) | | **Version manager compatibility** | Rake task may use wrong Ruby | Direct Ruby call uses correct version | | **Debugging** | Multiple indirection layers | Clear sequential execution | | **When precompile runs** | Before each webpack compile | Once at dev server startup | ## Execution Timing With this pattern, precompile tasks run: - Once when you start `bin/dev` - On manual restarts of `bin/dev` - **Not** on file changes during development - **Not** on webpack hot reload For file-watching behavior (e.g., ReScript watch mode), add a separate Procfile process instead. For production builds, ensure all tasks are included in `build_production_command`. ## Troubleshooting ### Version Manager Issues If you experience issues where rake tasks use the wrong Ruby version (common with mise, asdf, or rbenv in non-interactive shells): 1. Use the direct Ruby API in `bin/dev` instead of rake tasks 2. The Rails environment loaded in `bin/dev` will use the correct Ruby version ### Missing Environment If you see "uninitialized constant ReactOnRails" errors: ```ruby # Ensure Rails environment is loaded before using React on Rails APIs require_relative "../config/environment" ``` ### Precompile Tasks Running Multiple Times If using this pattern, ensure you: 1. Remove the `precompile_hook` from `shakapacker.yml` 2. Remove precompile commands from Procfile entries 3. Only call `run_precompile_tasks` once in `bin/dev` ## FAQ ### When should I NOT use this pattern? Stick with the default `precompile_hook` approach if: - You only have a single precompile task (e.g., locale generation) - Your version manager works fine with rake tasks in all contexts - You prefer Shakapacker to handle precompile timing automatically The extensible pattern adds configuration overhead that isn't justified for simple setups. ## Compatibility This pattern requires **React on Rails 16.4.0+** and works with any version of Shakapacker. The `ReactOnRails::Locales.compile` API has been available since React on Rails introduced i18n support and is the same method used internally by the `react_on_rails:locale` rake task. ## See Also - [Process Managers](./process-managers.md) - Using Overmind/Foreman with bin/dev - [Internationalization](./i18n.md) - i18n configuration and locale generation - [Auto-Bundling](../core-concepts/auto-bundling-file-system-based-automated-bundle-generation.md) - Automatic component pack generation ================================================================================ PAGE: https://reactonrails.com/docs/building-features/process-managers SOURCE: docs/oss/building-features/process-managers.md ================================================================================ # Using Process Managers with React on Rails React on Rails requires running multiple processes simultaneously during development: - Rails server - Webpack dev server (client bundle) - Webpack watcher (server bundle) ## Running Your Development Server React on Rails includes `bin/dev` which automatically uses Overmind or Foreman: ```bash ./bin/dev ``` This script will: 1. Check database connectivity (unless disabled) 2. Check required external services (if `.dev-services.yml` exists) 3. Run Shakapacker's `precompile_hook` once (if configured in `config/shakapacker.yml`) 4. Set `SHAKAPACKER_SKIP_PRECOMPILE_HOOK=true` to prevent duplicate execution 5. Try to use Overmind (if installed) 6. Fall back to Foreman (if installed) 7. Show installation instructions if neither is found ### Precompile Hook Integration If you have configured a `precompile_hook` in `config/shakapacker.yml`, `bin/dev` will automatically: - Execute the hook **once** before starting development processes - Set the `SHAKAPACKER_SKIP_PRECOMPILE_HOOK` environment variable - Pass this environment variable to all spawned processes (Rails, webpack, etc.) - Prevent webpack processes from re-running the hook independently **Note:** Shakapacker 9.4.0+ supports `SHAKAPACKER_SKIP_PRECOMPILE_HOOK` natively. For Shakapacker 9.0-9.3, script-based hooks remain reliable when the script includes a self-guard: ```ruby exit 0 if ENV["SHAKAPACKER_SKIP_PRECOMPILE_HOOK"] == "true" ``` `bin/dev` warns only when your hook cannot safely self-guard (for example, a direct command hook, or a script hook missing the guard line). This eliminates the need for manual coordination in your `Procfile.dev`. For example: **Before (manual coordination with sleep hacks):** ```procfile # Procfile.dev wp-server: sleep 15 && bundle exec rake react_on_rails:locale && bin/shakapacker --watch ``` **After (automatic coordination via bin/dev):** ```procfile # Procfile.dev wp-server: bin/shakapacker --watch ``` ```yaml # config/shakapacker.yml default: &default precompile_hook: 'bundle exec rake react_on_rails:locale' ``` > [!TIP] > **For HMR with SSR setups** (two webpack processes), use a script-based hook instead of a > direct command. Script-based hooks can include a self-guard that prevents duplicate execution > regardless of Shakapacker version. See the [i18n documentation](./i18n.md#internationalization) > for an example. #### Upgrading Existing Apps If your app currently uses a direct command hook, such as: ```yaml precompile_hook: 'bundle exec rake react_on_rails:locale' ``` migrate to a script-based hook: 1. Create `bin/shakapacker-precompile-hook`: ```ruby #!/usr/bin/env ruby # frozen_string_literal: true exit 0 if ENV["SHAKAPACKER_SKIP_PRECOMPILE_HOOK"] == "true" system("bundle", "exec", "rake", "react_on_rails:locale", exception: true) ``` 2. Make it executable: ```bash chmod +x bin/shakapacker-precompile-hook ``` 3. Update `config/shakapacker.yml`: ```yaml default: &default precompile_hook: 'bin/shakapacker-precompile-hook' ``` This upgrade path works for both Shakapacker 9.0-9.3 and 9.4.0+. See the [i18n documentation](./i18n.md#internationalization) for more details on configuring the precompile hook. ### Alternative: Extensible Precompile Pattern For projects with custom build requirements (ReScript, TypeScript compilation, multiple precompile tasks), consider handling precompile tasks directly in `bin/dev` instead of using the precompile_hook mechanism. This approach provides: - Single place to manage all precompile tasks - Direct Ruby API calls (faster, better version manager compatibility) - Clean Procfiles without embedded precompile logic See the [Extensible Precompile Pattern](./extensible-precompile-pattern.md) guide for full details. ### Service Dependency Checking `bin/dev` can automatically verify that required external services (like Redis, PostgreSQL, Elasticsearch) are running before starting your development server. This prevents cryptic error messages and provides clear instructions on how to start missing services. #### Configuration Create a `.dev-services.yml` file in your project root: ```yaml services: redis: check_command: 'redis-cli ping' expected_output: 'PONG' start_command: 'redis-server' install_hint: 'brew install redis (macOS) or apt-get install redis-server (Linux)' description: 'Redis (for caching and background jobs)' postgresql: check_command: 'pg_isready' expected_output: 'accepting connections' start_command: 'pg_ctl -D /usr/local/var/postgres start' install_hint: 'brew install postgresql (macOS)' description: 'PostgreSQL database' ``` A `.dev-services.yml.example` file with common service configurations is created when you run the React on Rails generator. #### Configuration Fields - **check_command** (required): Shell command to check if the service is running - **expected_output** (optional): String that must appear in the command output - **start_command** (optional): Command to start the service (shown in error messages) - **install_hint** (optional): How to install the service if not found - **description** (optional): Human-readable description of the service #### Behavior If `.dev-services.yml` exists, `bin/dev` will: 1. Check each configured service before starting 2. Show a success message if all services are running 3. Show helpful error messages with start commands if any service is missing 4. Exit before starting the Procfile if services are unavailable If `.dev-services.yml` doesn't exist, `bin/dev` works exactly as before (zero impact on existing installations). #### Example Output **When services are running:** ```text 🔍 Checking required services (.dev-services.yml)... ✓ redis - Redis (for caching and background jobs) ✓ postgresql - PostgreSQL database ✅ All services are running ``` **When services are missing:** ```text 🔍 Checking required services (.dev-services.yml)... ✗ redis - Redis (for caching and background jobs) ❌ Some services are not running Please start these services before running bin/dev: redis Redis (for caching and background jobs) To start: redis-server Not installed? brew install redis (macOS) or apt-get install redis-server (Linux) 💡 Tips: • Start services manually, then run bin/dev again • Or remove service from .dev-services.yml if not needed • Or add service to Procfile.dev to start automatically ``` ### Database Connectivity Check `bin/dev` automatically checks that your Rails database is accessible before starting the development server. This catches common issues like a missing database or a stopped database server, and provides clear error messages with specific commands to fix the problem. #### Behavior When `bin/dev` starts, it runs a quick Rails runner process to verify: 1. The database exists and accepts connections 2. Migrations are up to date (warns but does not block if pending) If the database is not accessible, `bin/dev` prints a clear error message and exits before starting any processes. **Note:** This check adds ~1-2 seconds to startup time as it spawns a Rails runner process. #### Disabling the Check There are three ways to disable the database check, listed by priority: 1. **CLI flag** (highest priority): ```bash bin/dev --skip-database-check ``` 2. **Environment variable**: ```bash SKIP_DATABASE_CHECK=true bin/dev ``` 3. **Configuration** in `config/initializers/react_on_rails.rb`: ```ruby ReactOnRails.configure do |config| config.check_database_on_dev_start = false end ``` **When to disable:** - Apps that don't use a database (API-only backends with external data stores) - Rapid restart workflows where the 1-2 second overhead matters (e.g., TDD with guard/watchman) - Projects where ActiveRecord is not loaded #### Security Note ⚠️ **IMPORTANT**: Commands in `.dev-services.yml` are executed during `bin/dev` startup without shell expansion for safety. However, you should still: - **Only add commands from trusted sources** - **Avoid shell metacharacters** (&&, ||, ;, |, $, etc.) - they won't work and indicate an anti-pattern - **Review changes carefully** if .dev-services.yml is committed to version control - **Consider adding to .gitignore** if it contains machine-specific paths or sensitive information **Recommended approach:** - Commit `.dev-services.yml.example` to version control (safe, documentation) - Add `.dev-services.yml` to `.gitignore` (developers copy from example) - This prevents accidental execution of untrusted commands from compromised dependencies **Execution order:** 1. Database connectivity check (unless disabled) 2. Service dependency checks (`.dev-services.yml`) 3. Precompile hook (if configured in `config/shakapacker.yml`) 4. Process manager starts processes from Procfile ## Installing a Process Manager ### Overmind (Recommended) Overmind provides easier debugging and better signal handling: ```bash # macOS brew install overmind # Linux # See: https://github.com/DarthSim/overmind#installation ``` ### Foreman (Alternative) Foreman is a widely-used Ruby-based process manager: ```bash # Install globally (NOT in Gemfile) gem install foreman ``` **Important:** Do NOT add Foreman to your `Gemfile`. Install it globally on your system. **Why not in Gemfile?** From [Foreman's documentation](https://github.com/ddollar/foreman/wiki/Don't-Bundle-Foreman): > Foreman is not a library, and should not affect the dependency tree of your application. Key reasons: - **Dependency conflicts**: Including Foreman in your Gemfile can create dependency conflicts that break other projects - **Security risk**: Loading Foreman as an application dependency creates an unnecessary security vulnerability vector - **Stability**: Foreman is mature and stable; bundling it could introduce bugs from unnecessary dependency updates - **Wrong abstraction**: Foreman is a system tool, not an application dependency Install Foreman globally: `gem install foreman` ## Alternative: Run Process Managers Directly You can also run process managers directly instead of using `bin/dev`: ```bash # With Overmind overmind start -f Procfile.dev # With Foreman foreman start -f Procfile.dev ``` > [!WARNING] > When running Foreman directly (not via `bin/dev`), Foreman injects its own `PORT` > environment variable (starting at 5000) into every subprocess. This causes > `${PORT:-3000}` in `Procfile.dev` to evaluate to Foreman's injected value rather > than the fallback 3000. > > To avoid this, set `PORT` explicitly in your shell or `.env` file before running > Foreman: > > ```sh > PORT=3000 foreman start -f Procfile.dev > # or add PORT=3000 to your .env file > ``` > > `bin/dev` handles this automatically — port detection runs before Foreman starts, > so `PORT` is always set correctly when Foreman launches. ## Customizing Your Setup Edit `Procfile.dev` in your project root to customize which processes run and their configuration. The default `Procfile.dev` includes: ```procfile rails: bundle exec rails s -p ${PORT:-3000} dev-server: bin/shakapacker-dev-server server-bundle: SERVER_BUNDLE_ONLY=true bin/shakapacker --watch ``` ## Running Multiple Worktrees Simultaneously If you use [git worktrees](https://git-scm.com/docs/git-worktree) to work on multiple branches in parallel, `bin/dev` automatically detects and avoids port conflicts — no configuration needed. When the default ports (3000 for Rails, 3035 for webpack-dev-server) are occupied, `bin/dev` scans for the next free pair and prints: ```text Default ports in use. Using Rails :3001, webpack :3036 ``` **To override ports manually**, create a `.env` file in the worktree (gitignored by default). A `.env.example` is generated by `rails g react_on_rails:install` as a reference: ```sh PORT=3001 SHAKAPACKER_DEV_SERVER_PORT=3036 ``` When `PORT` or `SHAKAPACKER_DEV_SERVER_PORT` are set, auto-detection is skipped entirely. ### Coding Agent / CI Integration When using coding agent tools that run multiple workspaces concurrently ([Conductor.build](https://conductor.build), OpenAI Codex, Quad Code, etc.), set `REACT_ON_RAILS_BASE_PORT` to derive all service ports from a single value. This eliminates the need for per-worktree `.env` files. > **Important:** Run each live `bin/dev` stack from a separate checkout, worktree, > or copied app directory. Starting two stacks from the exact same app path is > not supported because build tools such as ReScript and webpack watchers share > lock files and runtime artifacts within that directory. `bin/dev` assigns ports using fixed offsets from the base: | Service | Offset | Example (base=4000) | | ------------------- | ------ | ------------------- | | Rails server | +0 | 4000 | | Webpack dev server | +1 | 4001 | | Node renderer (Pro) | +2 | 4002 | | _(reserved)_ | +3–+9 | 4003–4009 | When a base port is detected, `bin/dev` also sets `RENDERER_PORT` and `REACT_RENDERER_URL` automatically so the Pro Node Renderer and Rails initializer agree on the port without any additional configuration. > **Heads up:** setting `RENDERER_PORT`, `RENDERER_URL`, or `REACT_RENDERER_URL` > in your environment activates the Pro renderer code path even in OSS apps — > in base-port mode this means `RENDERER_PORT` and `REACT_RENDERER_URL` will be > derived from the base and propagated to spawned processes. If you use > `RENDERER_PORT` in your environment for an unrelated purpose, rename your > variable to avoid the side effect. > > **Note:** Base-port mode derives the node renderer URL as > `http://localhost:<port>`. If you run the renderer in a Docker container or > on a remote host (e.g. `REACT_RENDERER_URL=http://renderer:3800`), do not use > base-port mode — set `REACT_RENDERER_URL` explicitly and use the > [manual worktree setup](#manual-worktree-port-setup-pro) instead. `bin/dev` > will warn at runtime if a pre-set `REACT_RENDERER_URL` is overridden. **Recognized environment variables** (checked in order): 1. `REACT_ON_RAILS_BASE_PORT` — the canonical base port variable; any tool can set this. 2. `CONDUCTOR_PORT` — set automatically by [Conductor.build](https://conductor.build). > **Note on `CONDUCTOR_PORT`:** React on Rails treats `CONDUCTOR_PORT` as the > **base** of a consecutive port block (Rails = base + 0, webpack = base + 1, > renderer = base + 2). This interpretation is not part of a public Conductor > API; treat `CONDUCTOR_PORT` support as best-effort until Conductor documents > the contract. If a future Conductor release redefines `CONDUCTOR_PORT` (for > example, to mean the Rails port itself), override by setting > `REACT_ON_RAILS_BASE_PORT` explicitly — it takes precedence and uses the > same derivation rules. **Priority chain:** base port > explicit per-service env vars (`PORT`, etc.) > auto-detect free ports. **Example: setting the base port in a tool's configuration:** ```sh # In your agent tool's workspace setup or .env REACT_ON_RAILS_BASE_PORT=4000 ``` #### Tool-specific setup [Conductor.build](https://conductor.build) sets `CONDUCTOR_PORT` for you — no configuration needed. Other tools (Claude Code CLI, [OpenAI Codex](https://github.com/openai/codex) CLI or app, plain `git worktree`, etc.) don't inject a port variable, so pick a different base per checkout using one of the options below. - **Per-worktree `.env` file** (tool-agnostic; gitignored by default): ```sh # .env at the root of each worktree REACT_ON_RAILS_BASE_PORT=4000 ``` - **Claude Code `.claude/settings.json`** (per-project, checked in or local): ```json { "env": { "REACT_ON_RAILS_BASE_PORT": "4000" } } ``` - **Shell export** (ad hoc, one session): ```sh REACT_ON_RAILS_BASE_PORT=4000 bin/dev ``` `bin/dev` reads the variable from the process environment regardless of how it was set, so mix and match whichever is most convenient for each tool. If you create a new checkout by copying an existing app directory while another `bin/dev` is running, the copy can inherit `tmp/pids/server.pid` or Overmind socket files from the original app. `bin/dev` now cleans those copied stale runtime files automatically on startup. If you launch processes outside `bin/dev`, clear those files yourself before booting the copied app. ### Manual Worktree Port Setup (Pro) If you use the [Node Renderer](./node-renderer/basics.md) (React on Rails Pro) with manual worktrees (no base port), you need to configure the renderer port in addition to the standard Rails and webpack ports: ```sh # .env in each worktree PORT=3001 SHAKAPACKER_DEV_SERVER_PORT=3036 RENDERER_PORT=3801 REACT_RENDERER_URL=http://localhost:3801 ``` The renderer port must match on both sides: `RENDERER_PORT` is read by the Node process and `REACT_RENDERER_URL` is read by the Rails-side Pro initializer. > **Note:** `bin/dev kill` only stops the renderer when `RENDERER_PORT` (or `REACT_RENDERER_URL`) > is exported in the current shell. From a fresh terminal that hasn't sourced your worktree's > `.env`, run e.g. `RENDERER_PORT=3801 bin/dev kill`, or source `.env` first. Otherwise the > renderer process will silently keep running. ## See Also - [HMR and Hot Reloading](./hmr-and-hot-reloading-with-the-webpack-dev-server.md) - [Foreman documentation](https://github.com/ddollar/foreman) - [Overmind documentation](https://github.com/DarthSim/overmind) ================================================================================ PAGE: https://reactonrails.com/docs/building-features/debugging SOURCE: docs/oss/building-features/debugging.md ================================================================================ # Debugging React on Rails This guide covers common debugging workflows for React on Rails applications, focusing on server-side rendering issues, hydration mismatches, and tools for diagnosing problems. ## Configuration for Debugging React on Rails provides several configuration options that help with debugging. Enable them in development: ```ruby # config/initializers/react_on_rails.rb ReactOnRails.configure do |config| # Detailed logging for server rendering, including stack traces for # setTimeout/setInterval calls config.trace = Rails.env.development? # Log server rendering output to Rails.logger.info config.logging_on_server = true # Replay server-side console.log messages in the browser console config.replay_console = true # Raise exceptions when server rendering fails (instead of rendering # an error message in the HTML) config.raise_on_prerender_error = Rails.env.development? end ``` See the [Configuration Reference](../configuration/README.md) for full documentation on these options. ## Debugging Server-Side Rendering ### Reading Server Rendering Output When `logging_on_server` is `true` (the default), server rendering messages appear in your Rails log. Check `log/development.log` or your terminal output for lines related to React on Rails rendering. When `replay_console` is `true` (the default), any `console.log`, `console.warn`, or `console.error` calls from your server-rendered JavaScript will replay in the browser's developer console. This is one of the most useful tools for understanding what your components are doing during server rendering. ### Common SSR Errors **`ReferenceError: window is not defined`** Your component accesses `window`, `document`, or another browser API during server rendering. Guard with an environment check or move the code into `useEffect`: ```javascript // Guard approach const isClient = typeof window !== 'undefined'; // useEffect approach (preferred) useEffect(() => { // Browser-only code here }, []); ``` **`TypeError: Cannot read properties of undefined`** Often caused by accessing props that are `nil` in Ruby but become `undefined` in JavaScript. Check your prop serialization: ```ruby # Ensure props are present @props = { user: @user&.as_json || {}, items: @items || [] } ``` **Timer callbacks silently dropped during SSR** During ExecJS rendering, React on Rails stubs `setTimeout`, `setInterval`, and `clearTimeout` as no-ops, so callbacks never run. `clearInterval` is **not** stubbed by React on Rails. Behavior depends on runtime: `mini_racer` may raise a `ReferenceError`, while Node-based runtimes provide `clearInterval`. With `config.trace = true`, calls to stubbed timer functions emit `console.error` warnings with stack traces. Those warnings replay in browser devtools via `replay_console`, and also appear in Rails logs when `logging_on_server = true`. See the [ExecJS Limitations](../core-concepts/execjs-limitations.md) guide for workarounds. ### Using `trace` Mode When `config.trace` is enabled, React on Rails logs additional details about the server rendering process, including stack traces when `setTimeout` or `setInterval` are called during ExecJS rendering. This helps identify which library or component is making unsupported calls. ## Debugging Hydration Mismatches Hydration mismatches occur when the server-rendered HTML differs from what React generates on the client. React will warn in the browser console: ```text Warning: Text content did not match. Server: "March 21" Client: "March 22" ``` ### Common Causes **Time-dependent rendering:** Server and client render at different times, producing different date/time strings. ```javascript // Problem: different output on server vs client const now = new Date().toLocaleDateString(); // Fix: pass the timestamp as a prop from Rails // In controller: @props = { timestamp: Time.current.iso8601 } ``` **Random values:** `Math.random()` or UUID generation produces different values between renders. ```javascript // Problem: different ID on server vs client const id = `item-${Math.random()}`; // Fix: use a deterministic ID const id = `item-${props.itemId}`; ``` **Browser-only code affecting initial render:** Code that checks `window` dimensions or feature detection may produce different initial output. ```javascript // Problem: server renders one thing, client another const isMobile = typeof window !== 'undefined' && window.innerWidth < 768; // Fix: defer to useEffect so the initial render matches the server const [isMobile, setIsMobile] = useState(false); useEffect(() => { setIsMobile(window.innerWidth < 768); }, []); ``` ### Inspecting Server-Rendered HTML To see exactly what the server rendered, view the page source (not the DOM inspector, which shows the hydrated DOM). In your browser: 1. Navigate to the page 2. Right-click and select **View Page Source** (or use `Ctrl+U` / `Cmd+U`) 3. Search for your component's container div (e.g., `id="MyComponent-react-component-<uuid>"` when `random_dom_id` is enabled, which is the default) The HTML inside that div is what the server produced. Compare it with what React expects to render on the client. You can also add `console.log` statements in your component to see the props and state during both renders: ```javascript function MyComponent(props) { console.log('Rendering MyComponent with props:', props); // ... } ``` With `replay_console` enabled, the server-side log will appear in the browser console alongside the client-side log, making it easy to compare. ## Where to Find Logs ### Rails Server Logs Server rendering output, including errors and console replays, appears in: - **Terminal:** where you run `rails server` or `bin/dev` - **Log file:** `log/development.log` (or `log/test.log` for test environment) ### Webpack/Rspack Build Logs Build errors and warnings appear in: - **Terminal:** where webpack-dev-server or `bin/dev` runs - **Browser console:** webpack overlay may show compilation errors To run diagnostics on your React on Rails setup (checks configuration, file existence, and common issues): ```bash bundle exec rake react_on_rails:doctor ``` ### Browser Console The browser developer console shows: - Replayed server-side `console.log` messages (when `replay_console` is enabled) - React hydration warnings - Client-side JavaScript errors - Component registration status ### Checking Component Registration To verify that your components are registered correctly: ```javascript // In the browser console console.log(ReactOnRails.registeredComponents()); ``` This returns a map of all components that have been registered with `ReactOnRails.register()`. If your component is missing, check that the registration file is included in your webpack entry point. ## Debugging Webpack Configuration If components aren't loading or you suspect bundling issues: 1. Check that your webpack entry points include the registration files 2. Verify the manifest file exists at the expected path (check `public_output_path` in `config/shakapacker.yml` — defaults to `public/packs/`) 3. Confirm the server bundle is generated in your `server_bundle_output_path` (defaults to `ssr-generated/`): ```bash # List the server bundle output directory (filename set via config.server_bundle_js_file) ls ssr-generated/ # Check that the client manifest exists and contains your client bundles cat public/packs/manifest.json | grep "application" ``` ### Exporting the Fully-Resolved Bundler Configuration When something is wrong with the build itself — a loader not matching, a plugin missing in production, dev/prod divergence — it helps to inspect the **fully-resolved** webpack or rspack config, including all of Shakapacker's defaults. Shakapacker ships a `--doctor` mode that dumps annotated YAML for every relevant build. > [!NOTE] > This is separate from `bundle exec rake react_on_rails:doctor`, which diagnoses React on Rails configuration rather than the bundler config itself. ```bash # Shakapacker 9.6+ canonical binstub bin/shakapacker-config --doctor # Older Shakapacker versions / projects with the legacy binstub bin/export-bundler-config --doctor ``` Both commands are thin shims over the same exporter and produce the same output: annotated YAML files in `shakapacker-config-exports/` (created in your project root) covering development (with and without HMR) and production, split into separate client and server bundle files. The YAML is annotated with inline documentation so you can see, for each loader / plugin / resolve rule, where it came from. > [!TIP] > Add `shakapacker-config-exports/` to your `.gitignore` — these files are intended for local inspection, not version control. Two common uses: - **Troubleshooting:** diff two exports (before/after an upgrade, or against a known-working app) to find configuration drift. - **AI-assisted analysis:** paste the annotated YAML into an AI tool to ask questions like "why is this plugin in server but not client?" — the output format is designed to be readable by both humans and LLMs. For the full set of flags (`--build`, `--init`, `--validate`, `--save-dir`, etc.) and the build-config-file workflow, see the [Shakapacker Configuration Diff Tool docs](https://shakapacker.com/docs/config-diff/). ## Pro Node Renderer Debugging If you're using the React on Rails Pro Node Renderer, the renderer process has its own logs. The log level is controlled by the `RENDERER_LOG_LEVEL` environment variable. See the [Node Renderer Basics](./node-renderer/basics.md) for configuration details. ## Additional Resources - [Troubleshooting Guide](../deployment/troubleshooting.md) — common installation, build, and runtime issues - [ExecJS Limitations](../core-concepts/execjs-limitations.md) — timer, async, and environment constraints - [Client vs. Server Rendering](../core-concepts/client-vs-server-rendering.md) — when and how to use SSR - [Configuration Reference](../configuration/README.md) — all configuration options - [Testing Configuration](./testing-configuration.md) — setting up test environments ================================================================================ PAGE: https://reactonrails.com/docs/building-features/debugging-hydration-mismatches SOURCE: docs/oss/building-features/debugging-hydration-mismatches.md ================================================================================ # Debugging Hydration Mismatches in Rails A hydration mismatch happens when the HTML your Rails server rendered for a React component does not match what React renders on the client during hydration. React 18+ recovers automatically by throwing away the server HTML and re-rendering on the client — which means the page still "works," but you pay for the server render twice, the UI can visibly flicker, and the underlying bug stays hidden unless you are watching for it. Rails apps hit a set of systematic causes that JavaScript-only frameworks rarely see, because the server render happens in a Rails request context (time zones, `current_user`, I18n, CSRF, asset hosts) while the client render does not. This guide catalogs those causes, the fix patterns, and how to observe hydration errors with React on Rails' root error callbacks. ## Observing hydration errors ### Development default When `Rails.env.development?`, React on Rails automatically logs every recoverable hydration error with the component name, the DOM id, the component stack (when React provides one), and a link to this guide: ```text [ReactOnRails] Recoverable hydration error in component "MyComponent" (dom id: "MyComponent-react-component-0"). ... Component stack: at MyComponent ``` React's default error reporting is preserved: the error itself is still reported once via `reportError` (falling back to `console.error`), so dev overlays and other window-`'error'`-based tooling keep working. The branded line is supplemental context. On React on Rails Pro RSC hydration paths, Pro's internal handler already reports the error, so only the supplemental line is added — each error is reported exactly once either way. No setup is required. The default logger runs in addition to any callback you register. ### Registering root error callbacks (React 19) React's root APIs accept error callbacks, and React on Rails exposes them globally through `ReactOnRails.setOptions`. They apply to every React root that React on Rails creates (`hydrateRoot` and `createRoot`): ```js // In your client bundle entry, before your components render // (typically next to your ReactOnRails.register call). import ReactOnRails from 'react-on-rails/client'; ReactOnRails.setOptions({ rootErrorHandlers: { // React recovered from an error (most commonly a hydration mismatch). React 18+. onRecoverableError: (error, errorInfo, context) => { const rootContext = { componentName: context.componentName ?? 'unknown', domNodeId: context.domNodeId ?? 'unknown', }; myErrorReporter.report(error, { level: 'warning', ...rootContext, }); }, // An error boundary caught an error. React 19+. onCaughtError: (error, errorInfo, context) => { const rootContext = { componentName: context.componentName ?? 'unknown', domNodeId: context.domNodeId ?? 'unknown', }; myErrorReporter.report(error, { level: 'error', handled: true, ...rootContext }); }, // An error was NOT caught by any error boundary. React 19+. onUncaughtError: (error, errorInfo, context) => { const rootContext = { componentName: context.componentName ?? 'unknown', domNodeId: context.domNodeId ?? 'unknown', }; myErrorReporter.report(error, { level: 'fatal', handled: false, ...rootContext }); }, }, }); ``` Each callback receives React's original `(error, errorInfo)` arguments plus a `context` object that may include the React on Rails `componentName` and `domNodeId` of the affected root. Treat both fields as optional because lower-level render paths or custom mount nodes may not supply one. Notes: - **Register before rendering.** Each root captures the callbacks registered when it is created; register them in the same pack file where you call `ReactOnRails.register`. - **Partial updates merge per key.** A later `setOptions({ rootErrorHandlers: { onCaughtError } })` keeps a previously registered `onRecoverableError`/`onUncaughtError`. Pass an explicit `undefined` for a key to clear just that callback; `ReactOnRails.resetOptions()` clears all of them. - **React version support:** `onRecoverableError` requires React 18+; `onCaughtError`/`onUncaughtError` require React 19. On unsupported React versions, React on Rails still stores the registered handlers so they start working after a React upgrade, but the current runtime cannot invoke them and logs a one-time `console.warn`. - **React on Rails Pro:** on RSC/streaming hydration paths, Pro installs an internal `onRecoverableError` for its own bookkeeping. Your callback is chained after it — both always run, and Pro's internal control-flow signals (such as the `RSCRoute` `ssr: false` bailout) are filtered out of both so they never reach your error reporter. The Pro RSC hydration chain already calls `reportError`/`console.error` before your callback, so do not call `reportError(error)` again in that callback on RSC hydrate roots. - **Development default scope:** the branded `[ReactOnRails]` guide-link log is only for recoverable hydration errors. `onCaughtError` and `onUncaughtError` still receive the enriched context, but React on Rails does not add a supplemental guide log for those non-hydration paths. - **Default reporting for `onRecoverableError`:** registering this callback replaces React's own default `reportError`/`console.error` for that root (standard React semantics). React on Rails re-emits recoverable hydration errors in development so dev overlays keep working on hydrated roots; client-only `createRoot` roots use the standard React callback semantics, so your callback is the reporter. If you rely on separate `window.onerror`-based monitoring, call `reportError(error)` inside your callback or configure your monitoring SDK to capture `window.reportError`. Exception: on React on Rails Pro RSC hydrate roots, Pro already calls `reportError` before your callback, so calling it again there will double-report. - **Per-component overrides** are not currently supported; the global registration above is the blessed route. ### Sentry example (and avoiding double reporting) ```js import * as Sentry from '@sentry/react'; import ReactOnRails from 'react-on-rails/client'; ReactOnRails.setOptions({ rootErrorHandlers: { onRecoverableError: (error, errorInfo, context) => { Sentry.captureException(error, { level: 'warning', tags: { ror_component: context.componentName ?? 'unknown', ror_dom_id: context.domNodeId ?? 'unknown', }, }); }, onUncaughtError: (error, errorInfo, context) => { Sentry.captureException(error, { tags: { ror_component: context.componentName ?? 'unknown', ror_dom_id: context.domNodeId ?? 'unknown', }, }); }, }, }); ``` **Precedence:** an error is routed to exactly one of React's callbacks. If an error boundary catches it, it reaches `onCaughtError` (not `onUncaughtError`); otherwise it reaches `onUncaughtError`. But error boundaries themselves (like `Sentry.ErrorBoundary` or a `componentDidCatch` that reports) run **in addition to** `onCaughtError` — so if you report from both your boundary and `onCaughtError`, the same error is reported twice. Pick one layer: either report from boundaries and leave `onCaughtError` for logging/metrics, or report from `onCaughtError` and keep boundaries presentational. Similarly, `window.onerror`-based reporters may also see uncaught errors that React rethrows; deduplicate by error identity if you wire both. ## Rails-specific causes and fixes ### 1. Time, dates, and time zones (`Time.current`, `l(...)`, relative times) **Symptom:** timestamps, "x minutes ago" labels, or date-dependent UI differ between the server HTML and the client render. **Why:** the server renders with the Rails process time (and `Time.zone`), while the client renders with the browser clock and locale — even a one-second delta changes "rendered at" strings. Passing `Time.current.to_s` as a prop is fine; _formatting the current time independently on both sides_ is not. ```erb <%# BAD: the view bakes a server-formatted "now" next to a component that renders its own clock %> <%= react_component("OrderSummary", props: { renderedAt: Time.current.strftime("%H:%M:%S") }, prerender: true) %> ``` **Fixes:** - Pass a stable value (epoch milliseconds or ISO8601 string) as a prop and format it the same way on both sides: ```erb <%= react_component("OrderSummary", props: { createdAtMs: @order.created_at.to_i * 1000 }, prerender: true) %> ``` - For values that _must_ differ (live clocks, relative "ago" labels), render them client-side only — initialize state to the server-safe value and update in `useEffect`: ```jsx function TimeAgo({ createdAtMs }) { const [label, setLabel] = useState(null); // server renders nothing dynamic useEffect(() => setLabel(formatTimeAgo(createdAtMs)), [createdAtMs]); return <span suppressHydrationWarning>{label ?? '…'}</span>; } ``` - `suppressHydrationWarning` on the single text node that legitimately differs is acceptable for things like timestamps. It only suppresses one element's text/attribute warning — do not wrap whole trees in it to silence a real bug. ### 2. `current_user`-conditional ERB around components **Symptom:** components hydrate fine logged out but mismatch (or render the wrong UI) logged in, or vice versa. **Why:** ERB that conditionally wraps or alters a server-rendered component bakes the login state into the server HTML, but the client bundle renders from props alone: ```erb <%# BAD: the server HTML contains the admin toolbar, the client render doesn't know about it %> <% if current_user&.admin? %> <div class="admin-frame"><%= react_component("Dashboard", prerender: true) %></div> <% else %> <%= react_component("Dashboard", prerender: true) %> <% end %> ``` **Fix — props, not ERB:** pass the user state as props and branch inside the component, so server and client render from the same inputs: ```erb <%= react_component("Dashboard", props: { currentUser: { admin: current_user&.admin? || false, name: current_user&.name } }, prerender: true) %> ``` ### 3. I18n locale drift **Symptom:** translated strings mismatch — the server renders one language, the client another. **Why:** the server render uses `I18n.locale` from the Rails request, while the client may initialize its JS i18n library from `navigator.language`, a cookie, or a default that disagrees with Rails. **Fix:** drive the client locale from the same source as the server. React on Rails already passes `i18nLocale` and `i18nDefaultLocale` in the `railsContext` to every render function on both server and client: ```jsx const MyApp = (props, railsContext) => { i18n.locale = railsContext.i18nLocale; // same value on server and client return () => <App {...props} />; }; ``` See the [Internationalization guide](./i18n.md) for generating translation files. ### 4. CSRF-token-dependent props and markup **Symptom:** forms or fetch wrappers that embed the CSRF token mismatch on every page load. **Why:** the token from `csrf_meta_tags` is per-session/request. If the server render embeds one token into component HTML (e.g., a hidden input rendered from a prop) and the client reads a fresh one from the meta tag, the values differ. With Rails action caching, the cached server HTML can even contain another user's masked token. **Fix:** never render the token during SSR. Read it client-side with React on Rails' helper when you actually submit: ```js import ReactOnRails from 'react-on-rails/client'; fetch('/orders', { method: 'POST', headers: ReactOnRails.authenticityHeaders({ 'Content-Type': 'application/json' }), body: JSON.stringify(payload), }); ``` If a hidden field is unavoidable, populate it in `useEffect` (client-only) instead of from a server-rendered prop. ### 5. Asset hosts and URL helpers **Symptom:** `<img>`/`<link>` attribute mismatches where the server URL has a CDN host (or different protocol) and the client-computed URL does not. **Why:** `config.asset_host`, `default_url_options`, and request-dependent helpers (`request.base_url`) apply during the Rails-side render, while client code building URLs from relative paths or `window.location` produces different strings. **Fixes:** - Compute asset URLs once in Rails and pass them as props (`image_url`, not client-side string building). The [images guide](./images.md) covers webpack-side asset imports that produce identical URLs in both bundles. - Avoid `window.location`-derived URLs during initial render; if needed, move them to `useEffect`. ### 6. Anything nondeterministic in render `Math.random()`, `Date.now()`, `crypto.randomUUID()`, or unstable iteration order used during render guarantees a mismatch. Generate the value once on the server, pass it as a prop, or compute it in `useEffect`. For stable generated IDs across server and client, use React's `useId()` — React on Rails Pro's streaming SSR already coordinates the required `identifierPrefix` between server and client for multi-root pages. ## General fix patterns | Pattern | When to use | | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Props, not ERB** | Any request-dependent value (user, locale, URLs, feature flags): pass it into the component instead of branching in the view around server-rendered HTML. | | **Render client-side only** | Values that genuinely differ per client (clocks, viewport, `window`-derived state): initialize state server-safe, fill in via `useEffect`. | | **`suppressHydrationWarning`** | A single text node/attribute that legitimately differs (e.g. a timestamp). Last resort, narrowest possible scope — it hides the warning, not the double render. | | **`prerender: false`** | Components that are inherently client-only; skip SSR entirely rather than fighting mismatches. | ## Verifying a fix 1. In development, load the page and confirm the `[ReactOnRails] Recoverable hydration error...` message no longer appears. 2. Keep an `onRecoverableError` callback wired to your error reporter in production — hydration regressions are otherwise invisible (React recovers silently). 3. For ongoing protection, assert in an E2E test that no recoverable events fire on your critical pages (see `react_on_rails/spec/dummy/e2e/playwright/e2e/react_on_rails/root_error_callbacks.spec.js` in the React on Rails repo for a working example). ## Related documentation - [Client vs. Server Rendering](../core-concepts/client-vs-server-rendering.md) - [React Server Rendering](../core-concepts/react-server-rendering.md) - [Debugging React on Rails](./debugging.md) - [Internationalization](./i18n.md) - [React `hydrateRoot` error callback options](https://react.dev/reference/react-dom/client/hydrateRoot) ================================================================================ PAGE: https://reactonrails.com/docs/building-features/performance-tracks-and-profiling SOURCE: docs/oss/building-features/performance-tracks-and-profiling.md ================================================================================ # React Performance Tracks and Profiling React on Rails apps have three broad performance questions that look similar but need different tool clusters: 1. **What did the browser do?** Use Chrome DevTools Performance recordings with [React Performance Tracks](https://react.dev/reference/dev-tools/react-performance-tracks). 2. **What did the React on Rails Pro Node Renderer do?** Use the Node inspector and the renderer tracing integrations. 3. **What did real users experience?** Use field metrics such as [Web Vitals and Real User Monitoring](./web-vitals-and-rum.md). React Performance Tracks are most useful when you can reproduce a slow interaction locally. They show React scheduler work, component render and effect durations, and, for React Server Components in development builds, server request and Server Component timing. They do not replace production telemetry, but they make the local trace much easier to read than a JavaScript stack alone. ## Choose the right profiling path | Symptom | Start with | Why | | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | Slow click, navigation, or hydration in the browser | Chrome DevTools Performance recording with React Performance Tracks | Shows React scheduler priority, component render cost, effects, network, layout, and paint on one timeline. | | A specific component renders too often | React Components track, React DevTools, and optional `<Profiler>` boundaries | Shows component render/effect duration and, in development builds, prop changes for selected entries. | | Slow server rendering in the Pro Node Renderer | [Profiling Server-Side Rendering Code](../../pro/profiling-server-side-rendering-code.md) | Attaches Chrome DevTools to the Node process and records CPU work such as bundle upload, VM setup, and render calls. | | Renderer breakpoints or request-by-request debugging | [Node Renderer Debugging](./node-renderer/debugging.md) | Uses `--inspect`, renderer logs, and focused restarts for breakpoint debugging. | | Production SSR latency or error correlation | [Error Reporting and Tracing](./node-renderer/error-reporting-and-tracing.md) and [OpenTelemetry](../../pro/node-renderer.md#observability-with-opentelemetry) | Captures spans and errors from live requests without attaching an inspector to production traffic. | | Memory growth in the renderer | [Memory Leaks](../../pro/js-memory-leaks.md) | Uses heap snapshots and worker restart strategy instead of CPU flamegraphs. | ## Record React Performance Tracks Use this workflow for browser-side interaction, hydration, Suspense, and RSC timing investigations. 1. Run the app in development with React 19.2 or newer when your app supports that React line. For React on Rails Pro RSC apps, keep the React version supported by the current RSC guide and release notes; do not upgrade a generated RSC app only to capture Performance Tracks. 2. Install and enable the React Developer Tools browser extension when you want the Components track to include the full component tree. 3. Open Chrome DevTools, then open the **Performance** panel. 4. Start recording, reload the page or perform the slow interaction, then stop recording. 5. Inspect the React tracks alongside the normal browser tracks for network, JavaScript, layout, paint, and user timing. React enables Performance Tracks automatically in development builds. In profiling builds, the Scheduler track is enabled by default. The Components track is limited to subtrees wrapped in `<Profiler>` unless the React DevTools extension is enabled. React's Server Components and Server Requests tracks are development-build only. ## Read the React tracks The **Scheduler** track explains the priority and phase of React work: - **Blocking** work usually comes from direct user interactions. - **Transition** work comes from non-blocking updates scheduled with `startTransition`. - **Suspense** work shows fallback and reveal timing. - **Idle** work runs only after higher-priority work is clear. Within those lanes, look for update, render, commit, and remaining-effect spans. A render followed by repeated updates or long effects often points to avoidable state changes, expensive effects, or missing memoization boundaries. The **Components** track shows component render and effect durations as flamegraphs. Use it to answer: - Which component subtree is expensive? - Did the cost happen during render, layout effects, or passive effects? - Did a selected component receive changed props that explain the render? The **Server** tracks are relevant when you use React Server Components in development. The Server Requests track visualizes async work that flows into Server Components, and the Server Components tracks show the component work and awaited Promises. Treat these as React-level RSC timing: they do not include every Rails controller, Fastify, network, or renderer worker cost. ## Keep names readable Profiles are only useful when component and function names survive the build. - Prefer named functions and named component exports over anonymous inline components. - Set `displayName` on components wrapped by helpers such as `memo` or `forwardRef` when the wrapper hides the useful name. - Use a development build first. It gives the clearest component names and enables the full React development instrumentation. - For a production-like profiling build, alias `react-dom/client` to `react-dom/profiling` at build time as described in the [React Performance Tracks docs](https://react.dev/reference/dev-tools/react-performance-tracks#using-profiling-builds), and preserve function/class names in that temporary build if minification erases useful labels. For Terser-style minifiers, that means profiling-only `keep_fnames` and `keep_classnames` settings or the equivalent setting in your bundler/minifier. Do not turn those knobs on blindly for production, since they can increase bundle size and reduce minification. ## Correlate browser and server work For a local SSR/RSC investigation, collect one browser trace and one renderer trace for the same scenario: 1. Record the browser interaction with React Performance Tracks. 2. Record the renderer process with the [SSR profiling workflow](../../pro/profiling-server-side-rendering-code.md). 3. Compare timestamps, request logs, and component names. The browser trace shows hydration, interaction, Suspense, and paint timing. The renderer trace shows CPU spent before HTML or RSC payloads reach the browser. If your server-rendered code needs its own named spans in a renderer CPU profile, add temporary User Timing marks around the code under investigation: ```js performance.mark('ror:ssr:ProductSummary:start'); try { // Render or data preparation work under investigation. } finally { performance.mark('ror:ssr:ProductSummary:end'); performance.measure('ror:ssr:ProductSummary', 'ror:ssr:ProductSummary:start', 'ror:ssr:ProductSummary:end'); } ``` In the Pro Node Renderer VM, `performance` is available when `supportModules: true`; otherwise inject it with `additionalContext`. See [Runtime Globals for SSR and RSC](./node-renderer/js-configuration.md#runtime-globals-for-ssr-and-rsc). ## Use production telemetry for production questions Do not attach `--inspect` to production traffic as your primary profiling strategy. It slows the renderer and changes the workload you are trying to measure. Use production-safe instrumentation instead: - [Web Vitals and RUM](./web-vitals-and-rum.md) for user-visible browser outcomes such as LCP, INP, CLS, FCP, and TTFB. - [OpenTelemetry](../../pro/node-renderer.md#observability-with-opentelemetry) for SSR request spans from the Pro Node Renderer. - [Error Reporting and Tracing](./node-renderer/error-reporting-and-tracing.md) for Sentry, Honeybadger, and custom tracing integrations. - [Profiling Server-Side Rendering Code](../../pro/profiling-server-side-rendering-code.md) for short, local CPU profiling sessions when you can reproduce the slow path. ## Measuring an RSC conversion with a paired A/B When you convert a page to React Server Components, the only honest way to know whether you regressed user-visible performance is a paired, throttled A/B comparison of the page before and after the conversion. The profiling workflows above tell you _where_ time goes inside one build; this workflow tells you whether the conversion moved the numbers that users feel. ### Why paired and throttled is mandatory An unthrottled load on `localhost` will hide the regression almost entirely. Local hardware is fast and the network is effectively free, so the page is bound by main-thread and loopback timing that no real user shares. The regression only surfaces under Lighthouse mobile throttling, which models a phone on a slow connection: - **Slow 4G** network throttling. - **4x CPU** slowdown. Sampling matters as much as throttling. A single server measured sequentially — control runs, then experiment runs — is noise-dominated: background load, thermal state, and JIT warmup drift between the two runs and swamp the effect you are trying to measure. Sample the two variants **simultaneously (paired)** instead, so each control sample shares its environment with the experiment sample it is compared against. ### Setup Stand up two production-mode servers serving identical data and config, side by side: | Variant | Build | | -------------- | ---------------------------------------------------------------- | | **Control** | Pre-RSC baseline (your default branch before the RSC conversion) | | **Experiment** | RSC branch | Then: 1. Build both variants in production mode on the same data and configuration. 2. Drive both with the **same throttled Lighthouse config** (Slow 4G + 4x CPU). 3. Collect **10 to 15 paired samples** per page so the comparison has reliable power. Six paired samples is only a weak smoke-test floor: with the two-sided exact Wilcoxon signed-rank test, you need unanimous agreement across all six pairs to reach p < 0.05 — one dissenting sample pushes you above it. 4. Report a **Wilcoxon signed-rank p-value**; treat **p < 0.05** as strong directional evidence of a real shift when the paired samples consistently move in the same direction. We use ShakaPerf for this — it brings up the twin production-local servers and runs the paired comparison with `shaka-perf compare --categories perf`. The methodology is what matters, not the tool: any harness that runs two production builds side by side under identical mobile throttling with paired sampling and a significance test gives you the same signal. ### Reading the result Do not just stare at LCP. Decompose the metrics, because the fix depends on which ones moved: | Signal | Likely cause | Where to look | | ----------------------------------------- | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | **FCP and TBT both high** | JS-bundle / hydration bound — the `'use client'` tail is shipping and executing too much | Reduce client boundaries. See [Chunk Contamination](../migrating/rsc-troubleshooting.md#chunk-contamination). | | **LCP high while FCP is also high** | LCP is gated on late FCP; the largest element may be healthy but cannot paint yet | Fix FCP first by reducing client JS boundaries; LCP usually follows. | | **LCP high while FCP is healthy** | The LCP element or its asset delivery is slow | Inspect the hero/image resource, asset host, CDN cache headers, preload/fetch priority, and responsive image selection. | | **INP high in RUM or interaction traces** | Long client tasks delay input responsiveness, often from the same JS tail that raises TBT | Follow the FCP/TBT path, then verify the affected interactions with RUM or browser traces. | | **CLS and Lighthouse score** | Corroboration | Use as secondary confirmation, not as the primary signal. | A high FCP that drags LCP behind it is the common RSC-conversion pattern: the largest element is healthy, it simply cannot paint until the late first render lets it. Fix FCP first and LCP usually follows. ### Iterate Treat each fix as one controlled change: 1. Apply one fix. 2. Rebuild the **experiment only** — the control stays fixed as your baseline. 3. Re-measure the paired comparison. 4. Repeat. Because the control never moves, every change has a defensible before/after instead of a number you have to argue about. ### Case study: HiChee home and FAQ A real RSC conversion of the HiChee `home` and `faq` pages, measured with a paired ShakaPerf A/B under Slow 4G + 4x CPU (p ≈ 0.03), shows the initial regression state that triggered investigation. These are not final shipped metrics; add your own post-fix rows after each client-boundary or CSS-delivery change. | Page | FCP | LCP | TBT | Lighthouse | | -------- | ------------ | ------------ | ---------------- | ---------------- | | **Home** | 2.0s → 9.3s | 2.1s → 21.1s | 0 → 928ms | 79 → 8.5 | | **FAQ** | 2.0s → 15.9s | 2.2s → 20.5s | — (not captured) | — (not captured) | The FAQ run did not capture TBT or Lighthouse score. The captured signals pointed straight at the `'use client'` JS tail: FCP regressed on both pages, Home TBT blew up, and LCP was gated on late FCP because first render arrived far too late, not because the hero element itself was slow. A CSS broadcast fix (react_on_rails_rsc [#108](https://github.com/shakacode/react_on_rails_rsc/pull/108) → [#110](https://github.com/shakacode/react_on_rails_rsc/pull/110) / [#113](https://github.com/shakacode/react_on_rails_rsc/pull/113), shipped in `react-on-rails-rsc` 19.2.0-rc.3) was correct, but it was a **second-order** effect. The dominant driver was the client JS tail, not CSS delivery. Chasing the CSS fix first would have spent effort without moving the metrics that mattered. The lesson to take from this: **measure paired and throttled, then decompose FCP/TBT versus LCP before choosing a fix.** A related second-order CSS concern worth knowing about is the end-of-`<head>` rsc-css precedence trap described in [CSS and styling for RSC](../../pro/react-server-components/css-and-styling.md#rsc-stylesheet-cascade-order-end-of-head-precedence) — but confirm with the decomposition that CSS delivery is actually on your critical path before you spend time there. ================================================================================ PAGE: https://reactonrails.com/docs/building-features/web-vitals-and-rum SOURCE: docs/oss/building-features/web-vitals-and-rum.md ================================================================================ # Web Vitals and Real User Monitoring (RUM) React on Rails instruments **server-side** render performance — the repo's `benchmarks/` suite feeds a Bencher-based regression dashboard, and [Performance Benchmarks](../core-concepts/performance-benchmarks.md) covers ExecJS vs Node Renderer throughput. What that does not tell you is how your app performs **for real users in real browsers**: Largest Contentful Paint (LCP), Cumulative Layout Shift (CLS), Interaction to Next Paint (INP), Time to First Byte (TTFB), and First Contentful Paint (FCP). This page closes that loop with a **first-party** Real User Monitoring setup: the browser collects Web Vitals with the [`web-vitals`](https://github.com/GoogleChrome/web-vitals) library and beacons them to **your own Rails endpoint** — no third-party analytics vendor, no Vercel, no extra SaaS bill, and the data never leaves your app (privacy/GDPR friendly). For comparison: Next.js ships [`useReportWebVitals`](https://nextjs.org/docs/app/api-reference/functions/use-report-web-vitals), a thin hook over the same `web-vitals` library, and pairs it with Vercel Speed Insights for turnkey field RUM — a path that effectively assumes you deploy on Vercel and send your traffic data there. On Rails, the equivalent is just another controller action: POST the vitals to your app and aggregate them with ActiveRecord or your existing APM. > **Scope note:** This page covers wiring the framework-agnostic `web-vitals` > metrics. Framework-level hydration-timing instrumentation (`performance.mark` > entries emitted from the React on Rails client runtime — "time to hydrate", > "first interaction after hydration") is a planned follow-up, tracked in > [issue #3877](https://github.com/shakacode/react_on_rails/issues/3877). It has > not shipped yet; nothing on this page depends on it. ## How the pieces fit 1. **Client**: a small script in your client bundle subscribes to the five Core Web Vitals via `web-vitals`, queues them, and flushes the queue with `navigator.sendBeacon` when the page is hidden or unloaded. 2. **Sampling**: only a configurable fraction of page views report (default below: 10%), so high-traffic apps don't write a row per page view. 3. **Server**: a Rails route + controller accepts the JSON beacon, validates it with strong parameters, and stores it (or forwards it to your APM). 4. **Aggregation**: you query percentiles (p75 is the Core Web Vitals threshold standard) from your own database. ## Client: collecting and beaconing vitals Add the [`web-vitals`](https://github.com/GoogleChrome/web-vitals) package: ```bash npm install web-vitals # or: yarn add web-vitals # or: pnpm add web-vitals ``` Then add the following to a Shakapacker entry — either a dedicated pack or your existing client bundle entry. It is intentionally plain JavaScript with no React on Rails API dependency, so it works in any client bundle: ```js // app/javascript/packs/web-vitals-reporter.js // (or import it from your existing client bundle entry) import { onCLS, onFCP, onINP, onLCP, onTTFB } from 'web-vitals'; const VITALS_ENDPOINT = '/web_vitals'; // Report only a fraction of page views. Decide once per page load so a sampled // page view reports its full set of metrics (you can also read the rate from a // <meta> tag to configure it from Rails without rebuilding the bundle). const SAMPLE_RATE = 0.1; // 10% const isSampled = Math.random() < SAMPLE_RATE; const queue = []; function addToQueue({ name, value, id, rating, delta, navigationType }) { queue.push({ name, value, id, rating, delta, navigation_type: navigationType, // Capture the path when the metric is observed, not when the queue is // flushed -- with Turbo Drive one flush can carry metrics from several // routes. Send the pathname only: query strings can contain tokens or PII. page: window.location.pathname, }); } function flushQueue() { if (!isSampled || queue.length === 0) { return; } // splice(0) drains the queue and returns its contents in one step. const body = JSON.stringify({ metrics: queue.splice(0) }); // sendBeacon queues delivery even while the page unloads. Wrap the payload in // a Blob so the request carries a JSON content type and Rails parses the // params (a bare string would be sent as text/plain). const blob = new Blob([body], { type: 'application/json' }); if (!(navigator.sendBeacon && navigator.sendBeacon(VITALS_ENDPOINT, blob))) { // Fallback for browsers without sendBeacon: keepalive lets the request // outlive the page. Telemetry is fire-and-forget -- swallow delivery // errors instead of surfacing them. fetch(VITALS_ENDPOINT, { method: 'POST', body, headers: { 'Content-Type': 'application/json' }, keepalive: true, }).catch(() => {}); } } onCLS(addToQueue); onFCP(addToQueue); onINP(addToQueue); onLCP(addToQueue); onTTFB(addToQueue); // CLS, LCP, and INP only settle when the page is hidden or unloaded, so flush // on visibility change rather than on a timer. addEventListener('visibilitychange', () => { if (document.visibilityState === 'hidden') { flushQueue(); } }); // pagehide covers older Safari, which does not reliably fire visibilitychange // on unload. addEventListener('pagehide', flushQueue); // Turbo Drive swaps the page without firing visibilitychange or pagehide, so // also flush before each Turbo visit. Harmless no-op in apps without Turbo. addEventListener('turbo:before-visit', flushQueue); ``` Why this shape: - **Queue + flush on `visibilitychange`/`pagehide`** — CLS, LCP, and INP are not final until the user leaves the page, so per-metric immediate POSTs would both undercount and multiply requests. Batching into one beacon per page view is the pattern the `web-vitals` documentation recommends. - **`navigator.sendBeacon`** — a normal `fetch`/XHR issued during unload is routinely cancelled by the browser; `sendBeacon` hands the payload to the browser to deliver asynchronously even after the page is gone. The `keepalive: true` fetch is the fallback for the rare browser without it. - **Turbo Drive** — Turbo navigations swap the `<body>` without firing `visibilitychange` or `pagehide`, so several routes can share one flush. That is why the snippet stamps each metric with the pathname **at observation time** (one `page` per metric, not per POST) and also flushes on `turbo:before-visit`. Registering that listener in a non-Turbo app is a harmless no-op — the event simply never fires. - **Back/forward cache** — `web-vitals` treats a [bfcache](https://web.dev/articles/bfcache) restore as a separate page view and reports all metrics again with new `id`s (and `navigationType: 'back-forward-cache'`). The listeners and queue survive the restore, so those metrics are delivered on the next hide — no extra code needed. - **Payload fields** mirror the `web-vitals` [`Metric` type](https://github.com/GoogleChrome/web-vitals#metric): `name` (`'CLS' | 'FCP' | 'INP' | 'LCP' | 'TTFB'`), `value`, `id` (unique per metric per page load — use it to deduplicate), `rating` (`'good' | 'needs-improvement' | 'poor'`), `delta` (change since the last report of this metric), and `navigationType` (e.g. `'navigate'`, `'reload'`, `'back-forward'`, `'prerender'`) — plus the `page` pathname the snippet captures per metric. ## Server: a first-party ingestion endpoint Add a route: ```ruby # config/routes.rb post "/web_vitals", to: "web_vitals#create" ``` And a controller: ```ruby # app/controllers/web_vitals_controller.rb class WebVitalsController < ApplicationController # sendBeacon cannot set custom request headers, so the beacon arrives without # the X-CSRF-Token header Rails expects. Skipping forgery protection on this # one write-only, anonymous endpoint is the standard trade-off -- see the # CSRF section below before copying this. skip_forgery_protection VALID_NAMES = %w[CLS FCP INP LCP TTFB].freeze VALID_RATINGS = %w[good needs-improvement poor].freeze def create rows = coerced_rows return head :unprocessable_entity if rows.nil? # insert_all! (Rails 6+) writes every row in one all-or-nothing statement, # skipping per-row callbacks/validations -- fine for telemetry. On older # Rails, wrap per-row creates in a single transaction instead. WebVitalMetric.insert_all!(rows) if rows.any? head :no_content end private # Coerce and validate every metric before persisting anything. Metrics with # an unknown name or rating are silently dropped (skipped, not an error); # any non-numeric value rejects the whole beacon by returning nil. Either # way, nothing half-persists. String fields are length-clamped because this # endpoint skips CSRF protection -- never trust client-supplied sizes. def coerced_rows now = Time.current vitals_params[:metrics].to_a.filter_map do |metric| next unless VALID_NAMES.include?(metric[:name]) next unless VALID_RATINGS.include?(metric[:rating]) { name: metric[:name], value: Float(metric[:value]), delta: Float(metric[:delta]), metric_id: metric[:id].to_s.byteslice(0, 64), rating: metric[:rating], navigation_type: metric[:navigation_type].to_s.byteslice(0, 32), page: metric[:page].to_s.byteslice(0, 255), created_at: now } end rescue ArgumentError, TypeError # Float() raises on non-numeric values. nil end def vitals_params params.permit(metrics: %i[name value id rating delta navigation_type page]) end end ``` The strong-params schema matches the client payload (and the `web-vitals` `Metric` type): `name`, `value`, `id`, `rating`, `delta`, `navigation_type`, plus the per-metric page path. Everything else in the request is dropped, and all metrics are coerced up front and written in a single atomic insert — a malformed beacon never half-persists. ### CSRF and abuse considerations `skip_forgery_protection` is what makes the `sendBeacon` path work, and it is a real trade-off: - **Why it is usually acceptable here**: the endpoint is write-only, stores anonymous numeric metrics, returns no data, and performs no action on behalf of a user — there is nothing for a classic CSRF attack to gain. - **What you give up**: anyone can POST junk metrics. Mitigate with the strict schema validation above (unknown names/ratings are dropped, non-numeric values are rejected) and rate limiting (e.g. a [Rack::Attack](https://github.com/rack/rack-attack) throttle on `POST /web_vitals` per IP). Treat the data as untrusted telemetry, not as an audit log. - **Alternative that keeps CSRF protection**: skip `sendBeacon` entirely and always use `fetch(..., { keepalive: true })` with the `X-CSRF-Token` header read from the `csrf-token` meta tag (emitted by `csrf_meta_tags`). `keepalive` requests survive unload in modern browsers, though delivery is somewhat less reliable than `sendBeacon` (keepalive requests share a small per-origin in-flight budget). Pick this if your security posture rules out any unprotected endpoint. ### Sampling The `SAMPLE_RATE` constant in the client snippet controls what fraction of page views report. 10% is a sensible default for most apps: Core Web Vitals are percentile statistics, so you need volume, not completeness. Guidance: - **Low-traffic apps** (under ~10k page views/day): sample 100% (`1`) — you need every data point to compute a stable p75. - **High-traffic apps**: 1–10% is typically plenty. At 1M page views/day, a 1% sample still yields 10k measurements. - Decide **once per page view** (as the snippet does), never per metric — otherwise a page view contributes CLS but not LCP and your per-page correlations break. - To tune the rate without rebuilding the bundle, emit it from Rails (e.g. `<meta name="web-vitals-sample-rate" content="<%= ENV.fetch('WEB_VITALS_SAMPLE_RATE', '0.1') %>">`) and read it in the snippet instead of hardcoding the constant. ## Storage and aggregation This is guidance, not a product — storage and visualization are your app's choice. Two common paths: ### Option 1: ActiveRecord table ```ruby # Generate with `bin/rails generate migration CreateWebVitalMetrics` so the # migration version matches your app's Rails version. class CreateWebVitalMetrics < ActiveRecord::Migration[7.1] def change create_table :web_vital_metrics do |t| t.string :name, null: false t.float :value, null: false t.float :delta t.string :metric_id t.string :rating t.string :navigation_type t.string :page t.datetime :created_at, null: false end add_index :web_vital_metrics, %i[name created_at] add_index :web_vital_metrics, %i[page name] end end ``` Core Web Vitals thresholds are defined at the **75th percentile**, so query p75 rather than averages (averages hide the slow tail that ratings are based on): ```sql -- p75 LCP per page over the last 7 days (PostgreSQL) SELECT page, percentile_cont(0.75) WITHIN GROUP (ORDER BY value) AS p75_lcp_ms, count(*) AS samples FROM web_vital_metrics WHERE name = 'LCP' AND created_at > now() - interval '7 days' GROUP BY page ORDER BY p75_lcp_ms DESC; ``` `percentile_cont` is PostgreSQL-specific — on MySQL or SQLite, compute the percentile with a window function (`PERCENT_RANK()`/`NTILE`) or load the sorted values and pick the p75 index in Ruby. Prune old rows on a schedule (a nightly `WebVitalMetric.where("created_at < ?", 90.days.ago).delete_all` job) or roll daily percentiles up into a summary table if volume grows. ### Option 2: forward to your existing APM If you already run an APM or metrics stack (New Relic, Datadog, Sentry, Prometheus/StatsD, Scout, Skylight…), skip the table and forward from the controller instead — e.g. emit a custom event or a distribution/histogram metric tagged with `name`, `rating`, and `page`. You keep the same first-party beacon and endpoint; only the sink changes. This is usually the right call when the APM already owns your dashboards and alerting. ## Privacy This setup is deliberately privacy-friendly, but keep it that way: - **No PII in beacons.** The payload is metric names and numbers plus a page path. Do not add user IDs, emails, session tokens, or full URLs — the snippet sends `location.pathname` precisely because query strings can carry tokens or personal data. If a path itself embeds an identifier (e.g. `/users/123`), normalize it before storing (`/users/:id`). - **First-party only.** Data goes from the user's browser to your own origin and stays in your database. There is no third-party analytics script, no cross-site cookie, and no data-processing agreement with an analytics vendor to manage — which substantially simplifies the GDPR story compared with shipping field data to an external RUM service. - **No fingerprinting.** Resist the temptation to add user-agent strings, precise geolocation, or device fingerprints "for segmentation." Coarse dimensions (`navigation_type`, `rating`, page path) answer almost every performance question. ## How this complements server-side benchmarks The `benchmarks/` suite and [Performance Benchmarks](../core-concepts/performance-benchmarks.md) answer "did this change make server rendering slower?" under controlled load. Field Web Vitals answer "what do real users experience?" across real devices, networks, and cache states — including everything the server-side numbers cannot see: asset delivery, font loading (see [Font Optimization](./fonts.md), which targets LCP and CLS directly), hydration cost, and third-party scripts. Use both: Bencher to catch server-render regressions in CI, and your vitals table to verify that optimizations actually move p75 LCP/CLS/INP for users. ## Related - [Performance Benchmarks](../core-concepts/performance-benchmarks.md) — the server-side measurement story this complements - [Font Optimization](./fonts.md) — a direct LCP/CLS lever, verifiable with this setup - [Caching](./caching.md) — server-side render caching, a common TTFB lever - [web.dev: Web Vitals](https://web.dev/articles/vitals) — metric definitions and thresholds - [GoogleChrome/web-vitals](https://github.com/GoogleChrome/web-vitals) — the collection library - [Issue #3877](https://github.com/shakacode/react_on_rails/issues/3877) — tracking for the planned framework-level hydration-timing instrumentation ================================================================================ PAGE: https://reactonrails.com/docs/building-features/node-renderer/basics SOURCE: docs/oss/building-features/node-renderer/basics.md ================================================================================ # Node Renderer Basics > **Pro Feature** — Available with [React on Rails Pro](../../../pro/react-on-rails-pro.md). > Free or very low cost for startups and small companies. [Upgrade or licensing details →](../../../pro/upgrading-to-pro.md#try-pro-risk-free) ## Requirements - You must use React on Rails v11.0.7 or higher. ## Install the Gem and the Node Module See [Installation](../../../pro/installation.md). ## Memory Management The Node Renderer reuses V8 VM contexts across requests for performance. This means **module-level state in your server bundle persists across all SSR requests**. Any unbounded caches, `_.memoize` calls, or growing data structures at module scope will leak memory until the worker restarts. **Essential for production:** - Set `NODE_OPTIONS=--max-old-space-size=<MB>` to prevent V8 from deferring garbage collection - Enable worker rolling restarts via `allWorkersRestartInterval` and `delayBetweenIndividualWorkerRestarts` - Audit your server bundle for module-level mutable state See the [Memory Leaks guide](../../../pro/js-memory-leaks.md) for common leak patterns and how to fix them. ## Setup Node Renderer Server **node-renderer** is a standalone Node application to serve React SSR requests from a **Rails** client. You don't need any **Ruby** code to setup and launch it. You can configure with the command line or with a launch file. > **Generator shortcut:** Running `rails generate react_on_rails:install --pro` (or `rails generate react_on_rails:pro` for existing apps) automatically creates `renderer/node-renderer.js`, adds the Node Renderer process to `Procfile.dev`, and installs the required npm packages. See [Installation](../../../pro/installation.md) for details. The manual setup below is for apps that need custom configuration. ## Simple Command Line for node-renderer 1. ENV values for the default config are (See [JS Configuration](./js-configuration.md) for more details): - `RENDERER_PORT` - `RENDERER_HOST` - `RENDERER_LOG_LEVEL` - `RENDERER_SERVER_BUNDLE_CACHE_PATH` - `RENDERER_BUNDLE_PATH` (legacy alias) - `RENDERER_WORKERS_COUNT` - `RENDERER_PASSWORD` - `RENDERER_ALL_WORKERS_RESTART_INTERVAL` - `RENDERER_DELAY_BETWEEN_INDIVIDUAL_WORKER_RESTARTS` - `RENDERER_SUPPORT_MODULES` 2. Configure ENV values and run the command. Note, you can set port with args `-p <PORT>`. For example, assuming node-renderer is in your path: ```bash RENDERER_SERVER_BUNDLE_CACHE_PATH=/app/.node-renderer-bundles node-renderer ``` 3. You can use a command line argument of `-p SOME_PORT` to override any ENV value for the PORT. ## JavaScript Configuration File For the most control over the setup, create a JavaScript file to start the NodeRenderer. 1. Create some project directory, let's say `renderer-app`: ```sh mkdir renderer-app cd renderer-app ``` 2. Make sure you have **Node.js 18+** and a JavaScript package manager such as **npm**, **pnpm**, **Yarn**, or **bun**. 3. Initialize a Node application and install the `react-on-rails-pro-node-renderer` package. ```sh npm init -y npm install react-on-rails-pro-node-renderer # or: pnpm add react-on-rails-pro-node-renderer # or: yarn add react-on-rails-pro-node-renderer # or: bun add react-on-rails-pro-node-renderer ``` 4. Configure a JavaScript file that will launch the rendering server per the docs in [Node Renderer JavaScript Configuration](./js-configuration.md). For example, create a file `renderer/node-renderer.js`. Here is a simple example that uses all the defaults except for serverBundleCachePath: ```javascript import path from 'path'; import reactOnRailsProNodeRenderer from 'react-on-rails-pro-node-renderer'; const config = { serverBundleCachePath: path.resolve(__dirname, '../.node-renderer-bundles'), }; reactOnRailsProNodeRenderer(config); ``` 5. Now you can launch your renderer server with `node renderer/node-renderer.js`. You will probably add a script to your `package.json`. 6. You can use a command line argument of `-p SOME_PORT` to override any configured or ENV value for the port. ## Setup Rails Application Create `config/initializers/react_on_rails_pro.rb` and configure the **renderer server**. See configuration values in [Configuration](../../configuration/configuration-pro.md). Pay attention to: 1. Set `config.server_renderer = "NodeRenderer"` 2. Decide whether to enable `config.prerender_caching = true`. The default is `false`; turn it on only if you want Rails cache-backed SSR result caching and your cache is configured for the additional load. 3. Configure values beginning with `renderer_` 4. Use ENV values for values like `renderer_url` so that your deployed server is properly configured. If the ENV value is unset, the default for the renderer_url is `localhost:3800`. 5. Here's a tiny example using mostly defaults: ```ruby ReactOnRailsPro.configure do |config| config.server_renderer = "NodeRenderer" # when this ENV value is not defined, the local server at localhost:3800 is used config.renderer_url = ENV["REACT_RENDERER_URL"] end ``` ## Network Security The Node Renderer executes JavaScript sent to it by the Rails application using Node.js `vm.runInContext()`. This makes it, by design, a **remote code execution service** — any client that can reach the HTTP port can execute arbitrary JavaScript on the host machine. Node.js [`vm` contexts are not a security boundary](https://nodejs.org/api/vm.html#vm-executing-javascript). Escaping a `vm` sandbox to access the full Node.js runtime (file system, child processes, network) is well-documented and straightforward. To mitigate this, the renderer uses the same approach as PostgreSQL: **it binds to `localhost` by default**, so it is not reachable from the network at all. This provides two layers of defense: 1. **Network layer** — Only processes on the same machine (or same Kubernetes pod network namespace) can reach the renderer. No remote attacker can connect. 2. **Authentication layer** — The optional `password` setting (required in production-like environments) protects against unauthorized local callers. This means a developer running the renderer locally without a password is safe by default — the renderer is only reachable from their own machine, just as a default PostgreSQL installation only accepts local connections. **When you must bind to `0.0.0.0`** (e.g., separate container workloads in Docker Compose or Kubernetes separate-workload deployments): - Always set `RENDERER_PASSWORD` to a strong value - Place the renderer behind private networking or firewall rules - Never expose the renderer port to the public internet See [JS Configuration](./js-configuration.md) for the `host` and `password` options, and [Container Deployment](./container-deployment.md) for architecture-specific guidance. ## CI and Test Environment Setup Running tests that involve server-side rendering requires the Node Renderer to be running. Without it, tests will silently timeout with `Net::ReadTimeout` -- not crash with a clear error -- making the failure easy to misdiagnose. ### 1. Guard the initializer for test environments A common mistake is guarding the Node Renderer configuration with `Rails.env.development?`, which excludes the test environment: ```ruby # config/initializers/react_on_rails_pro.rb # WRONG -- excludes test environment if Rails.env.development? ReactOnRailsPro.configure do |config| config.server_renderer = "NodeRenderer" end end # CORRECT -- covers both development and test if Rails.env.local? ReactOnRailsPro.configure do |config| config.server_renderer = "NodeRenderer" end end ``` `Rails.env.local?` returns `true` for both `development` and `test` environments (available since Rails 7.1). For older Rails versions, use `Rails.env.development? || Rails.env.test?`. ### 2. Start the renderer in CI The Node Renderer must be started as a background process before running tests. Add a step to your CI workflow: ```yaml # .github/workflows/test.yml (GitHub Actions example) jobs: test: runs-on: ubuntu-latest env: # Job-level: both the renderer and Rails test steps need this RENDERER_PASSWORD: ${{ secrets.RENDERER_PASSWORD }} steps: - name: Start Node Renderer run: | node renderer/node-renderer.js & # Wait for the renderer to be ready. # The renderer uses cleartext HTTP/2 (h2c), so use --http2-prior-knowledge for the probe. # --max-time 2 prevents hangs if the port is open but the process is stalled. for i in $(seq 1 30); do if curl -s --http2-prior-knowledge --max-time 2 http://localhost:3800/ > /dev/null 2>&1; then echo "Node Renderer is ready" break fi echo "Waiting for Node Renderer... ($i/30)" sleep 1 done # Fail fast if renderer never became ready if ! curl -s --http2-prior-knowledge --max-time 2 http://localhost:3800/ > /dev/null 2>&1; then echo "Node Renderer failed to start in time" >&2 exit 1 fi ``` Key points: - **Readiness check**: Poll port 3800 (or your configured port) before running tests. The renderer uses **cleartext HTTP/2 (h2c)**, so the `curl` probe must include `--http2-prior-knowledge`. Without it, `curl` sends an HTTP/1.1 request that the h2c server rejects. - **`RENDERER_PASSWORD`**: Must be set in the CI environment and match the value configured in `react_on_rails_pro.rb`. Add it as a CI secret. **Important:** Declare this at the job level (not just the renderer step) so Rails can also read it when running tests. - **Bundle pre-staging**: You do **not** need to set a bundle path env var for the renderer. In CI, run `rake react_on_rails_pro:pre_stage_bundle_for_node_renderer` after the webpack build and before starting the renderer — this symlinks the compiled bundle into the renderer's cache directory, eliminating the first-request upload latency. For remote renderers, use `rake react_on_rails_pro:copy_assets_to_remote_vm_renderer` instead. ### 3. Common CI failures | Symptom | Cause | Fix | | ----------------------------------------- | ------------------------------ | -------------------------------------- | | All tests timeout with `Net::ReadTimeout` | Node Renderer not running | Add the renderer start step above | | "Connection refused" errors | Renderer started but not ready | Add the TCP readiness check loop | | Tests pass locally but fail in CI | `Rails.env.development?` guard | Change to `Rails.env.local?` | | "Invalid password" errors | `RENDERER_PASSWORD` mismatch | Ensure CI env var matches Rails config | ## Troubleshooting - See [Memory Leaks guide](../../../pro/js-memory-leaks.md). ## Upgrading The NodeRenderer has a protocol version on both the Rails and Node sides. If the Rails server sends a protocol version that does not match the Node side, an error is returned. Ideally, you want to keep both the Rails and Node sides at the same version. ## References - [Installation](../../../pro/installation.md) - [Rails Options for node-renderer](../../configuration/configuration-pro.md) - [JS Options for node-renderer](./js-configuration.md) - [Container Deployment](./container-deployment.md) — Sidecar vs. separate workloads, memory tuning, autoscaling, and troubleshooting ================================================================================ PAGE: https://reactonrails.com/docs/building-features/node-renderer/js-configuration SOURCE: docs/oss/building-features/node-renderer/js-configuration.md ================================================================================ # Node Renderer JavaScript Configuration > **Pro Feature** — Available with [React on Rails Pro](../../../pro/react-on-rails-pro.md). > Free or very low cost for startups and small companies. [Upgrade or licensing details →](../../../pro/upgrading-to-pro.md#try-pro-risk-free) You can configure the node-renderer entirely with ENV values from your own launch file or `package.json` script. The package does not ship a standalone `node-renderer` CLI. For most apps, create a small configuration file to set up and launch the node-renderer. The values in this file must be kept in sync with the `config/initializers/react_on_rails_pro.rb` file, as documented in [Configuration](../../configuration/configuration-pro.md). Here are the options available for the JavaScript renderer configuration object, as well as the available default ENV values if you wire them into your own launch script. [//]: # 'If you change text here, you may want to update comments in packages/node-renderer/src/shared/configBuilder.ts as well.' 1. **port** (default: `process.env.RENDERER_PORT || 3800`) - The port the renderer should listen to. [On Heroku](https://devcenter.heroku.com/articles/dyno-startup-behavior#port-binding-of-web-dynos) or [ControlPlane](https://docs.controlplane.com/reference/workload/containers#port-variable) you may want to use `process.env.PORT`. 1. **host** (default: `process.env.RENDERER_HOST || 'localhost'`) - The host/IP address the renderer should bind to. The default of `localhost` keeps the renderer reachable only from the local machine (or the same Kubernetes pod network namespace), following the same secure-by-default approach as PostgreSQL. Set to `0.0.0.0` only when the renderer must be reachable across a network boundary (e.g., separate container workloads in Docker Compose or Kubernetes). **Security caution:** The renderer executes JavaScript sent to it via `vm.runInContext()`, making it a remote code execution service by design. The Node.js `vm` module is [not a security boundary](https://nodejs.org/api/vm.html#vm-executing-javascript). Binding to `0.0.0.0` without `password` authentication exposes this to anyone on the network. Only bind to `0.0.0.0` behind private networking or firewall rules, and always set `password` when the renderer is network-accessible. See [Network Security](./basics.md#network-security) for details. 1. **logLevel** (default: `process.env.RENDERER_LOG_LEVEL || 'info'`) - The renderer log level. Set it to `silent` to turn logging off. [Available levels](https://getpino.io/#/docs/api?id=levels): `{ fatal: 60, error: 50, warn: 40, info: 30, debug: 20, trace: 10 }`. `silent` can be used as well. 1. **logHttpLevel** (default: `process.env.RENDERER_LOG_HTTP_LEVEL || 'error'`) - The HTTP server log level (same allowed values as `logLevel`). 1. **fastifyServerOptions** (default: `{}`) - Additional options to pass to the Fastify server factory. See [Fastify documentation](https://fastify.dev/docs/latest/Reference/Server/#factory). 1. **serverBundleCachePath** (default: `process.env.RENDERER_SERVER_BUNDLE_CACHE_PATH || process.env.RENDERER_BUNDLE_PATH || '/tmp/react-on-rails-pro-node-renderer-bundles'` ) - Path to a cache directory where uploaded server bundle files will be stored. This is distinct from Shakapacker's public asset directory. For example you can set it to `path.resolve(__dirname, './.node-renderer-bundles')` if you configured renderer from the `/` directory of your app. 1. **workersCount** (default: `process.env.RENDERER_WORKERS_COUNT || defaultWorkersCount()` where default is your CPUs count - 1) - Number of workers that will be forked to serve rendering requests. If you set this manually make sure that value is a **Number** and is `>= 0`. Setting this to `0` will run the renderer in a single process mode without forking any workers, which is useful for debugging purposes. For production use, the value should be `>= 1`. 1. **password** (default: `env.RENDERER_PASSWORD`) - The password expected to receive from the **Rails client** to authenticate rendering requests. In `development` and `test` environments (checked via both `NODE_ENV` and `RAILS_ENV`), the password is optional — if unset, no authentication is required. In all other environments (`staging`, `production`, etc.), the renderer will refuse to start without an explicit password. Set `RENDERER_PASSWORD` in your environment or pass `password` in the config object. 1. **allWorkersRestartInterval** (default: `env.RENDERER_ALL_WORKERS_RESTART_INTERVAL`) - Interval in minutes between scheduled restarts of all workers. By default restarts are not enabled. If restarts are enabled, `delayBetweenIndividualWorkerRestarts` should also be set. **Recommended for production** — rolling restarts are the primary safety net against memory leaks from application code. See the [Memory Leaks guide](../../../pro/js-memory-leaks.md). 1. **delayBetweenIndividualWorkerRestarts** (default: `env.RENDERER_DELAY_BETWEEN_INDIVIDUAL_WORKER_RESTARTS`) - Interval in minutes between individual worker restarts (when cluster restart is triggered). By default restarts are not enabled. If restarts are enabled, `allWorkersRestartInterval` should also be set. Set this high enough so that not all workers are down simultaneously (e.g., if you have 4 workers and set this to 5 minutes, the full restart cycle takes 20 minutes). 1. **gracefulWorkerRestartTimeout**: (default: `env.GRACEFUL_WORKER_RESTART_TIMEOUT`) - Time in seconds that the master waits for a worker to gracefully restart (after serving all active requests) before killing it. For example, `30` means 30 seconds, not 30 milliseconds. Use this when you want to avoid situations where a worker gets stuck in an infinite loop and never restarts. This config is only usable if worker restart is enabled. The timeout starts when the worker should restart; if it elapses without a restart, the worker is killed. 1. **maxDebugSnippetLength** (default: 1000) - If the rendering request is longer than this, it will be truncated in exception and logging messages. 1. **supportModules** - (default: `env.RENDERER_SUPPORT_MODULES || null`) - If set to true, `supportModules` enables the server-bundle code to call a default set of NodeJS global objects and functions that get added to the VM context: `{ Buffer, TextDecoder, TextEncoder, URLSearchParams, ReadableStream, process, performance, setTimeout, setInterval, setImmediate, clearTimeout, clearInterval, clearImmediate, queueMicrotask }`. `performance` is included so React 19's development build can call `performance.now()` from `React.lazy` without throwing `ReferenceError: performance is not defined`. This option is required to equal `true` if you want to use loadable components. Setting this value to false causes the NodeRenderer to behave like ExecJS. See also `stubTimers`. 1. **additionalContext** - (default: `null`) - additionalContext enables you to specify additional NodeJS objects (usually from https://nodejs.org/api/globals.html) to add to the VM context in addition to our `supportModules` defaults. Object shorthand notation may be used, but is not required. Example: `{ URL, Crypto }` 1. **stubTimers** - (default: `env.RENDERER_STUB_TIMERS` if that environment variable is set, `true` otherwise) - With this option set, use of functions `setTimeout`, `setInterval`, `setImmediate`, `clearTimeout`, `clearInterval`, `clearImmediate`, and `queueMicrotask` will do nothing during server-rendering. This is useful when using dependencies like [react-virtuoso](https://github.com/petyosi/react-virtuoso) that use these functions during hydration. In RORP, hydration typically is synchronous and single-task (unless you use streaming) and thus callbacks passed to task-scheduling functions should never run during server-side rendering. Because these functions are valid client-side, they are ignored on server-side rendering without errors or warnings. Note that `performance` (exposed when `supportModules: true`) is the host's real `performance` object and is **not** stubbed by `stubTimers`; if rendered output embeds `performance.now()` values (e.g., dev-only timing annotations) they will vary between renders. Override via `additionalContext` (e.g., `{ performance: { now: () => 0 } }`) if strict SSR determinism is required. See also `supportModules`. 1. **enableHealthEndpoints** - (default: `false`; set `RENDERER_ENABLE_HEALTH_ENDPOINTS` to `true`, `TRUE`, `yes`, `YES`, or `1` to enable) - If set to `true`, the renderer registers built-in, unauthenticated `GET /health` (liveness) and `GET /ready` (readiness) probe endpoints with status-only response bodies. See [Health and Readiness Endpoints](./health-checks.md) for semantics and working Kubernetes/ECS probe examples (the renderer's h2c listener cannot be probed with HTTP/1.1 `httpGet` probes). Deprecated options: 1. **bundlePath** - Renamed to `serverBundleCachePath`. The old name will continue to work but will log a deprecation warning. 1. **honeybadgerApiKey**, **sentryDsn**, **sentryTracing**, **sentryTracesSampleRate** - Deprecated and have no effect. If you have any of them set, see [Error Reporting and Tracing](./error-reporting-and-tracing.md) for the new way to set up error reporting and tracing. 1. **includeTimerPolyfills** - Renamed to `stubTimers`. ## Runtime Globals for SSR and RSC The node renderer executes uploaded JavaScript bundles inside isolated VM contexts. Those contexts do not automatically inherit every global from the host Node.js process. | Runtime path | Execution environment | Global guarantees | | ------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Client bundle | Browser | Browser APIs such as `window`, `document`, and browser `fetch` are available. Node.js globals are not. | | Server bundle (SSR) | Node renderer VM context | JavaScript built-ins are available. With the `supportModules` option enabled, common Node.js globals (`Buffer`, `TextDecoder`, `TextEncoder`, `URLSearchParams`, `ReadableStream`, `process`, `performance`, timer functions) are injected. | | RSC bundle payload render | Node renderer VM context for RSC code | Uses the same VM context rules as the server bundle. The bundle is built for RSC, but host Node.js globals still need to be bundled, polyfilled, or injected. | `supportModules` injects a fixed set of common Node.js globals; it does **not** mirror the host global object into the VM. It does **not** inject `fetch`, `Headers`, `Request`, `Response`, `AbortController`, or `AbortSignal`. Even if the Node.js process that launches the renderer has those globals, code inside the renderer VM will not see them unless you provide them. That means Server Components should not assume that "modern Node" global `fetch` or fetch-related cancellation APIs are available in the server or RSC bundle. > **Warning:** Passing `additionalContext: {}` (an empty object) still opts the renderer into CommonJS execution mode, where bundle code can call `require()` against the renderer host's module graph. If you do not need any injected globals, use `additionalContext: null` instead. See the [Bundle Architecture Reference](../../../pro/react-server-components/rendering-flow.md#bundle-architecture-reference) for the full security and behavioral implications. Prefer passing application data from Rails controllers through props when the data belongs to your Rails app. When a Server Component really needs to call an external HTTP API from the renderer, choose one of these approaches: 1. Inject host globals through `additionalContext`. Node.js 18+ exposes `globalThis.fetch`, `Headers`, `Request`, and `Response` by default (Node.js 18 and 20 mark the fetch API as experimental; fetch became stable in Node.js 21 and remains stable in Node.js 22+ LTS). Start with the guarded example below so the renderer fails fast if any required fetch global is absent. On older or unsupported Node.js versions without these globals, use a bundled HTTP client instead (see option 2). 2. Import a server-side HTTP client in the component code, such as `undici` (recommended for new projects) or `node-fetch` v2 (CJS-compatible legacy fallback; v3+ is ESM-only; `node-fetch` v2 is maintenance-only since 2022, with security fixes only), and let your bundler include it in the RSC/server bundle. ```js const { reactOnRailsProNodeRenderer } = require('react-on-rails-pro-node-renderer'); const fetchImplementation = globalThis.fetch; const HeadersImplementation = globalThis.Headers; const RequestImplementation = globalThis.Request; const ResponseImplementation = globalThis.Response; // Set to true only if your Server Components use AbortSignal; requires Node.js 15+. const componentsUseAbortSignals = false; if (!fetchImplementation || !HeadersImplementation || !RequestImplementation || !ResponseImplementation) { throw new Error( 'Your Node.js runtime does not expose one or more required fetch globals (fetch, Headers, Request, Response). ' + 'Use a supported Node.js release that exposes these globals or replace the globalThis.* references above with compatible fetch polyfill imports.', ); } if (componentsUseAbortSignals && (!globalThis.AbortController || !globalThis.AbortSignal)) { throw new Error( 'Your component code uses abort signals, but this Node.js runtime does not expose AbortController and AbortSignal. ' + 'Use a runtime that exposes them or replace the globalThis.* references below with compatible abort polyfill imports.', ); } reactOnRailsProNodeRenderer({ supportModules: true, additionalContext: { fetch: fetchImplementation, Headers: HeadersImplementation, Request: RequestImplementation, Response: ResponseImplementation, ...(componentsUseAbortSignals ? { AbortController: globalThis.AbortController, AbortSignal: globalThis.AbortSignal, } : {}), }, }); ``` Set `componentsUseAbortSignals` to `true` when component code creates or accepts `AbortSignal` values. That guard turns a missing `AbortController` or `AbortSignal` into a startup error; without it, the renderer would start and the first component that touches those globals would fail later with `ReferenceError`. If your components do not use abort signals, set it to `false` or omit those `additionalContext` entries. `supportModules` does not add abort globals. Install a fetch implementation only when your renderer runtime does not provide these globals, or when you intentionally want a bundled HTTP client instead of the host runtime's implementation. Use this decision guide: | Situation | Recommendation | | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Supported Node.js LTS host, want to use the runtime's built-in fetch | Use the guarded `globalThis.fetch` / `additionalContext` example above. | | Supported Node.js LTS, ESM or CommonJS, want a bundled HTTP client | Use `undici` and choose a release compatible with your runtime; see [undici's compatibility notes](https://github.com/nodejs/undici#long-term-support) for version pairs. | | CommonJS launch file on an older runtime that does not expose fetch globals | Use `node-fetch` v2; `node-fetch` v3+ is ESM-only. | For new projects, prefer `undici`. The `undici` example below is the primary bundled-client pattern; the `node-fetch` v2 example after it is a legacy fallback for older or unsupported Node.js installations. Use the same `additionalContext` shape with `undici` as with the `globalThis.fetch` example above. Unlike `node-fetch` v2, `undici` exports `fetch` as a named export; choose a version compatible with your renderer Node.js runtime. Add the same startup guard so incompatible versions fail before the renderer starts. The example below uses CommonJS; ESM launchers can import the same names from `undici` and alias them to the `*Implementation` constants used here. ```js const { reactOnRailsProNodeRenderer } = require('react-on-rails-pro-node-renderer'); const { fetch: fetchImplementation, Headers: HeadersImplementation, Request: RequestImplementation, Response: ResponseImplementation, } = require('undici'); // `undici` does not export `AbortController`/`AbortSignal` as named exports // (verified against v6 and v8 — they are absent from `Object.keys(require('undici'))`). // Bundle code that uses abort signals relies on the host globals (Node.js 15+), // injected via `additionalContext` below. // Set to true only if your Server Components use AbortSignal; requires Node.js 15+. const componentsUseAbortSignals = false; if (!fetchImplementation || !HeadersImplementation || !RequestImplementation || !ResponseImplementation) { throw new Error( 'The selected undici version does not expose one or more required fetch globals (fetch, Headers, Request, Response). ' + 'Choose an undici release compatible with your renderer Node.js runtime.', ); } if (componentsUseAbortSignals && (!globalThis.AbortController || !globalThis.AbortSignal)) { throw new Error( 'Your component code uses abort signals, but this Node.js runtime does not expose AbortController and AbortSignal. ' + 'Use Node.js 15+, or replace the globalThis.* references below with compatible abort polyfill imports.', ); } reactOnRailsProNodeRenderer({ supportModules: true, additionalContext: { fetch: fetchImplementation, Headers: HeadersImplementation, Request: RequestImplementation, Response: ResponseImplementation, ...(componentsUseAbortSignals ? { AbortController: globalThis.AbortController, AbortSignal: globalThis.AbortSignal, } : {}), }, }); ``` For older or unsupported Node.js installations that cannot use a current `undici` release, fall back to `node-fetch` v2 in a CommonJS launch file: ```js const { reactOnRailsProNodeRenderer } = require('react-on-rails-pro-node-renderer'); // node-fetch v2: the CJS default export is the fetch function itself. // There is no named "fetch" export, so require("node-fetch").fetch is undefined. // Headers, Request, and Response are attached as properties on that default export. const nodeFetch = require('node-fetch'); // A successful require returns the fetch function; the guard below verifies // the attached fetch classes that node-fetch v2 must provide. const { Headers: HeadersImplementation, Request: RequestImplementation, Response: ResponseImplementation, } = nodeFetch; if ( typeof nodeFetch !== 'function' || !HeadersImplementation || !RequestImplementation || !ResponseImplementation ) { throw new Error( 'node-fetch v2 did not expose the required fetch function or fetch classes (Headers, Request, Response). ' + 'Ensure node-fetch v2 is installed; v3+ is ESM-only and will not work in this CommonJS launcher.', ); } reactOnRailsProNodeRenderer({ supportModules: true, additionalContext: { fetch: nodeFetch, Headers: HeadersImplementation, Request: RequestImplementation, Response: ResponseImplementation, }, }); ``` `node-fetch` v2 does not ship its own `AbortController` or `AbortSignal` implementation, but `node-fetch` v2.6+ accepts spec-compatible signals when you provide them. If component code uses abort signals, merge the optional abort globals shown in the `globalThis.fetch` example into `additionalContext`; on Node.js 18+, the native `globalThis.AbortController` and `globalThis.AbortSignal` work with `node-fetch` v2.6+. On older EOL runtimes, use a compatible polyfill such as `node-abort-controller`. ## Example Launch Files ### Testing example: The repository's dummy app keeps a full integration-test launcher at [`react_on_rails_pro/spec/dummy/renderer/node-renderer.js`](https://github.com/shakacode/react_on_rails/blob/main/react_on_rails_pro/spec/dummy/renderer/node-renderer.js). ### Simple example: Create a file `renderer/node-renderer.js`. The generator uses this filename and CommonJS syntax so the file runs directly with `node renderer/node-renderer.js` without extra ESM configuration. ```js const path = require('path'); const { reactOnRailsProNodeRenderer } = require('react-on-rails-pro-node-renderer'); const config = { // Save bundles to relative "./.node-renderer-bundles" dir of our app root serverBundleCachePath: path.resolve(__dirname, '../.node-renderer-bundles'), // All other values are the defaults, as described above }; // For debugging, run in single process mode if (process.env.NODE_ENV === 'development') { config.workersCount = 0; } // Renderer detects a total number of CPUs on virtual hostings like Heroku or CircleCI instead // of CPUs number allocated for current container. This results in spawning many workers while // only 1-2 of them really needed. else if (process.env.CI) { config.workersCount = 2; } reactOnRailsProNodeRenderer(config); ``` And add a root-level script to the `scripts` section of your `package.json` ```json "scripts": { "node-renderer": "node renderer/node-renderer.js" }, ``` Run the renderer with `pnpm run node-renderer` (or the equivalent `npm`/`yarn` command for your app). ## Built-in Endpoints The React on Rails Pro node renderer registers `/info` as a plain `GET` route outside the authenticated render and asset endpoints, and it does not use the render or asset authentication prechecks, so it remains accessible without the renderer password even when `password` is configured. The route returns `node_version` and `renderer_version`. Treat it as a shallow process check and keep the renderer on `localhost` or private networking if those runtime version details should not be exposed. Verify it locally: ```bash curl -s --http2-prior-knowledge http://localhost:3800/info ``` Example response: ```json { "node_version": "v20.17.0", "renderer_version": "1.4.2" } ``` ## Custom Fastify Configuration For advanced use cases, such as adding custom routes, registering Fastify plugins, or hooking into the request lifecycle, you can configure the Fastify server directly by importing the `master` and `worker` modules instead of using `reactOnRailsProNodeRenderer`. The advanced examples below use ES modules for readability. If you want this file to keep running as `node renderer/node-renderer.js`, either keep using the CommonJS pattern shown in the simple example above or switch the file to `.mjs` or `"type": "module"`. ### Adding a Health Check Endpoint > **Built-in alternative:** The renderer now ships built-in `GET /health` (liveness) and `GET /ready` (readiness) > endpoints behind the `enableHealthEndpoints` config option — no custom Fastify code required. See > [Health and Readiness Endpoints](./health-checks.md). Use the recipe below only when you need custom probe logic > (extra warm-up gates, dependency checks, or custom payloads). > If your `configureFastify` callback already registers `/health` or `/ready`, remove or rename the custom route > before enabling `enableHealthEndpoints`; Fastify raises a duplicate-route startup error for reused paths. > If the duplicate route is registered by an async Fastify plugin during `app.register()` boot, Fastify reports its raw > `FST_ERR_DUPLICATED_ROUTE` error instead of the `enableHealthEndpoints` migration hint. A common need is a `/health` endpoint for container health checks: ```js import masterRun from 'react-on-rails-pro-node-renderer/master'; import run, { configureFastify } from 'react-on-rails-pro-node-renderer/worker'; import cluster from 'cluster'; const config = { // Your configuration options here }; // Register a custom health check route configureFastify((app) => { app.get('/health', () => { // Return a Promise or use async/await if warm-up checks involve async operations. return { status: 'ok' }; }); }); // The node-renderer uses Node.js cluster module to fork worker processes. // The primary process manages workers; workers handle HTTP requests. if (cluster.isPrimary) { masterRun(config); } else { run(config); } ``` The sample `/health` route is intentionally shallow and omits handler parameters because it does not need them. Fastify also passes `request` and `reply` to handlers if you need to inspect headers, set status codes, or customize the response. Add warm-up or readiness-gate logic inside this handler if readiness should wait for renderer-specific initialization. To signal not-ready while keeping Fastify's return-value style, add `reply` to the handler parameters, set the status with `reply.code(503)`, and return a response object from that branch. Do not call `reply.send()` and then return another response object. ```js // Example: signal not-ready while application-specific warm-up runs. // `workersReady` stands in for any per-worker readiness gate you maintain. let workersReady = false; configureFastify((app) => { // Fastify's `onReady` hook runs once per worker after all plugins finish // loading. Put any application warm-up here — preload modules, hydrate // caches, wait for an external dependency — and flip the flag when done. app.addHook('onReady', async () => { // await yourWarmUpFunction(); // put async warm-up logic here before flipping the flag workersReady = true; }); app.get('/health', (request, reply) => { if (!workersReady) { reply.code(503); return { status: 'warming_up' }; } return { status: 'ok' }; }); }); ``` The `-f` flag in `curl -sf` causes curl to exit non-zero for HTTP 4xx/5xx responses, so a `503` from this handler correctly fails the probe. Kubernetes exec probes treat any non-zero curl exit code as a failure; the response body is irrelevant to probe semantics, so you can return whatever payload is useful for debugging, such as `{ status: 'ok', workers: 4 }`. Routes registered with `configureFastify` do not automatically use the renderer's render and asset authentication prechecks. A custom `/health` route like the one above is reachable without the renderer password unless you add your own Fastify authentication. Keep probe routes shallow and non-sensitive, and keep the renderer on `localhost` or private networking. ### Registering Fastify Plugins You can also register Fastify plugins. This example assumes you're using the same cluster setup pattern shown above: ```js // In the worker branch of your cluster setup (see example above) import run, { configureFastify } from 'react-on-rails-pro-node-renderer/worker'; import cors from '@fastify/cors'; configureFastify((app) => { // Register a plugin app.register(cors, { origin: true, }); }); // Add request logging configureFastify((app) => { app.addHook('onRequest', (request, reply, done) => { try { console.log(`Request: ${request.method} ${request.url}`); done(); } catch (err) { done(err); } }); }); ``` > **Note:** The `configureFastify` function must be called before calling `run()`. Multiple callbacks can be registered and will execute in order. You can use `app.ready()` in your callback to ensure all plugins are loaded before performing operations that depend on them. ### API Stability The `./master` and `./worker` exports provide direct access to the node-renderer internals. While we strive to maintain backwards compatibility, these are considered advanced APIs. If you only need basic configuration, prefer using the standard `reactOnRailsProNodeRenderer` function with the configuration options documented above. ## Configuring Startup, Readiness, and Liveness Probes This section is the canonical source for probe semantics, recommended timing values, and curl command guidance. The copy-paste YAML lives in [Kubernetes Sidecar Manifest](./container-deployment.md#kubernetes-sidecar-manifest); update the values here first when tuning, then reflect the change in the manifest. Keep the three probe types distinct: - **Startup** answers whether the renderer has finished booting. Separate it from readiness and liveness so slow startup does not cause premature restarts or block traffic. - **Readiness** answers whether the renderer should receive new render requests. Use the built-in `/ready` endpoint only when an out-of-band warm-up render can compile a bundle before probe-gated traffic begins. Without that warm-up path, prefer a shallow TCP readiness check or the built-in `/info` endpoint, and use `/ready` for monitoring or post-deploy verification. See [Health and Readiness Endpoints](./health-checks.md) for the full cold-start semantics. - **Liveness** answers whether the renderer is stuck badly enough that restarting the container is safer. Prefer `tcpSocket` as the default so transient CPU or GC pauses do not restart an otherwise recoverable renderer; use an h2c-aware `exec` check only when you intentionally need stricter hung-process detection. Only the custom `/health` route requires `configureFastify`; `tcpSocket` probes and `/info` checks work without custom Fastify setup. The health check route should return `200 OK` when the renderer is ready to serve requests, and return a non-2xx status (for example `503`) only when the process should be marked unhealthy for the probe's purpose — readiness, startup, or stricter liveness. > **Security note:** See [Built-in Endpoints](#built-in-endpoints) for the note on `/info` exposing runtime version > details. Do not put Rails, database, Redis, or other external dependency checks in the node-renderer's liveness probe. A temporary dependency outage should not restart every renderer replica. If SSR must be available before Rails receives traffic, make the Rails readiness endpoint perform a short renderer check. The renderer listens with cleartext HTTP/2 (h2c). Do not configure a Kubernetes `httpGet` probe, Control Plane HTTP probe, or any other HTTP/1.1-only probe directly against the renderer port; those probes are rejected by the h2c listener. Use one of these probe styles instead: | Probe style | When to use it | | ------------ | ----------------------------------------------------------------------------------------------------------------------------------- | | `tcpSocket` | Startup checks, default liveness checks, and fallback readiness when curl with HTTP/2 support is unavailable. | | `exec` probe | Application-level readiness and optional stricter liveness checks with an h2c-aware client, such as `curl --http2-prior-knowledge`. | | HTTP/1.1 | Only if you probe Rails, a separate HTTP/1.1 health sidecar/port, or another endpoint that is not the renderer h2c listener. | A passing `tcpSocket` probe means the h2c listener has bound to the port; cluster workers might still be warming up. Keep an application-level readiness probe if traffic should wait for worker initialization. For Kubernetes and platform `tcpSocket` probes, set the renderer `host` to `0.0.0.0` because those probes connect to the pod or workload IP, not container-local loopback. The default `localhost` binding is fine for `exec` probes that run inside the renderer container. For liveness, start with `tcpSocket`. A fully blocked Node.js event loop may still accept TCP connections and pass that check, so use an h2c-aware `exec` liveness probe with a short `--max-time` only if you explicitly need stricter hung-process detection and have verified curl HTTP/2 support in the image. > **Note:** The `exec` probe requires curl with HTTP/2 support. Verify with `curl --version | grep -i http2`. If unavailable, > use a `tcpSocket` probe as a fallback. Recommended starting values: - **Startup**: Use `tcpSocket` on the renderer port (`3800` by default; use your configured `RENDERER_PORT` value if different). TCP is enough here because readiness below gates traffic; startup only shields liveness during boot. Start with `initialDelaySeconds: 10` (first check fires at 10 s; the sixth and final check fires at `10 + ((6 - 1) * 5) = 35 s` after container start, and the restart follows once that check actually fails — up to `timeoutSeconds` later), `periodSeconds: 5`, `failureThreshold: 6`, and the Kubernetes default `timeoutSeconds: 1` for a TCP connection check. - **Readiness (custom route)**: Use `exec` with `curl -sf --max-time 3 --http2-prior-knowledge http://localhost:3800/health` after registering the route with [`configureFastify`](#adding-a-health-check-endpoint). Start with `timeoutSeconds: 5`, `periodSeconds: 5`, and `failureThreshold: 3`. - **Readiness (built-in info)**: Use `exec` with `curl -sf --max-time 3 --http2-prior-knowledge http://localhost:3800/info`. Use the same timing settings as the custom-route readiness probe. See the canonical [`/info` security note](#built-in-endpoints) for the unauthenticated-access caveat. - **Readiness fallback**: Use `tcpSocket` on the renderer port only if curl with HTTP/2 support is unavailable. This checks port reachability, not application readiness. - **Liveness**: Use `tcpSocket` on the renderer port as the default. Start with `timeoutSeconds: 1`, `periodSeconds: 10`, and `failureThreshold: 3`, matching the Container Deployment examples. Raise `failureThreshold`, and optionally `periodSeconds`, if hard listener checks restart the container too aggressively in your environment. `timeoutSeconds: 1` assumes a co-located probe over loopback; raise it (typically to `2`-`3`) when the renderer is reached over the network, such as the separate-workload topology. - **Optional stricter liveness**: Use `curl -sf --max-time 3 --http2-prior-knowledge http://localhost:3800/info` only when you need liveness to catch a blocked event loop and have verified curl has HTTP/2 support in the image. Keep external dependency and warm-up checks in readiness, not liveness. Substitute `3800` with your actual renderer port in Kubernetes YAML `exec` arrays; shell variable expansion does not apply there. See the `port` option at the top of this page for Heroku or Control Plane. > **Note (startup window):** With `initialDelaySeconds: 10`, `periodSeconds: 5`, and `failureThreshold: 6`: > > - First check fires at **10 s**. > - Last (6th) check fires at **35 s** (`10 + (6 - 1) × 5`). > - Container restarts after the 6th consecutive failure, up to `timeoutSeconds` (1 s here) later. > > If you omit `initialDelaySeconds`, checks start immediately and the last check fires at **25 s** (`(6 - 1) × 5`). > Increase `failureThreshold` or `periodSeconds` if startup regularly takes longer. Reduce `initialDelaySeconds` if the > renderer reliably opens its port within 1-2 s, or match it to your actual boot time to suppress noisy early-failure > log entries during the warm-up window. Readiness and liveness omit `initialDelaySeconds` here because Kubernetes 1.20+ (startup probe GA) defers them until the startup probe succeeds. If you skip the startup probe or run an older cluster without startup probe support, add an appropriate `initialDelaySeconds` to each. See [Kubernetes Sidecar Manifest](./container-deployment.md#kubernetes-sidecar-manifest) for a complete pod spec with all three probes wired in, and [Startup Errors: `ERR_STREAM_PREMATURE_CLOSE`](./container-deployment.md#startup-errors-err_stream_premature_close) for the startup-error troubleshooting context. For Control Plane topology-specific `renderer_url`, host binding, and probe target guidance, see [Control Plane Deployment Shapes](./container-deployment.md#control-plane-deployment-shapes). ================================================================================ PAGE: https://reactonrails.com/docs/building-features/node-renderer/container-deployment SOURCE: docs/oss/building-features/node-renderer/container-deployment.md ================================================================================ # Node Renderer: Container Deployment > **Pro Feature** — Available with [React on Rails Pro](https://pro.reactonrails.com). > ShakaCode Trust-Based Commercial Licensing: no token is required for development, test, CI/CD, or staging. [Pro pricing and sign up](https://pro.reactonrails.com/) covers production licenses, with free or low-cost options for qualifying startups and small companies. This guide covers deploying the Node Renderer in containerized environments (Docker, Kubernetes, ControlPlane, etc.), including architecture options, performance tuning, memory management, error tracking, and troubleshooting. ## Prerequisites - **React on Rails Pro** v16.4.0 or later - **Node.js** 22+ (LTS recommended) - **Ruby** 3.1+ with Bundler - The `react-on-rails-pro-node-renderer` npm package installed in your project ## Architecture Options When running Rails and the Node Renderer in containers, you have three options, listed from simplest to most complex: | | Single Container | Sidecar Containers | Separate Workloads | | -------------------------- | ---------------------- | --------------------------- | ----------------------------------------------- | | **Complexity** | Lowest | Medium | Highest | | **Scaling** | Together | Together | Independent | | **Version alignment** | Guaranteed | Guaranteed | Risk of drift | | **Networking** | `localhost` | `localhost` | Service DNS | | **Per-process visibility** | No | Yes | Yes | | **When to use** | Default starting point | Need to diagnose OOM source | Need independent scaling at high replica counts | [Diagram: Three container topologies for running Rails with the Pro Node Renderer. Single container: both processes run in one container sharing OS resources and talking over localhost — lowest complexity, scaled together, versions always aligned. Sidecar containers: Rails and the Node Renderer run as two containers in the same pod with their own resource limits but still talking over localhost — scaled together, versions aligned, with per-process visibility. Separate workloads: Rails and the renderer run as independent workloads communicating over service DNS — scaled independently but with a risk of version drift on rolling deploys.] ### Option 1: Single Container (Default) Rails and the Node Renderer run together in a **single container**. This is the simplest setup and the recommended starting point (the leftmost topology in the diagram above). Both processes share the container's CPU and memory limits (cgroup resources); they do not communicate via shared-memory IPC. **Advantages:** - **Simplest setup** — One container, one image, one deploy. - **No networking config** — Rails connects to the renderer via `localhost` out of the box. - **Guaranteed version alignment** — Both processes always run from the same image. - **Lower overhead** — Shared OS layer saves ~200–300 MB vs. separate containers. **When to move on:** If you're experiencing OOM restarts and need to determine whether Rails or the Node Renderer is the culprit, move to sidecar containers for visibility. **Configuration:** ```ruby # config/initializers/react_on_rails_pro.rb ReactOnRailsPro.configure do |config| config.server_renderer = "NodeRenderer" config.renderer_url = "http://localhost:3800" end ``` ### Option 2: Sidecar Containers Rails and the Node Renderer run as separate containers within the **same pod/workload**, sharing the same lifecycle (the middle topology in the diagram above). Use this when you need to isolate and diagnose memory/CPU usage per process. **Advantages:** - **Per-process visibility** — See exactly which process is consuming memory and causing OOM kills. - **Independent resource limits** — Set separate CPU/memory limits for Rails and the Node Renderer. - **Guaranteed version alignment** — Both containers use the same image on deploy. - **Simpler networking** — Rails still connects via `localhost`. **Tradeoffs:** - Slightly more complex deployment config than a single container. - Autoscaling logic may need adjustment (see [Autoscaling Considerations](#autoscaling-considerations)). **Configuration:** ```ruby # config/initializers/react_on_rails_pro.rb ReactOnRailsPro.configure do |config| config.server_renderer = "NodeRenderer" config.renderer_url = "http://localhost:3800" end ``` ### Option 3: Separate Workloads Rails and the Node Renderer run as independent workloads with their own scaling. This is the most complex option and is rarely needed. **Advantages:** - **Independent scaling** — Scale the renderer independently of Rails. - **Isolated resource limits** — OOM in the renderer doesn't affect Rails and vice versa. **Disadvantages:** - **Version drift risk** — During rolling deploys, Rails and the Node Renderer may briefly run different versions. While protocol changes are rare, this is a risk to monitor. - **Race conditions** — Pods restart independently, which can cause transient connection errors. - **Network dependency** — Renderer must be reachable via internal service DNS. - **Overkill for most setups** — If you're running 2–4 replicas, independent scaling adds complexity without real benefit. **Configuration:** ```ruby # config/initializers/react_on_rails_pro.rb ReactOnRailsPro.configure do |config| config.server_renderer = "NodeRenderer" config.renderer_url = ENV.fetch("RENDERER_URL", "http://node-renderer-service:3800") end ``` > **Recommendation:** Start with a single container. Move to sidecar containers if you need per-process memory/CPU visibility (e.g., to diagnose OOM restarts). Separate workloads are rarely justified unless you have a specific need for independent scaling at high replica counts. ## Control Plane Deployment Shapes For Control Plane deployments, choose the probe target based on where the node renderer runs. Control Plane configures probes per container. Renderer probe targets below mean `tcpSocket` or h2c-aware `exec` probes, not HTTP/1.1 `httpGet` probes directly against the renderer. [Control Plane Flow](https://github.com/shakacode/control-plane-flow)'s default `rails` template models Rails as a single-container standard workload. If you follow that template and run the renderer inside the Rails container, configure the Rails workload's probes rather than looking for a separate node-renderer container. If you split the renderer into its own container or workload, add renderer-specific probes there. ### Same Rails Container (Rails and Renderer Co-Located) Set the Rails `renderer_url` to `http://localhost:3800`. The renderer can keep the default `localhost` host binding. Probe the `rails` container's Rails health endpoint, such as `/up` on port `3000` in Rails 7.1+ or a custom endpoint in earlier Rails versions. This also applies when a process supervisor starts Rails and the renderer together in the same container: probe the Rails container and let the Rails health endpoint cover the co-located renderer when needed. When Rails and the renderer share one container, use one combined Rails health endpoint if you need to check both processes. For example, make the Rails readiness endpoint perform a short TCP connection check to `localhost:3800` and return `503` if the renderer is unreachable. Because this guide covers React on Rails Pro's Node Renderer, the Rails endpoint below reads the same `ReactOnRailsPro.configuration.renderer_url` value used for SSR requests rather than requiring a second port environment variable. `config/routes.rb`: ```ruby # Override Rails 7.1+'s built-in /up route to add the renderer TCP check. # If you already have custom /up logic, use a distinct path such as /healthz # to avoid silently replacing existing health behavior. get "up", to: "health#show" ``` Loading the `Socket` stdlib from an initializer keeps the controller body lean and outside the autoload boundary, which matches Rails conventions for stdlib dependencies. If your environment already auto-requires stdlib (for example via Bundler) the require below is harmless; placing it in an initializer is still preferred. `config/initializers/socket_require.rb`: ```ruby # Load the Ruby stdlib Socket class once at boot for the Health controller's TCP check. require "socket" ``` `app/controllers/health_controller.rb`: ```ruby # Inherits from ActionController::Base (not ApplicationController) to avoid # app-level authentication callbacks on unauthenticated probe requests. # `Socket` is loaded once at boot via config/initializers/socket_require.rb. class HealthController < ActionController::Base def show # A successful TCP connect means the h2c listener is bound, not that cluster workers # are ready. Pair with the startup probe to shield liveness during boot. # In this same-container topology, Rails and the renderer share a network namespace, # so always probe localhost even if other deployment shapes use a service host. # connect_timeout is supported by the Ruby versions in this guide's prerequisites. renderer_url = ReactOnRailsPro.configuration.renderer_url raise ArgumentError, "renderer_url not configured" if renderer_url.nil? || renderer_url.empty? # Extract the explicit port from the URL authority, skipping any userinfo # (`user@`, `user:pass@`) and supporting bracketed IPv6 hosts. URI#port would # return 80/443 for URLs without an explicit port, so we read the string # directly and fall back to 3800 when no authority port is present. renderer_port = renderer_url[%r{://(?:[^/?#@]*@)?(?:\[[^\]]+\]|[^/?#:]+):(\d+)}, 1]&.to_i || 3800 # Block form ensures the socket closes after a successful connect; the explicit # |_socket| parameter signals that the empty body is intentional, not a typo. Socket.tcp("localhost", renderer_port, connect_timeout: 1) { |_socket| } head :ok rescue SocketError, SystemCallError # Only renderer reachability failures map to 503. ArgumentError raised above # intentionally escapes as 500 so a misconfigured `renderer_url` stays visible # in logs and alerting. head :service_unavailable end end ``` > **Topology-specific:** This same-container example always probes `localhost` and only borrows the port from > `renderer_url`. Do not reuse it as-is for sidecar or separate-workload topologies where the renderer runs behind a > different host. > > A missing `renderer_url` raises `ArgumentError` and surfaces as a 500 so the misconfiguration stays visible in logs > and alerting. Only renderer reachability failures are converted to `503`. ### Separate Container In The Same Workload Keep the Rails `renderer_url` as `http://localhost:3800`. Use `0.0.0.0` for the renderer `host` when you rely on `tcpSocket` probes; `localhost` is fine for `exec`-only probes. Add h2c-aware `exec` probes against `localhost:3800` or `tcpSocket` probes on the renderer port. For `tcpSocket`, bind the renderer to `0.0.0.0` because Kubernetes and platform TCP probes are initiated by the kubelet and connect to the pod or workload IP, not container-local loopback. Rails→renderer HTTP traffic over `localhost` still works inside the shared pod network namespace (see [Host Binding for Container Environments](#host-binding-for-container-environments)); only externally-initiated probes need the `0.0.0.0` bind. `exec` probes run a command inside the container, so `localhost` works there. > **Probe YAML:** For Control Plane readiness and liveness fields, reuse the individual `exec` or `tcpSocket` probe blocks > from [Kubernetes Sidecar Manifest](#kubernetes-sidecar-manifest). Attach them to the node-renderer container in this > workload instead of to a separate Kubernetes pod spec. ### Separate Node-Renderer Workload Set the Rails `renderer_url` to `http://<WORKLOAD_NAME>.<GVC_NAME>.cpln.local:3800`, use `0.0.0.0` for the renderer `host`, and add `tcpSocket` or h2c-aware `exec` probes to the node-renderer workload container. Expose the renderer port internally, not publicly, unless required. Use the same Control Plane probe fields as the same-workload case, but attach them to the separate node-renderer workload container. Replace `<WORKLOAD_NAME>` with the renderer workload name and `<GVC_NAME>` with your Control Plane Global Virtual Cloud name. Use your actual renderer port if it is not `3800`; see Control Plane's [service-to-service endpoint format](https://docs.controlplane.com/guides/service-to-service). ## Dockerfile Example > **Why the renderer entry point lives in a dedicated `renderer/` directory:** Production Docker builds commonly strip JavaScript sources after the client bundles are built, since the Rails app no longer needs them at runtime. Keeping the renderer entry point in its own top-level directory (separate from `client/`) makes it trivial to exclude from that cleanup — the Node Renderer process still needs its entry file and dependencies at runtime. A minimal Dockerfile that bundles Rails and the Node Renderer in a single image: ```dockerfile FROM node:22-slim AS node FROM ruby:3.3 # Copy Node.js from the official image (avoids curl-pipe-bash) COPY --from=node /usr/local/bin/node /usr/local/bin/node COPY --from=node /usr/local/lib/node_modules /usr/local/lib/node_modules RUN ln -s /usr/local/lib/node_modules/npm/bin/npm-cli.js /usr/local/bin/npm # jemalloc for Rails memory (adjust path for arm64: aarch64-linux-gnu) # and curl for h2c health checks (`curl --http2-prior-knowledge`) RUN apt-get update && apt-get install -y libjemalloc2 curl && rm -rf /var/lib/apt/lists/* ENV LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libjemalloc.so.2 ENV MALLOC_CONF="dirty_decay_ms:1000,muzzy_decay_ms:1000" WORKDIR /app # Install Ruby and Node dependencies COPY Gemfile Gemfile.lock ./ RUN bundle install COPY package.json package-lock.json ./ RUN npm ci COPY . . # Precompile assets RUN bundle exec rake assets:precompile # Expose Rails and Node Renderer ports EXPOSE 3000 3800 # Start both processes with a process manager (overmind, foreman, etc.) # See the Procfile example below CMD ["overmind", "start", "-f", "Procfile"] ``` For the single-container pattern, use a process manager like [overmind](https://github.com/DarthSim/overmind) or [foreman](https://github.com/ddollar/foreman) with a `Procfile`: ```text # Procfile rails: bundle exec rails server -b 0.0.0.0 -p 3000 renderer: node renderer/node-renderer.js ``` > **Tip:** For sidecar containers, use the same image but override the `CMD` — one container runs `bundle exec rails server`, the other runs `node renderer/node-renderer.js` (or your Node Renderer entry point). ## Docker Compose Example For local development with sidecar-like containers: ```yaml services: rails: build: . command: bundle exec rails server -b 0.0.0.0 -p 3000 ports: - '3000:3000' environment: RENDERER_URL: 'http://renderer:3800' depends_on: renderer: condition: service_healthy renderer: build: . command: node renderer/node-renderer.js ports: - '3800:3800' environment: RENDERER_HOST: '0.0.0.0' NODE_OPTIONS: '--max-old-space-size=512' healthcheck: # --max-time 2 leaves a 1 s buffer below the 3 s healthcheck timeout so curl exits # cleanly with a non-zero code rather than being killed mid-request. test: ['CMD', 'curl', '-sf', '--max-time', '2', '--http2-prior-knowledge', 'http://localhost:3800/info'] interval: 5s timeout: 3s retries: 5 start_period: 10s ``` > **Note:** In Docker Compose, the containers do not share a network namespace (unlike Kubernetes sidecars), so the renderer must bind to `0.0.0.0` and Rails must connect via the service name (`renderer`). > The Compose example uses `--max-time 2` with `timeout: 3s` for fast local feedback; the Kubernetes examples use > `--max-time 3` with `timeoutSeconds: 5` to allow more scheduler and node-load jitter. ## Host Binding for Container Environments By default, the Node Renderer binds to `localhost`. For **sidecar containers** in the same Kubernetes pod, that works because the containers share a network namespace. For **separate workloads** or Docker Compose setups without shared networking, bind to `0.0.0.0`: ```javascript // renderer/node-renderer.js import { reactOnRailsProNodeRenderer } from 'react-on-rails-pro-node-renderer'; const config = { host: '0.0.0.0', // ... other config }; reactOnRailsProNodeRenderer(config); ``` Or via environment variable: ```bash RENDERER_HOST=0.0.0.0 ``` > **Security note:** The renderer executes JavaScript via `vm.runInContext()`, making it a remote code execution service. Binding to `0.0.0.0` exposes this to the network. Use it only when the renderer must be reachable across a network namespace (separate workloads, Docker Compose). Always set `RENDERER_PASSWORD` and place the renderer behind private networking when bound to `0.0.0.0`. See [Network Security](./basics.md#network-security) for the full threat model. ## Optimizing Performance per Cost ### Memory: Understanding the Growth Pattern The Node Renderer's memory grows over time as it handles SSR requests. This is **expected behavior** — V8's garbage collector doesn't always return memory to the OS, even after objects are freed. In containerized environments with cgroup memory limits, this can trigger OOM kills. Typical memory profile: - **Startup:** ~500–600 MB for the renderer process with workers - **After hours of traffic:** 2–3 GB+ depending on component complexity and traffic volume - **Rails container:** Usually stabilizes at 2–4 GB depending on `WEB_CONCURRENCY` and `RAILS_MAX_THREADS` ### Constraining Node Memory Use `NODE_OPTIONS` to cap V8's old-generation heap per worker: ```bash NODE_OPTIONS="--max-old-space-size=512" ``` This tells V8 to trigger garbage collection more aggressively and limits each worker's heap. Adjust the value based on your component complexity: | Component Complexity | Recommended `max-old-space-size` | | ------------------------------------- | -------------------------------- | | Simple components | 256–512 MB | | Medium (Redux, large props) | 512–768 MB | | Complex (large data, many components) | 768–1024 MB | > **Note:** This setting applies per worker. Total renderer memory ≈ `max-old-space-size × workersCount + overhead`. If V8 hits the limit, the worker process exits and is automatically restarted by the cluster manager. ### Worker Count Tuning The default `workersCount` is CPU count minus 1, which may over-allocate in containers. Set it explicitly: ```javascript const config = { workersCount: parseInt(process.env.RENDERER_WORKERS_COUNT, 10), // Required — derive from the sizing formula below }; ``` **Sizing guideline:** Match worker count to expected concurrent SSR requests. A rough formula (assuming each SSR render takes roughly half a full Rails request cycle, so one renderer worker can serve ~2 concurrent threads — adjust the divisor based on your measured render times): ```text renderer_workers ≥ (WEB_CONCURRENCY × RAILS_MAX_THREADS × ssr_request_ratio) / 2 ``` Where `ssr_request_ratio` is the fraction of requests that need server rendering (often 30–60% for hybrid apps). Example: With `WEB_CONCURRENCY=4` and `RAILS_MAX_THREADS=8` (32 total Rails threads), and ~50% of requests needing SSR: ```text renderer_workers ≥ (4 × 8 × 0.5) / 2 = 8 workers ``` > **Tip:** Monitor CPU utilization per worker. If average CPU per worker is above 80%, you need more workers. If below 20%, you can reduce. ### Rolling Worker Restarts To mitigate memory growth, enable periodic worker restarts: ```javascript const config = { allWorkersRestartInterval: 360, // Restart all workers every 6 hours delayBetweenIndividualWorkerRestarts: 2, // 2 minutes between each worker restart gracefulWorkerRestartTimeout: 30, // Kill stuck workers after 30 seconds }; ``` This drains requests from each worker before restarting, so there's no downtime. ### Container Resource Allocation Recommended starting points for sidecar configuration: | Container | CPU Request | CPU Limit | Memory Request | Memory Limit | | ------------- | ----------- | --------- | -------------- | ------------ | | Rails | 1–2 cores | 2–4 cores | 4 GB | 4 GB | | Node Renderer | 1–2 cores | 2–4 cores | 4 GB | 4 GB | > **Important:** Set memory **requests** equal to **limits** for the renderer container so its memory budget is explicit. Kubernetes QoS is determined at the pod level, so you only get `Guaranteed` QoS when **every** container in the pod has matching requests and limits. If using `--max-old-space-size`, set the container memory limit to `max-old-space-size × workersCount × 1.5` to account for overhead. ### jemalloc for Rails Memory Consider using [jemalloc](https://github.com/jemalloc/jemalloc) as Ruby's memory allocator to reduce Rails memory fragmentation: ```dockerfile RUN apt-get install -y libjemalloc2 ## Adjust the preload path for your image architecture: ## amd64: /usr/lib/x86_64-linux-gnu/libjemalloc.so.2 ## arm64: /usr/lib/aarch64-linux-gnu/libjemalloc.so.2 ENV LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libjemalloc.so.2 ENV MALLOC_CONF="dirty_decay_ms:1000,muzzy_decay_ms:1000" ``` This won't help the Node Renderer (which uses V8's allocator), but can significantly reduce Rails container memory. ## Graceful Shutdown During rolling deploys and scale-down events, containers receive `SIGTERM` before being killed. Both Rails and the Node Renderer need to handle this gracefully to avoid dropping in-flight requests. ### Node Renderer The Node Renderer's cluster manager handles `SIGTERM` automatically — it stops accepting new connections and waits for in-flight requests to complete before exiting. No additional configuration is needed. Set `terminationGracePeriodSeconds` in your pod spec to give workers enough time to drain: ```yaml spec: terminationGracePeriodSeconds: 60 # default is 30; increase if SSR requests are slow ``` ### Rails Rails handles `SIGTERM` via Puma's built-in graceful shutdown. Ensure `terminationGracePeriodSeconds` exceeds your longest expected request duration. > **Tip:** If either process doesn't shut down within `terminationGracePeriodSeconds`, Kubernetes sends `SIGKILL`. Monitor for exit code 137 in your logs, which may indicate the grace period is too short rather than an OOM kill. ## Autoscaling Considerations When using sidecar containers, autoscaling becomes more nuanced because CPU and memory metrics are aggregated across both containers. ### CPU-Based Autoscaling If you previously scaled on CPU at 75%, you may need to adjust: - **Rails-heavy traffic** (mostly API/JSON responses): Rails CPU spikes, but the renderer is idle. The pod-level CPU average may underreport Rails load. - **SSR-heavy traffic**: Both containers are active. Pod-level CPU is more representative. **Recommendation:** If your orchestrator supports per-container metrics (e.g., Kubernetes custom metrics), scale based on the Rails container's CPU. Otherwise, lower the threshold (e.g., to 60%) to account for the averaging effect. ### Scaling with Separate Workloads With separate workloads, scale each independently: - **Rails**: Scale on CPU utilization or request queue depth. - **Node Renderer**: Scale on CPU utilization per worker. ## Tracking and Responding to Errors ### Startup Errors: `ERR_STREAM_PREMATURE_CLOSE` During container startup, you may see `ERR_STREAM_PREMATURE_CLOSE` errors from Fastify. This occurs when Rails sends render requests before all Node Renderer workers are ready. **Mitigation:** > Probe semantics, timing values, and curl command flags are documented canonically in > [JS Configuration: Configuring Startup, Readiness, and Liveness Probes](./js-configuration.md#configuring-startup-readiness-and-liveness-probes). > The full copy-paste YAML lives in [Kubernetes Sidecar Manifest](#kubernetes-sidecar-manifest) below. Update the JS > Configuration section first when tuning thresholds, then reflect the change in the manifest. 1. **Health check endpoint** — The Node Renderer exposes a built-in `/info` endpoint that returns the node version and renderer version. The renderer uses cleartext HTTP/2, so Kubernetes `httpGet` probes (HTTP/1.1) are incompatible — use a `tcpSocket` probe, an `exec` probe with an h2c-aware client such as `curl --http2-prior-knowledge`, or a dedicated HTTP/1.1 sidecar/port for probes. For a custom `/health` route with more granular checks, see [JS Configuration: Adding a Health Check Endpoint](./js-configuration.md#adding-a-health-check-endpoint). 2. **Startup probe** — A startup probe is the primary mitigation for this error. It defers readiness and liveness until the renderer has bound its port, so Rails only sends render requests after workers are ready: ```yaml startupProbe: tcpSocket: port: 3800 initialDelaySeconds: 10 periodSeconds: 5 failureThreshold: 6 timeoutSeconds: 1 ``` 3. **Readiness and liveness probes** — Configure these alongside the startup probe so Rails only routes requests to a healthy renderer and stuck containers get restarted. See [Configuring Startup, Readiness, and Liveness Probes](./js-configuration.md#configuring-startup-readiness-and-liveness-probes) for probe-style choices, timing values, and curl command guidance, and [Kubernetes Sidecar Manifest](#kubernetes-sidecar-manifest) for the full copy-paste YAML. > **Security:** See the canonical [`/info` security note](./js-configuration.md#built-in-endpoints) for the > unauthenticated-access caveat when `password` is configured. ### OOM Tracking Distinguish between Rails and Node Renderer OOM kills by checking container-level exit codes: - **Exit code 137**: Process received SIGKILL — commonly OOM from cgroup limit, but can also be forced termination (grace-period expiry, liveness probe failure). Check `kubectl describe pod` for `Reason: OOMKilled` to confirm OOM. - **Exit code 1**: Application crash (check logs for stack trace). With sidecar containers, your orchestrator should report which container was OOM-killed. Use this to tune resource limits for the specific container rather than increasing the entire pod. ### Error Reporting See [Error Reporting and Tracing](./error-reporting-and-tracing.md) for setting up Sentry, Honeybadger, or other error tracking with the Node Renderer. ### Logging Set log levels to capture useful information without noise: ```javascript const config = { logLevel: 'info', // General renderer logs logHttpLevel: 'error', // Only log HTTP errors (not every request) }; ``` In production, `logLevel: 'warn'` is sufficient unless actively debugging. ## Kubernetes Sidecar Manifest A complete pod spec for the sidecar pattern. This is the canonical copy-paste YAML for renderer probes — other sections reference it instead of repeating the full block. > [!NOTE] > The manifest uses an h2c-aware `exec` probe for readiness and a `tcpSocket` probe for liveness. Keep that split unless > you intentionally need stricter liveness detection and have verified curl HTTP/2 support in the image. Probe timing > values and curl command guidance are canonical in > [JS Configuration: Configuring Startup, Readiness, and Liveness Probes](./js-configuration.md#configuring-startup-readiness-and-liveness-probes); > update that section first when tuning thresholds and reflect the change here. ```yaml apiVersion: apps/v1 kind: Deployment metadata: name: rails-app spec: replicas: 2 selector: matchLabels: app: rails-app template: metadata: labels: app: rails-app spec: terminationGracePeriodSeconds: 60 containers: - name: rails image: your-app:latest command: ['bundle', 'exec', 'rails', 'server', '-b', '0.0.0.0'] ports: - containerPort: 3000 env: - name: RENDERER_URL value: 'http://localhost:3800' - name: LD_PRELOAD value: '/usr/lib/x86_64-linux-gnu/libjemalloc.so.2' - name: MALLOC_CONF value: 'dirty_decay_ms:1000,muzzy_decay_ms:1000' resources: requests: cpu: '1' memory: '4Gi' limits: cpu: '2' memory: '4Gi' - name: node-renderer image: your-app:latest # Same image as Rails command: ['node', 'renderer/node-renderer.js'] ports: - containerPort: 3800 env: - name: RENDERER_HOST value: '0.0.0.0' # Bind to all interfaces for pod-network access - name: NODE_OPTIONS value: '--max-old-space-size=512' - name: RENDERER_WORKERS_COUNT value: '4' resources: requests: cpu: '1' memory: '4Gi' limits: cpu: '2' memory: '4Gi' startupProbe: tcpSocket: port: 3800 initialDelaySeconds: 10 periodSeconds: 5 failureThreshold: 6 timeoutSeconds: 1 readinessProbe: # Add initialDelaySeconds here if no startupProbe is configured. # Kubernetes 1.20+ defers readiness/liveness until the startupProbe succeeds. exec: command: - curl - -sf - --max-time - '3' - --http2-prior-knowledge - http://localhost:3800/info timeoutSeconds: 5 periodSeconds: 5 failureThreshold: 3 livenessProbe: # Add initialDelaySeconds here if no startupProbe is configured. # Kubernetes 1.20+ defers readiness/liveness until the startupProbe succeeds. tcpSocket: port: 3800 # TCP handshakes should complete quickly; exec/H2 uses timeoutSeconds: 5. timeoutSeconds: 1 periodSeconds: 10 failureThreshold: 3 ``` > **Readiness endpoint:** The manifest uses `/info` for copy-paste safety because that endpoint is built in. Replace > `/info` with `/health` in the readiness probe after registering that route via `configureFastify` if readiness should > wait for renderer-specific warm-up checks. > **Note:** Both containers use the same Docker image, ensuring the React on Rails gem and Node Renderer package versions are always aligned. ## Troubleshooting ### Container restarts frequently (OOM) 1. **Check which container is OOM-killed** — Use your orchestrator's events/logs to identify if it's Rails or the Node Renderer. 2. **If Node Renderer** — Set `NODE_OPTIONS="--max-old-space-size=512"` and enable rolling restarts with both `allWorkersRestartInterval` and `delayBetweenIndividualWorkerRestarts`. 3. **If Rails** — Consider jemalloc and review `WEB_CONCURRENCY` / `RAILS_MAX_THREADS` settings. 4. **Monitor over time** — Memory growth is gradual. Monitor for 8+ hours to see the steady-state memory usage. ### Renderer connection refused after deploy - Verify the renderer container is running and healthy. - For sidecars: Check that the renderer binds to `localhost` (default) or `0.0.0.0`. - For separate workloads: Verify DNS resolution and that `config.renderer_url` matches the renderer's service endpoint. - Check for readiness probe failures that may have removed the renderer from the service. ### Different versions after deploy (separate workloads) The React on Rails gem and Node Renderer package have a protocol version. If they mismatch, render requests return an error. To avoid this: - **Sidecars**: Both containers use the same image, so versions are always aligned. - **Separate workloads**: Deploy both workloads simultaneously. If your orchestrator doesn't support atomic multi-workload deploys, consider switching to sidecars. ### High latency on SSR requests 1. **Check worker count** — If all workers are busy, requests queue up. Increase `workersCount` or scale replicas. 2. **Check `max-old-space-size`** — If set too low, frequent GC pauses increase latency. Increase the limit. 3. **Profile components** — Use `node --inspect` to profile server-rendering code. See [Profiling Server-Side Rendering Code](../../../pro/profiling-server-side-rendering-code.md). ### Startup race condition between Rails and Node Renderer In sidecar configurations, Rails may start before the Node Renderer is ready. Configure `renderer_request_retry_limit` in Rails to retry failed connections: ```ruby ReactOnRailsPro.configure do |config| config.renderer_request_retry_limit = 5 # default: 5 end ``` This handles transient startup ordering issues. For a more robust solution, add a startup dependency or init container that waits for the renderer port to accept TCP connections, or queries `/info` with an h2c-aware client (for example, `curl --http2-prior-knowledge`). ## ControlPlane-Specific Notes When deploying on [ControlPlane](https://controlplane.com): - **Port configuration:** Use `process.env.PORT` for the renderer port if running as a standalone workload. ControlPlane injects the `PORT` environment variable for the primary container. - **Sidecar setup:** Configure separate CPU and memory limits per container in your workload definition. In ControlPlane, sidecar containers are defined alongside the main container in the same workload spec. - **Autoscaling:** ControlPlane uses workload-level metrics for autoscaling — see [Autoscaling Considerations](#autoscaling-considerations) above. If you need per-container scaling, use separate workloads instead of sidecars. - **Health checks:** ControlPlane supports readiness and liveness probes in the same format as Kubernetes. Configure them as shown in the [Kubernetes Sidecar Manifest](#kubernetes-sidecar-manifest) section. ## References - [Node Renderer Basics](./basics.md) - [JS Configuration](./js-configuration.md) - [Error Reporting and Tracing](./error-reporting-and-tracing.md) - [Heroku Deployment](./heroku.md) - [JS Memory Leaks](../../../pro/js-memory-leaks.md) - [Profiling Server-Side Rendering Code](../../../pro/profiling-server-side-rendering-code.md) - [Pro Troubleshooting](../../../pro/troubleshooting.md) ================================================================================ PAGE: https://reactonrails.com/docs/building-features/node-renderer/health-checks SOURCE: docs/oss/building-features/node-renderer/health-checks.md ================================================================================ # Node Renderer Health and Readiness Endpoints > **Pro Feature** — Available with [React on Rails Pro](../../../pro/react-on-rails-pro.md). > Free or very low cost for startups and small companies. [Upgrade or licensing details →](../../../pro/upgrading-to-pro.md#try-pro-risk-free) The node renderer ships built-in, opt-in probe endpoints so container orchestrators (Kubernetes, ECS, Docker Compose, Control Plane) can check renderer liveness and readiness without custom Fastify code: - **`GET /health`** — liveness. Returns `200` with `{ "status": "ok" }` whenever the process can answer, i.e. the event loop is responsive. It intentionally checks **no** dependencies (no bundle, Rails, or license state), so a transient dependency issue never restarts the container. - **`GET /ready`** — readiness. Returns `200` with `{ "status": "ready" }` only when the renderer can actually serve render requests: the worker answering the probe is online **and** at least one server bundle has been compiled into its VM pool. Until then it returns `503` with `{ "status": "waiting_for_bundle" }`, because a renderer with zero bundles responds `410` to render requests until the Rails client uploads one. Both endpoints return status-only JSON bodies — no runtime versions, file paths, or license details — so leaving them reachable exposes nothing sensitive. Like [`/info`](./js-configuration.md#built-in-endpoints), they are plain `GET` routes outside the authenticated render and asset endpoints and do not require the renderer `password` (orchestrator probes cannot carry it). Keep the renderer on `localhost` or private networking as usual; see [Network Security](./basics.md#network-security). ## Status-Code Contract Probe tooling that uses `curl --fail` / `-f` (which `-sf` and `-fsS` both include) exits non-zero on any HTTP status `>= 400`. Whether `--fail` is safe therefore depends on which endpoint you probe: | Endpoint | Status codes | Safe with `curl --fail` / `-f`? | | --------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | | `/health` | Always `200` (process can answer) | **Yes** — never non-2xx. | | `/info` | Always `200` (returns Node and renderer versions) | **Yes** — never non-2xx. | | `/ready` | `200` once a bundle is compiled; `503` `waiting_for_bundle` until then | **Only with a warm-up path.** Without one, `-f` turns the cold-start `503` into a failed probe. | > **Why `curl -fsS .../ready` can break container startup:** during the cold-start window `/ready` returns `503` > (`{"status":"waiting_for_bundle"}`) until the answering worker compiles its first bundle, and `-f`/`--fail` turns > that `503` into a non-zero exit. If that command gates startup/readiness and nothing pre-warms the renderer, the > probe never passes and the container never becomes ready. This is the `503` working as designed, not a bug — see > [Gating traffic on `/ready`](#gating-traffic-on-ready). For a probe that must always pass once the process is up, > point `--fail` at `/health` (or `/info`); reserve `--fail` against `/ready` for setups with a warm-up path. ## Enabling the Endpoints The endpoints are **off by default**. Enable them with the `enableHealthEndpoints` config option or the `RENDERER_ENABLE_HEALTH_ENDPOINTS` environment variable (`true`, `TRUE`, `yes`, `YES`, or `1`): The `1` alias is scoped to `RENDERER_ENABLE_HEALTH_ENDPOINTS`; other node-renderer boolean environment variables keep their existing parsing behavior. ```js // renderer/node-renderer.js const { reactOnRailsProNodeRenderer } = require('react-on-rails-pro-node-renderer'); reactOnRailsProNodeRenderer({ enableHealthEndpoints: true, // ... your other options }); ``` Or, without changing the launch file: ```bash RENDERER_ENABLE_HEALTH_ENDPOINTS=true node renderer/node-renderer.js ``` Verify locally (note `--http2-prior-knowledge` — see the next section for why): ```bash curl -s --http2-prior-knowledge http://localhost:3800/health # => {"status":"ok"} curl -s --http2-prior-knowledge http://localhost:3800/ready # => 503 {"status":"waiting_for_bundle"} until the first bundle upload, then 200 {"status":"ready"} ``` ## h2c: Why `httpGet` Probes Do NOT Work The renderer listens with **cleartext HTTP/2 (h2c)**. Kubernetes `httpGet` probes, ALB target-group health checks, Control Plane HTTP probes, and other HTTP/1.1-only checkers cannot speak h2c and **cannot reach these endpoints** directly. Do not configure an `httpGet` probe against the renderer port — it will always fail. Use these probe shapes instead: - **`exec` probe** with an h2c-aware client packaged in your image, e.g. `curl -sf --http2-prior-knowledge http://localhost:3800/ready`. This is the only shape that checks application-level readiness. Verify your image's curl has HTTP/2 support: `curl --version | grep -i http2`. - **`tcpSocket` probe** as a shallow fallback: it proves the port is bound, not that the renderer can serve. `exec` probes run inside the container, so the default `localhost` host binding works. `tcpSocket` probes connect to the pod/workload IP, so they require the renderer `host` set to `0.0.0.0`. See [Configuring Startup, Readiness, and Liveness Probes](./js-configuration.md#configuring-startup-readiness-and-liveness-probes) for the full probe-style discussion and timing guidance. ## Kubernetes Probes A working probe set for a renderer container with `enableHealthEndpoints: true` and curl (with HTTP/2 support) in the image: ```yaml containers: - name: node-renderer image: my-registry/my-app:latest command: ['node', 'renderer/node-renderer.js'] ports: - containerPort: 3800 env: - name: RENDERER_HOST value: '0.0.0.0' # required by the tcpSocket probes below - name: RENDERER_PORT value: '3800' - name: RENDERER_ENABLE_HEALTH_ENDPOINTS value: 'true' # Startup: shield liveness while the renderer boots. TCP is enough here # because readiness below gates traffic. startupProbe: tcpSocket: port: 3800 initialDelaySeconds: 10 periodSeconds: 5 failureThreshold: 12 # tune to your cold-start time; 10 + (5 * 12) = 70 s total timeoutSeconds: 1 # Readiness: shallow TCP check. Do NOT gate readiness on /ready unless you # also pre-warm the renderer — see "Gating traffic on /ready" below. # (httpGet cannot be used in any case: the renderer listener is h2c-only.) readinessProbe: tcpSocket: port: 3800 periodSeconds: 5 failureThreshold: 3 timeoutSeconds: 1 # Liveness: shallow by default so CPU/GC pauses don't restart the pod. livenessProbe: tcpSocket: port: 3800 periodSeconds: 10 failureThreshold: 3 timeoutSeconds: 1 ``` ### Gating traffic on `/ready` `/ready` reports `503` until the answering worker has compiled at least one bundle, and each worker compiles its first bundle when it serves its first render request. If the readiness probe is the only thing standing between a fresh pod and its first render — a standalone renderer behind a Service, or a sidecar (pod readiness requires **all** containers to be ready, so an unready renderer container blocks traffic to the Rails container too) — then gating readiness on `/ready` deadlocks the rollout: no traffic → no first render → never ready. Only use `/ready` as the readiness gate when something other than probe-gated traffic delivers the first render, for example a deployment pipeline step or Rails initializer that POSTs a warm-up render to each new replica directly (bypassing the Service), or a container `postStart` hook that does the same. That warm-up must reach every renderer worker that can answer probes; with `workersCount > 1`, one render per replica is not enough unless you intentionally run a single worker or fan out warm-up renders to each worker. With a warm-up path in place: ```yaml readinessProbe: exec: command: - curl - -sf - --max-time - '3' - --http2-prior-knowledge - http://localhost:3800/ready periodSeconds: 5 failureThreshold: 3 timeoutSeconds: 5 ``` Without a warm-up path, keep the shallow `tcpSocket` readiness probe and use `/ready` for monitoring, dashboards, and post-deploy verification instead. For stricter hung-process detection, replace the `tcpSocket` liveness probe with an `exec` probe against `/health` (same curl command as the `/ready` example above, with the path changed). A fully blocked event loop still accepts TCP connections, so only the `exec` form catches it. Use the stricter form deliberately — it restarts the container on slow event loops, not just dead ones. > **Cold-start note:** Each worker compiles its first bundle when it serves its first render request, so `/ready` > stays `503` until then — pre-seeding the bundle cache on disk does not by itself flip `/ready`. This is harmless > wherever the check does not gate the traffic that would deliver that first render or replace the container > (monitoring, dashboards, post-deploy checks). Wherever it does gate that traffic or container lifetime — a > Kubernetes Service routing only to ready replicas, a sidecar whose unready state blocks pod readiness, an ECS > container health check, an ALB target group — see "Gating traffic on `/ready`" above before using it as the gate. > A `503` from `/ready` during the cold-start window is correct behavior, not a failure. ## ECS Health Check ECS container health checks run **inside** the container (like a Kubernetes `exec` probe), so they work against the h2c listener with curl and the default `localhost` binding. Use `/health` by default so a normal cold start cannot fail the task before the first render compiles a bundle: ```json { "containerDefinitions": [ { "name": "node-renderer", "command": ["node", "renderer/node-renderer.js"], "portMappings": [{ "containerPort": 3800 }], "environment": [{ "name": "RENDERER_ENABLE_HEALTH_ENDPOINTS", "value": "true" }], "healthCheck": { "command": [ "CMD-SHELL", "curl -sf --max-time 3 --http2-prior-knowledge http://localhost:3800/health || exit 1" ], "interval": 10, "timeout": 5, "retries": 3, "startPeriod": 30 } } ] } ``` Tune `startPeriod` to match the observed image pull, boot, and first-render latency for your app. Larger bundles or slower registries may need 60 seconds or more. If you intentionally warm the renderer before `startPeriod` expires and want ECS to replace a task that cannot serve compiled bundles, change the path to `/ready`. > **ALB note:** ALB target-group health checks are HTTP/1.1 and cannot probe the renderer's h2c port. If the renderer > sits behind a load balancer, prefer the ECS container health check above for renderer health, or use an NLB with the > TCP health-check protocol for a shallow port check. ## Docker Compose ```yaml services: renderer: build: . command: node renderer/node-renderer.js environment: RENDERER_ENABLE_HEALTH_ENDPOINTS: 'true' healthcheck: test: ['CMD', 'curl', '-sf', '--max-time', '3', '--http2-prior-knowledge', 'http://localhost:3800/health'] interval: 5s timeout: 3s retries: 5 start_period: 10s ``` ## Control Plane (CPLN) Control Plane exposes two relevant probe shapes: an **HTTP** probe and a **Command** (exec) probe. The HTTP probe is HTTP/1.1 and **cannot speak the renderer's h2c listener** (see [h2c](#h2c-why-httpget-probes-do-not-work)), so it always fails against these endpoints — use a **Command** probe with an h2c-aware curl instead. Command probes run inside the container, so the default `localhost` binding works and no `0.0.0.0` host is required. Use `/health` (always `200`) for liveness and readiness by default so a normal cold start cannot fail the workload before the first render compiles a bundle. Control Plane uses the Kubernetes-style `readinessProbe` / `livenessProbe` fields on the workload container (the same shape as the [Kubernetes example above](#kubernetes-probes) and the existing [Control Plane deployment docs](../../deployment/docker-deployment.md#deploying-with-control-plane)), with a Command probe expressed as `exec.command`: ```yaml kind: workload spec: containers: - name: node-renderer # ... image, ports, env (RENDERER_ENABLE_HEALTH_ENDPOINTS: 'true') ... # Command probe — h2c-aware curl against /health (always 200). readinessProbe: exec: command: - curl - -sf - --max-time - '3' - --http2-prior-knowledge - http://localhost:3800/health periodSeconds: 5 failureThreshold: 3 timeoutSeconds: 5 # exceed curl --max-time 3 so the probe, not the orchestrator, owns the timeout livenessProbe: exec: command: - curl - -sf - --max-time - '3' - --http2-prior-knowledge - http://localhost:3800/health periodSeconds: 10 failureThreshold: 3 timeoutSeconds: 5 # exceed curl --max-time 3 so the probe, not the orchestrator, owns the timeout ``` Do **not** point a `--fail` Command probe at `/ready` unless something pre-warms the renderer, or the probe will fail on the cold-start `503` and the workload never becomes ready (the exact failure in [Status-Code Contract](#status-code-contract)). Only switch the path to `/ready` once a warm-up path delivers the first render to every worker that answers probes — see [Gating traffic on `/ready`](#gating-traffic-on-ready). ## Semantics and Caveats - **Per-worker checks.** With `workersCount > 1`, the Node.js cluster module distributes incoming connections across worker processes, and each worker has its own VM pool. A probe therefore checks the one worker that answers it. Workers load bundles independently (each compiles the bundle on its first render request), so a freshly restarted worker can briefly report `503` on `/ready` while its siblings serve traffic. This is the intended per-process readiness signal for orchestrators probing one container. During a rollout or cold start, raw probe logs may show a short mix of `503` and `200` responses; Kubernetes smooths that with `failureThreshold` / `successThreshold`, so a single unloaded-worker `503` should not flap pod readiness. - **No license check.** License validation happens on the Rails side; `/ready` does not (and cannot) report license state. - **Liveness checks nothing but the event loop.** Do not point `/health` at dependency monitoring; that is what readiness and your APM are for. - **Custom routes still work.** If you need richer checks (warm-up gates, dependency checks, custom payloads), the [`configureFastify` health-check recipe](./js-configuration.md#adding-a-health-check-endpoint) still applies and can coexist with the built-in endpoints as long as your custom routes use different paths. Remove or rename any existing custom `/health` or `/ready` route before enabling `enableHealthEndpoints`; Fastify raises a duplicate-route startup error when built-in and custom routes share the same path. If an async Fastify plugin registers the duplicate route during `app.register()` boot, you will see Fastify's raw `FST_ERR_DUPLICATED_ROUTE` error instead of the `enableHealthEndpoints` migration hint. ## Rails-Side Readiness To gate a Rails readiness endpoint on the renderer, keep using the TCP-check recipe in [Container Deployment](./container-deployment.md#same-rails-container-rails-and-renderer-co-located), or upgrade it to an HTTP/2 client call against `/ready` if your Ruby HTTP client supports h2c. ================================================================================ PAGE: https://reactonrails.com/docs/building-features/node-renderer/debugging SOURCE: docs/oss/building-features/node-renderer/debugging.md ================================================================================ # Node Renderer Debugging > **Pro Feature** — Available with [React on Rails Pro](../../../pro/react-on-rails-pro.md). > Free or very low cost for startups and small companies. [Upgrade or licensing details →](../../../pro/upgrading-to-pro.md#try-pro-risk-free) Because the renderer communicates over a port to Rails, you can start a local renderer instance with Node's inspector and debug the server-rendered JavaScript directly. Use this page for breakpoints, renderer logs, and memory snapshots. For CPU flamegraphs, use [Profiling Server-Side Rendering Code](../../../pro/profiling-server-side-rendering-code.md). For React 19.2 Performance Tracks, hydration traces, and choosing the right profiling tool, use [React Performance Tracks and Profiling](../performance-tracks-and-profiling.md). ## Monorepo Workflow For renderer debugging inside this repo, use the Pro dummy app at `react_on_rails_pro/spec/dummy`. It is a `pnpm` workspace app and already points at the local packages in this monorepo. ## Source-Mapped Stack Traces When an SSR error occurs, the renderer remaps stack frames to the original TypeScript/JavaScript `file:line:column` — both in the error returned to Rails (surfaced as `ReactOnRails::PrerenderError` / renderer error messages) and in the renderer logs. This works automatically when the server bundle includes a source map: - **Inline map (simplest):** build the server bundle with `devtool: 'inline-source-map'` (webpack and Rspack). The map travels inside the bundle, so nothing else needs to be uploaded. Inline maps grow the server bundle file, but the server bundle is never served to browsers, so the cost is only disk space and upload size between Rails and the renderer. - **External map:** with `devtool: 'source-map'`, make the `.map` file available next to the uploaded bundle in the renderer's bundle cache directory. The renderer accepts a filename-only `//# sourceMappingURL=` reference next to the bundle, including trusted pre-staged symlink entries created by Pro cache staging, and also checks for `<uploaded-bundle>.js.map`. Never serve server-bundle source maps publicly. External source map text is captured asynchronously while the VM builds so active requests keep using the map generation they started with. The map is parsed and applied lazily on the first error and cached per bundle generation, so normal requests do not pay stack-formatting cost. If no source map is found, stack traces still name the real bundle file path and line. ## Debugging the Node Renderer ### Quick start: debugging with the full stack running If you already have the dummy app running via `bin/dev` (which uses `Procfile.dev`), the node renderer is listening on port 3800 without `--inspect`. To attach a debugger, restart only the renderer with the inspector enabled: ```bash cd react_on_rails_pro/spec/dummy overmind stop node-renderer pnpm run node-renderer:debug ``` Keep that terminal open while you debug. Then: 1. Open `chrome://inspect` in Chrome and connect to the renderer process. 2. Watch renderer logs in that terminal. Keep `bin/dev` visible for Rails logs. 3. Set breakpoints in the inspector and reload the page that triggers SSR. 4. After a server-bundle or renderer change, press Ctrl-C and rerun `pnpm run node-renderer:debug`. If you prefer to keep the renderer under Overmind, temporarily add `--inspect` to the `node-renderer:` entry in `Procfile.dev`, then run `overmind restart node-renderer`. ### Isolated debugging: manual per-terminal startup Use this when you need full control over the renderer process — different flags, a specific bundle, or rebuilding just the renderer package. 1. From the repo root, install dependencies and build the local packages: ```bash pnpm install pnpm run build ``` 1. In one terminal, start the Pro dummy bundle watcher: ```bash cd react_on_rails_pro/spec/dummy pnpm run build:dev:watch ``` 1. In another terminal, start the renderer with verbose logging: ```bash cd react_on_rails_pro/spec/dummy RENDERER_LOG_LEVEL=debug pnpm run node-renderer ``` 1. If you want to attach a debugger instead, run: ```bash cd react_on_rails_pro/spec/dummy pnpm run node-renderer:debug ``` 1. Reload the page that triggers the SSR issue and reproduce the problem. 1. If you change Ruby code in loaded gems, restart the Rails server. 1. If you change code under `packages/react-on-rails-pro-node-renderer`, rebuild that package before restarting the renderer: ```bash pnpm --filter react-on-rails-pro-node-renderer run build ``` 1. If you are debugging an external app instead of the monorepo dummy app, refresh the installed renderer package using your local package workflow (for example `yalc`, `npm pack`, or a workspace link) before rerunning the renderer. ### Breakpoints vs. profiles - Use `--inspect` breakpoints when you need to inspect props, globals, module state, or the exact branch taken during SSR. - Use [the SSR profiling guide](../../../pro/profiling-server-side-rendering-code.md) when the code is correct but slow. - Use [React Performance Tracks and Profiling](../performance-tracks-and-profiling.md) when the slow path includes browser hydration, Suspense, RSC timing, or client interactions. - Use [Error Reporting and Tracing](./error-reporting-and-tracing.md) or [OpenTelemetry](../../../pro/node-renderer.md#observability-with-opentelemetry) for production request spans. ## Debugging Memory Leaks If worker memory grows over time, use heap snapshots to find the source. ### Quick approach: `--heapsnapshot-signal` (no code changes) Use Node's built-in flag to write heap snapshots on demand: ```bash cd react_on_rails_pro/spec/dummy # Adjust the port if your Rails app points at a different renderer URL. NODE_OPTIONS="--heapsnapshot-signal=SIGUSR2" RENDERER_PORT=3800 node renderer/node-renderer.js ``` Then capture snapshots at different times: ```bash kill -USR2 <worker-pid> # writes a .heapsnapshot file to the working directory ``` This also works in production containers — set `NODE_OPTIONS="--heapsnapshot-signal=SIGUSR2"` as an environment variable, send the signal at different times, then copy the `.heapsnapshot` files to your local machine for analysis. ### Detailed approach: with forced GC For more precise results, start the renderer with `--expose-gc` and a custom signal handler that forces garbage collection before each snapshot. See the [Memory Leaks guide](../../../pro/js-memory-leaks.md#2-take-v8-heap-snapshots) for the code. ### Analyzing snapshots 1. Load both `.heapsnapshot` files in Chrome DevTools (Memory tab → Load). 2. Use the **Comparison** view to see which objects accumulated between snapshots. 3. Look for growing `string`, `Object`, and `Array` counts — these typically point to module-level caches. ### Isolating memory issues with a separate renderer workload When diagnosing memory leaks in a containerized environment, running the Node renderer as a separate workload (instead of a sidecar) makes it easier to: - Monitor Node memory independently from Rails - Capture heap snapshots without affecting the Rails process - Restart or scale the renderer without restarting Rails See the [Memory Leaks guide](../../../pro/js-memory-leaks.md) for common patterns and fixes. ## Debugging Jest tests 1. See [the Jest documentation](https://jestjs.io/docs/troubleshooting) for overall guidance. 2. For JetBrains IDEs, see [the RubyMine documentation](https://www.jetbrains.com/help/ruby/running-unit-tests-on-jest.html) for current instructions. ## Debugging the Ruby gem Open the gemfile in the problematic app. ```ruby gem "react_on_rails_pro", path: "../../../shakacode/react-on-rails/react_on_rails_pro" ``` Optionally, also specify react_on_rails to be local: ```ruby gem "react_on_rails", path: "../../../shakacode/react-on-rails/react_on_rails" ``` ================================================================================ PAGE: https://reactonrails.com/docs/building-features/node-renderer/error-reporting-and-tracing SOURCE: docs/oss/building-features/node-renderer/error-reporting-and-tracing.md ================================================================================ # Error Reporting and Tracing > **Pro Feature** — Available with [React on Rails Pro](../../../pro/react-on-rails-pro.md). > Free or very low cost for startups and small companies. [Upgrade or licensing details →](../../../pro/upgrading-to-pro.md#try-pro-risk-free) For versions before 4.0.0, error reporting was configured via `honeybadgerApiKey` and `sentryDsn` options. These options were removed in 4.0.0 and will cause an error if used. See the current integration approach below. To integrate with error reporting and tracing services, you need a custom configuration script as described in [Node Renderer JavaScript Configuration](./js-configuration.md). It should initialize the services according to your requirements and then enable integrations. ## Sentry 1. [Set up Sentry](https://docs.sentry.io/platforms/javascript/guides/fastify/). You may create an `instrument.js` file as described there and require it in your configuration script, but it is simpler to call `Sentry.init` directly in your configuration script. 2. Call `Sentry.init` with the desired options according to [the documentation](https://docs.sentry.io/platforms/javascript/guides/fastify/configuration/). 3. Then load the integration: ```js require('react-on-rails-pro-node-renderer/integrations/sentry').init(); ``` - Use `react-on-rails-pro-node-renderer/integrations/sentry6` instead of `.../sentry` for versions of Sentry SDK older than 7.63.0. - For Sentry SDK v8+ you can use `.init({ fastify: true })` to capture additional Fastify-related information. ### Sentry Tracing To enable Sentry Tracing: 1. Include `enableTracing`, `tracesSampleRate`, or `tracesSampler` in your `Sentry.init` call. See [the Sentry documentation](https://docs.sentry.io/platforms/javascript/tracing/) for details, but ignore `Sentry.browserTracingIntegration()`. 2. Depending on your Sentry SDK version: - if it is older than 7.63.0, install `@sentry/tracing` as well as `@sentry/node` (with the same exact version) and pass `integrations: [new Sentry.Integrations.Http({ tracing: true })]` to `Sentry.init`. - for newer v7.x.y, pass `integrations: Sentry.autoDiscoverNodePerformanceMonitoringIntegrations()`. - for v8.x.y, Node HTTP tracing is included by default. 3. Pass `{ tracing: true }` to the `init` function of the integration. It can be combined with `fastify: true`. ### Sentry Profiling [Follow this documentation](https://docs.sentry.io/platforms/javascript/guides/fastify/profiling/). ## Honeybadger 1. [Set up Honeybadger](https://docs.honeybadger.io/lib/javascript/integration/node/). Call `Honeybadger.configure` with the desired options in the configuration script. 2. Then load the integration: ```js require('react-on-rails-pro-node-renderer/integrations/honeybadger').init(); ``` Use `init({ fastify: true })` to capture additional Fastify-related information. ## Other services You can create your own integrations in the same way as the provided ones. You can use [the built-in implementations](https://github.com/shakacode/react_on_rails/tree/main/packages/react-on-rails-pro-node-renderer/src/integrations) as examples. Import these functions from `react-on-rails-pro-node-renderer/integrations/api`: ### Error reporting services - `addErrorNotifier` and `addMessageNotifier` tell React on Rails Pro how to report errors to your chosen service. - Use `addNotifier` if the service uses the same reporting function for both JavaScript `Error`s and string messages. For example, integrating with BugSnag can be as simple as ```js const Bugsnag = require('@bugsnag/js'); const { addNotifier } = require('react-on-rails-pro-node-renderer/integrations/api'); Bugsnag.start({ /* your options */ }); addNotifier((msg) => { Bugsnag.notify(msg); }); ``` ### Tracing services - `setupTracing` takes an object with two properties: - `executor` should wrap an async function in the service's unit of work. - Since the only units of work we currently track are rendering requests, the options to start them are specified in `startSsrRequestOptions`. To track requests as sessions in BugSnag 8.x+, the above example becomes ```js const Bugsnag = require('@bugsnag/js'); const { addNotifier, setupTracing } = require('react-on-rails-pro-node-renderer/integrations/api'); Bugsnag.start({ /* your options */ }); addNotifier((msg) => { Bugsnag.notify(msg); }); setupTracing({ executor: async (fn) => { Bugsnag.startSession(); try { return await fn(); } finally { Bugsnag.pauseSession(); } }, }); ``` You can optionally add `startSsrRequestOptions` property to capture the request data: ```js setupTracing({ startSsrRequestOptions: ({ renderingRequest }) => ({ bugsnag: { renderingRequest } }), executor: async (fn, { bugsnag }) => { Bugsnag.startSession(); // bugsnag will look like { renderingRequest } Bugsnag.leaveBreadcrumb('SSR request', bugsnag, 'request'); try { return await fn(); } finally { Bugsnag.pauseSession(); } }, }); ``` Bugsnag v7 is a bit more complicated: ```js const Bugsnag = require('@bugsnag/js'); const { addNotifier, setupTracing } = require('react-on-rails-pro-node-renderer/integrations/api'); Bugsnag.start({ /* your options */ }); addNotifier((msg, { bugsnag = Bugsnag }) => { bugsnag.notify(msg); }); setupTracing({ executor: async (fn) => { const bugsnag = Bugsnag.startSession(); try { return await fn({ bugsnag }); } finally { bugsnag.pauseSession(); } }, }); ``` ### Fastify integrations If you want to report HTTP requests from Fastify, you can use `configureFastify` to add hooks or plugins as necessary. Extending the above example: ```js const { configureFastify } = require('react-on-rails-pro-node-renderer/integrations/api'); configureFastify((app) => { app.addHook('onError', (_req, _reply, error, done) => { Bugsnag.notify(error); done(); }); }); ``` You could also treat Fastify requests as sessions using [onRequest](https://fastify.dev/docs/latest/Reference/Hooks/#onrequest) or [preHandler](https://fastify.dev/docs/latest/Reference/Hooks/#prehandler) hooks. It isn't recommended to use the [fastify-bugsnag](https://github.com/ZigaStrgar/fastify-bugsnag) plugin since it wants to start Bugsnag on its own. ================================================================================ PAGE: https://reactonrails.com/docs/building-features/node-renderer/heroku SOURCE: docs/oss/building-features/node-renderer/heroku.md ================================================================================ # Node Renderer: Heroku Deployment > **Pro Feature** — Available with [React on Rails Pro](../../../pro/react-on-rails-pro.md). > Free or very low cost for startups and small companies. [Upgrade or licensing details →](../../../pro/upgrading-to-pro.md#try-pro-risk-free) Most React on Rails Pro installations of the Node SSR Renderer will deploy the Rails and Renderer instances on the same server. This technique results in better performance since it avoids network latency. Scroll down if you want to have different servers. ## Deploying to the Same Server As Your App Server [buildpack for runit](https://github.com/danp/heroku-buildpack-runit) ### Procfile `/Procfile` ```text web: bin/runsvdir-dyno ``` ### Procfile.web `/Procfile.web` Your `/Procfile.web` should keep the `puma` line and use the `renderer` line that matches your package manager: | Package manager | `renderer` line | | --------------- | ---------------------------------- | | npm | `renderer: npm run node-renderer` | | yarn | `renderer: yarn run node-renderer` | | pnpm | `renderer: pnpm run node-renderer` | For example, a complete `/Procfile.web` using pnpm: ```text puma: bundle exec puma -C config/puma.rb renderer: pnpm run node-renderer ``` Define the script in your root `package.json` so Heroku can run it from the app root: ```json { "scripts": { "node-renderer": "node renderer/node-renderer.js" } } ``` > **Note:** The script above relies on the default > `port: process.env.RENDERER_PORT || 3800` in the JS configuration example. That default is fine > for the same-dyno deployment above. If you deploy the renderer as a separate Heroku app, switch > the renderer config to `process.env.PORT` instead of `RENDERER_PORT`. Be sure your node-renderer script listens on the same port as the Rails `config.renderer_url` value, for example `http://localhost:3800`. ### Modifying Precompile Task _Not necessary if you are using [bundle caching](../bundle-caching.md) as doing so will result in the below being done automatically._ To avoid the initial round trip to get a bundle on the renderer, you can pre-stage the renderer cache during precompile. See [lib/tasks/assets.rake](https://github.com/shakacode/react_on_rails/blob/main/react_on_rails_pro/lib/tasks/assets.rake) for a couple tasks that you can use. For same-dyno / same-filesystem deployments such as Heroku, the legacy `react_on_rails_pro:pre_stage_bundle_for_node_renderer` task is still appropriate. It pre-stages the same bundle-hash cache layout the renderer uses at runtime, but does so with symlinks instead of copies. Prefer `react_on_rails_pro:pre_seed_renderer_cache` for Docker/image-build workflows where the cache needs to be copied into an immutable artifact. If you're not using the default cache location, set `RENDERER_SERVER_BUNDLE_CACHE_PATH` so the files stage into the right place. `RENDERER_BUNDLE_PATH` remains a deprecated compatibility alias. Then you can use the rake task: `react_on_rails_pro:pre_seed_renderer_cache MODE=symlink`. You might do something like this: ```ruby Rake::Task["assets:precompile"] .clear_prerequisites .enhance([:environment, "react_on_rails:assets:compile_environment"]) .enhance do ReactOnRailsPro::PreSeedRendererCache.call(mode: :symlink) end ``` ## Troubleshooting If you get this sort of error, then you're forgetting to configure the PORT on the node-renderer and setting the config.renderer_url on the Rails App. ```text bundler: failed to load command: puma (/app/vendor/bundle/ruby/2.6.0/bin/puma) Errno::EADDRINUSE: Address already in use - bind(2) for "0.0.0.0" port 21752 /app/vendor/bundle/ruby/2.6.0/gems/puma-4.3.3/lib/puma/binder.rb:229:in `initialize' ``` ## Separate Rails and Node Render Instances ### Deploy Node renderer to Heroku 1. Create your **Heroku** app with **Node.js** buildpack, say `renderer-test.herokuapp.com`. 2. In your JS configuration file or 1. If setting the port, ensure the port uses `process.env.PORT` so it will use port number provided by **Heroku** environment. The default is to use the env value `RENDERER_PORT` if available. 2. Set password in your configuration to something like `process.env.RENDERER_PASSWORD` and configure the corresponding **ENV variable** on your **Heroku** dyno so the `config/initializers/react_on_rails_pro.rb` uses this value. 3. Run deployment process (usually by pushing changes to **Git** repo associated with created **Heroku** app). 4. Once deployment process is finished, renderer should start listening from something like `renderer-test.herokuapp.com` host. ### Deploy react_on_rails application to Heroku 1. Create your **Heroku** app for `react_on_rails`. 2. Configure your app to communicate with renderer app you've created above. Put the following to your `initializers/react_on_rails_pro` (assuming you have **SSL** certificate uploaded to your renderer **Heroku** app or you use **Heroku** wildcard certificate under `*.herokuapp.com`) and configure corresponding **ENV variable** for the render_url and/or password on your **Heroku** dyno. 3. Run deployment process (usually by pushing changes to **Git** repo associated with created **Heroku** app). 4. Once deployment process is finished, all rendering requests form your `react_on_rails` app should be served by `<your-heroku-app>.herokuapp.com` app via **HTTPS**. ## References - [Heroku Node Settings](https://github.com/damianmr/heroku-node-settings) ================================================================================ PAGE: https://reactonrails.com/docs/building-features/node-renderer/troubleshooting SOURCE: docs/oss/building-features/node-renderer/troubleshooting.md ================================================================================ # Node Renderer Troubleshooting > **Pro Feature** — Available with [React on Rails Pro](../../../pro/react-on-rails-pro.md). > Free or very low cost for startups and small companies. [Upgrade or licensing details →](../../../pro/upgrading-to-pro.md#try-pro-risk-free) For node renderer troubleshooting (connection refused, memory issues, worker restarts), see the [Node Renderer section in the main troubleshooting guide](../../../pro/troubleshooting.md#node-renderer). ================================================================================ PAGE: https://reactonrails.com/docs/reference/error-reference SOURCE: docs/oss/reference/error-reference.md ================================================================================ <!-- GENERATED FILE - DO NOT EDIT DIRECTLY. --> <!-- Regenerate with: BUNDLE_GEMFILE=react_on_rails/Gemfile bundle exec ruby script/generate_error_reference.rb --> <!-- Source: react_on_rails/lib/react_on_rails/smart_error.rb --> # Error Reference React on Rails SmartError messages include stable `ROR###` codes and canonical URLs. Use this page to look up a code from a terminal error, server log, or support request. Error codes are append-only once published: do not reuse a removed code for a different failure. ## Code Index | Code | Error | SmartError type | | ----------------- | -------------------------------- | ----------------------------------- | | [ROR001](#ror001) | Component Not Registered | `:component_not_registered` | | [ROR002](#ror002) | Auto-loaded Bundle Missing | `:missing_auto_loaded_bundle` | | [ROR003](#ror003) | Auto-loaded Store Bundle Missing | `:missing_auto_loaded_store_bundle` | | [ROR004](#ror004) | Hydration Mismatch | `:hydration_mismatch` | | [ROR005](#ror005) | Server Rendering Failed | `:server_rendering_error` | | [ROR006](#ror006) | Redux Store Not Found | `:redux_store_not_found` | | [ROR007](#ror007) | Configuration Error | `:configuration_error` | <a id="ror001"></a> ## ROR001: Component Not Registered **SmartError type:** `:component_not_registered` **Canonical URL:** https://reactonrails.com/docs/reference/error-reference#ror001 React on Rails could not find the component in the client-side component registry. ### Example SmartError Output ```text ❌ React on Rails Error [ROR001]: Component 'ProductCard' Not Registered Component 'ProductCard' was not found in the component registry. React on Rails offers two approaches: • Auto-bundling (recommended): Components load automatically, no registration needed • Manual registration: Traditional approach requiring explicit registration Code: ROR001 Docs: https://reactonrails.com/docs/reference/error-reference#ror001 💡 Suggested Solution: 🚀 Recommended: Use Auto-Bundling (No Registration Required!) 1. Enable auto-bundling in your view: <%= react_component("ProductCard", props: {}, auto_load_bundle: true) %> 2. Place your component in the components directory: app/javascript/components/ProductCard/ProductCard.jsx Component structure: components/ └── ProductCard/ └── ProductCard.jsx (must export default) 3. Generate the bundle: bundle exec rake react_on_rails:generate_packs ✨ That's it! No manual registration needed. ───────────────────────────────────────────── Alternative: Manual Registration If you prefer manual registration: 1. Register in your entry file: ReactOnRails.register({ ProductCard: ProductCard }); 2. Import the component: import ProductCard from './components/ProductCard'; 📋 Context: Component: ProductCard Registered components: ProductList, ProductDetails, UserProfile Rails Environment: development (detailed errors enabled) 🔧 Need More Help? 📞 Get Help & Support: • 🚀 Professional Support: react_on_rails@shakacode.com (fastest resolution) • 💬 React + Rails Slack: https://invite.reactrails.com • 🆓 GitHub Issues: https://github.com/shakacode/react_on_rails/issues • 📖 Discussions: https://github.com/shakacode/react_on_rails/discussions ``` <a id="ror002"></a> ## ROR002: Auto-loaded Bundle Missing **SmartError type:** `:missing_auto_loaded_bundle` **Canonical URL:** https://reactonrails.com/docs/reference/error-reference#ror002 A component is configured for auto-loading, but its generated bundle is missing. ### Example SmartError Output ```text ❌ React on Rails Error [ROR002]: Auto-loaded Bundle Missing Component 'Dashboard' is configured for auto-loading but its bundle is missing. Expected location: app/javascript/packs/generated/Dashboard.js Code: ROR002 Docs: https://reactonrails.com/docs/reference/error-reference#ror002 💡 Suggested Solution: 1. Run the pack generation task: bundle exec rake react_on_rails:generate_packs 2. Ensure your component is in the correct directory: app/javascript/components/Dashboard/ 3. Check that the component file follows naming conventions: - Component file: Dashboard.jsx or Dashboard.tsx - Must export default 4. Verify webpack/shakapacker is configured for nested entries: config.nested_entries_dir = 'components' 📋 Context: Component: Dashboard Rails Environment: development (detailed errors enabled) 🔧 Need More Help? 📞 Get Help & Support: • 🚀 Professional Support: react_on_rails@shakacode.com (fastest resolution) • 💬 React + Rails Slack: https://invite.reactrails.com • 🆓 GitHub Issues: https://github.com/shakacode/react_on_rails/issues • 📖 Discussions: https://github.com/shakacode/react_on_rails/discussions ``` <a id="ror003"></a> ## ROR003: Auto-loaded Store Bundle Missing **SmartError type:** `:missing_auto_loaded_store_bundle` **Canonical URL:** https://reactonrails.com/docs/reference/error-reference#ror003 A Redux store is configured for auto-loading, but its generated store bundle is missing. ### Example SmartError Output ```text ❌ React on Rails Error [ROR003]: Auto-loaded Store Bundle Missing Redux store 'AppStore' is configured for auto-loading but its bundle is missing. Expected location: app/javascript/packs/generated/AppStore.js Code: ROR003 Docs: https://reactonrails.com/docs/reference/error-reference#ror003 💡 Suggested Solution: 1. Run the pack generation task: bundle exec rake react_on_rails:generate_packs 2. Ensure your store is in a directory matching stores_subdirectory under packer_source_path: app/javascript/**/ror_stores/AppStore.js 3. Check that the store file follows naming conventions: - Store file: AppStore.js or AppStore.ts - Must export default a store generator function 4. Verify stores_subdirectory is configured: config.stores_subdirectory = 'ror_stores' 📋 Context: Component: AppStore Rails Environment: development (detailed errors enabled) 🔧 Need More Help? 📞 Get Help & Support: • 🚀 Professional Support: react_on_rails@shakacode.com (fastest resolution) • 💬 React + Rails Slack: https://invite.reactrails.com • 🆓 GitHub Issues: https://github.com/shakacode/react_on_rails/issues • 📖 Discussions: https://github.com/shakacode/react_on_rails/discussions ``` <a id="ror004"></a> ## ROR004: Hydration Mismatch **SmartError type:** `:hydration_mismatch` **Canonical URL:** https://reactonrails.com/docs/reference/error-reference#ror004 The server-rendered HTML does not match the React tree rendered in the browser. ### Example SmartError Output ```text ❌ React on Rails Error [ROR004]: Hydration Mismatch The server-rendered HTML doesn't match what React rendered on the client. Component: UserProfile Code: ROR004 Docs: https://reactonrails.com/docs/reference/error-reference#ror004 💡 Suggested Solution: Common causes and solutions: 1. **Random IDs or timestamps**: Use consistent values between server and client // Bad: Math.random() or Date.now() // Good: Use props or deterministic values 2. **Browser-only APIs**: Check for client-side before using: if (typeof window !== 'undefined') { ... } 3. **Different data**: Ensure props are identical on server and client - Check your redux store initialization - Verify railsContext is consistent 4. **Conditional rendering**: Avoid using user agent or viewport checks Debug tips: - Set prerender: false temporarily to isolate the issue - Check browser console for hydration warnings - Compare server HTML with client render 📋 Context: Component: UserProfile Rails Environment: development (detailed errors enabled) 🔧 Need More Help? 📞 Get Help & Support: • 🚀 Professional Support: react_on_rails@shakacode.com (fastest resolution) • 💬 React + Rails Slack: https://invite.reactrails.com • 🆓 GitHub Issues: https://github.com/shakacode/react_on_rails/issues • 📖 Discussions: https://github.com/shakacode/react_on_rails/discussions ``` <a id="ror005"></a> ## ROR005: Server Rendering Failed **SmartError type:** `:server_rendering_error` **Canonical URL:** https://reactonrails.com/docs/reference/error-reference#ror005 Server-side rendering failed while rendering a React component. ### Example SmartError Output ```text ❌ React on Rails Error [ROR005]: Server Rendering Failed An error occurred while server-side rendering component 'ComplexComponent'. window is not defined Code: ROR005 Docs: https://reactonrails.com/docs/reference/error-reference#ror005 💡 Suggested Solution: 1. Check your JavaScript console output: tail -f log/development.log | grep 'React on Rails' 2. Common issues: - Missing Node.js dependencies: cd client && npm install - Syntax errors in component code - Using browser-only APIs without checks 3. Debug server rendering: - Set config.trace = true in your configuration - Set config.development_mode = true for better errors - Check config.server_bundle_js_file points to correct file 4. Verify your server bundle: bin/shakapacker or bin/webpack 📋 Context: Component: ComplexComponent Rails Environment: development (detailed errors enabled) 🔧 Need More Help? 📞 Get Help & Support: • 🚀 Professional Support: react_on_rails@shakacode.com (fastest resolution) • 💬 React + Rails Slack: https://invite.reactrails.com • 🆓 GitHub Issues: https://github.com/shakacode/react_on_rails/issues • 📖 Discussions: https://github.com/shakacode/react_on_rails/discussions ``` <a id="ror006"></a> ## ROR006: Redux Store Not Found **SmartError type:** `:redux_store_not_found` **Canonical URL:** https://reactonrails.com/docs/reference/error-reference#ror006 A component requested a Redux store that was not registered. ### Example SmartError Output ```text ❌ React on Rails Error [ROR006]: Redux Store Not Found Redux store 'AppStore' was not found. Available stores: UserStore, ProductStore Code: ROR006 Docs: https://reactonrails.com/docs/reference/error-reference#ror006 💡 Suggested Solution: 1. Register your Redux store: ReactOnRails.registerStore({ AppStore: AppStore }); 2. Ensure the store is imported: import AppStore from './store/AppStore'; 3. Initialize the store before rendering components that depend on it: <%= redux_store('AppStore', props: {}) %> 4. Check store dependencies in your component: store_dependencies: ['AppStore'] 📋 Context: Rails Environment: development (detailed errors enabled) 🔧 Need More Help? 📞 Get Help & Support: • 🚀 Professional Support: react_on_rails@shakacode.com (fastest resolution) • 💬 React + Rails Slack: https://invite.reactrails.com • 🆓 GitHub Issues: https://github.com/shakacode/react_on_rails/issues • 📖 Discussions: https://github.com/shakacode/react_on_rails/discussions ``` <a id="ror007"></a> ## ROR007: Configuration Error **SmartError type:** `:configuration_error` **Canonical URL:** https://reactonrails.com/docs/reference/error-reference#ror007 React on Rails detected invalid or incomplete configuration. ### Example SmartError Output ```text ❌ React on Rails Error [ROR007]: Configuration Error Invalid configuration detected. config.server_bundle_js_file points to a missing file Code: ROR007 Docs: https://reactonrails.com/docs/reference/error-reference#ror007 💡 Suggested Solution: Review your React on Rails configuration: 1. Check config/initializers/react_on_rails.rb 2. Common configuration issues: - Invalid bundle paths - Missing Node modules location - Incorrect component subdirectory 3. Run configuration doctor: rake react_on_rails:doctor 📋 Context: Rails Environment: development (detailed errors enabled) 🔧 Need More Help? 📞 Get Help & Support: • 🚀 Professional Support: react_on_rails@shakacode.com (fastest resolution) • 💬 React + Rails Slack: https://invite.reactrails.com • 🆓 GitHub Issues: https://github.com/shakacode/react_on_rails/issues • 📖 Discussions: https://github.com/shakacode/react_on_rails/discussions ``` ================================================================================ PAGE: https://reactonrails.com/docs/configuration SOURCE: docs/oss/configuration/README.md ================================================================================ # React on Rails Configuration Options This document describes all configuration options for React on Rails. Configuration is done in `/config/initializers/react_on_rails.rb`. > [!NOTE] > **Summary for AI agents:** Use this page for OSS configuration options. Most apps only need 2-3 settings. For Pro-specific options (Node renderer, fragment caching, prerender caching, streaming SSR), see [Pro configuration](./configuration-pro.md). > **Good News!** Most applications only need 2-3 configuration options. React on Rails provides sensible defaults for everything else. :::tip Pro Configuration React on Rails Pro adds additional configuration options for the Node renderer, fragment caching, prerender caching, and streaming SSR. See [Pro configuration options](./configuration-pro.md) for the full reference. ::: ## Quick Start See [Essential Configuration](#essential-configuration) below for the minimal configuration options you'll commonly use. Most applications only need 1-2 settings! ## Prerequisites ### `/config/shakapacker.yml` First, you should have a `/config/shakapacker.yml` setup. Here is the setup when using the recommended `/` directory for your `node_modules` and source files: ```yaml # Note: Base output directory of /public is assumed for static files default: &default compile: false # Used in your Webpack configuration. Must be created in the # public_output_path folder manifest: manifest.json cache_manifest: false # Source path is used to check if Webpack compilation needs to be run for `compile: true` source_path: client/app development: <<: *default # Generated files for development, in /public/webpack/dev public_output_path: webpack/dev test: <<: *default # For ReactOnRails::TestHelper + build_test_command (recommended), keep compile false. # If you prefer Shakapacker auto-compilation instead, set compile: true and remove # TestHelper/build_test_command wiring. compile: false # Generated files for tests, in /public/webpack/test. # Keep this separate from development output so each environment has its own # manifest.json and HMR/dev assets never overwrite test assets. public_output_path: webpack/test production: <<: *default # Generated files for production, in /public/webpack/production public_output_path: webpack/production cache_manifest: true ``` ## Configuration Categories React on Rails configuration options are organized into two categories: ### Essential Configuration Options you'll commonly configure for most applications: - `server_bundle_js_file` - Server rendering bundle (recommended) - `build_test_command` - Test environment build command (used with ReactOnRails::TestHelper) ### Advanced Configuration Options with sensible defaults that rarely need changing: - Component loading strategies (auto-configured based on Pro license) - Server bundle security and organization - I18n configuration - Server rendering pool settings - Custom rendering extensions - And more... See sections below for complete documentation of all options. ## Essential Configuration Here's a representative `/config/initializers/react_on_rails.rb` setup for essential options: ```ruby # frozen_string_literal: true ReactOnRails.configure do |config| ################################################################################ # Server Rendering (Recommended) ################################################################################ # This is the file used for server rendering of React when using `prerender: true` # Set to "" if you are not using server rendering config.server_bundle_js_file = "server-bundle.js" ################################################################################ # Test Configuration # Used with ReactOnRails::TestHelper: # - RSpec: ReactOnRails::TestHelper.configure_rspec_to_compile_assets(config) # - Minitest: ReactOnRails::TestHelper.ensure_assets_compiled # This controls what command is run to build assets during tests ################################################################################ config.build_test_command = "RAILS_ENV=test bin/shakapacker" # # React Server Components and Streaming SSR are React on Rails Pro features. # For detailed configuration of RSC and streaming features, see: # See docs/oss/configuration/configuration-pro.md for complete Pro configuration reference # # Key Pro configurations (configured in ReactOnRailsPro.configure block): # - rsc_bundle_js_file: Path to RSC bundle # - react_client_manifest_file: Client component manifest for RSC # - react_server_client_manifest_file: Server manifest for RSC # - enable_rsc_support: Enable React Server Components # # See Pro documentation for complete setup instructions. ################################################################################ # SERVER BUNDLE SECURITY AND ORGANIZATION ################################################################################ # ⚠️ RECOMMENDED: Use Shakapacker 9.0+ for Automatic Configuration # # For Shakapacker 9.0+, add to config/shakapacker.yml: # private_output_path: ssr-generated # # React on Rails will automatically detect and use this value, eliminating the need # to configure server_bundle_output_path here. This provides a single source of truth. # # For older Shakapacker versions or custom setups, manually configure: # This configures the directory (relative to the Rails root) where the server bundle will be output. # By default, this is "ssr-generated". If set to nil, the server bundle will be loaded from the same # public directory as client bundles. For enhanced security, use this option in conjunction with # `enforce_private_server_bundles` to ensure server bundles are only loaded from private directories # config.server_bundle_output_path = "ssr-generated" # When set to true, React on Rails will only load server bundles from private, explicitly # configured directories (such as `ssr-generated`), and will raise an error if a server # bundle is found in a public or untrusted location. This helps prevent accidental or # malicious execution of untrusted JavaScript on the server, and is strongly recommended # for production environments. Also prevents leakage of server-side code to the client # (especially important for React Server Components). # Default is false for backward compatibility, but enabling this option is a best practice # for security. config.enforce_private_server_bundles = false ################################################################################ # BUNDLE ORGANIZATION EXAMPLES ################################################################################ # # This configuration creates a clear separation between client and server assets: # # CLIENT BUNDLES (Public, Web-Accessible): # Location: public/webpack/[environment]/ or public/packs/ (According to your shakapacker.yml configuration) # Files: application.js, manifest.json, CSS files # Served by: Web server directly # Access: ReactOnRails::Utils.public_bundles_full_path # # SERVER BUNDLES (Private, Server-Only): # Location: ssr-generated/ (when server_bundle_output_path configured) # Files: server-bundle.js, rsc-bundle.js # Served by: Never served to browsers # Access: ReactOnRails::Utils.server_bundle_js_file_path # # Example directory structure with recommended configuration: # app/ # ├── ssr-generated/ # Private server bundles # │ ├── server-bundle.js # │ └── rsc-bundle.js # └── public/ # └── webpack/development/ # Public client bundles # ├── application.js # ├── manifest.json # └── styles.css # ################################################################################ # `prerender` means server-side rendering # default is false. This is an option for view helpers `render_component` and `render_component_hash`. # Set to true to change the default value to true. config.prerender = false # THE BELOW OPTIONS FOR SERVER-SIDE RENDERING RARELY NEED CHANGING # # This value only affects server-side rendering when using the webpack-dev-server # If you are hashing the server bundle and you want to use the same bundle for client and server, # you'd set this to `true` so that React on Rails reads the server bundle from the webpack-dev-server. # Normally, you have different bundles for client and server, thus, the default is false. # Furthermore, if you are not hashing the server bundle (not in the manifest.json), then React on Rails # will only look for the server bundle to be created in the typical file location, typically by # a `shakapacker --watch` process. # If true, ensure that in config/shakapacker.yml you set dev_server.hmr to false. config.same_bundle_for_client_and_server = false # If set to true, this forces Rails to reload the server bundle if it is modified # Default value is Rails.env.development? # You probably will never change this. config.development_mode = Rails.env.development? # For server rendering so that the server-side console replays in the browser console. # This can be set to false so that server side messages are not displayed in the browser. # Default is true. Be cautious about turning this off, as it can make debugging difficult. # Default value is true config.replay_console = true # Default is true. Logs server rendering messages to Rails.logger.info. If false, you'll only # see the server rendering messages in the browser console. config.logging_on_server = true # Default is true only for development? to raise exception on server if the JS code throws for # server rendering. The reason is that the server logs will show the error and force you to fix # any server rendering issues immediately during development. config.raise_on_prerender_error = Rails.env.development? # This configuration allows logic to be applied to client rendered props, such as stripping props that are only used during server rendering. # Add a module with an adjust_props_for_client_side_hydration method that expects the component's name & props hash # See below for an example definition of RenderingPropsExtension config.rendering_props_extension = RenderingPropsExtension ################################################################################ # Server Renderer Configuration for ExecJS ################################################################################ # The default server rendering is ExecJS, by default using Node.js runtime # If you wish to use an alternative Node server rendering for higher performance, # contact justin@shakacode.com for details. # # For ExecJS: # You can configure your pool of JS virtual machines and specify where it should load code: # On MRI, use `node.js` runtime for the best performance # (see https://github.com/shakacode/react_on_rails/issues/1438) # Also see https://github.com/shakacode/react_on_rails/issues/1457#issuecomment-1165026717 if using `mini_racer` # On MRI, you'll get a deadlock with `pool_size` > 1 # If you're using JRuby, you can increase `pool_size` to have real multi-threaded rendering. config.server_renderer_pool_size = 1 # increase if you're on JRuby config.server_renderer_timeout = 20 # seconds ################################################################################ ################################################################################ # FILE SYSTEM BASED COMPONENT REGISTRY # `render_component` and `render_component_hash` view helper methods can # auto-load the bundle for the generated component, to avoid having to specify the # bundle manually for each view with the component. # # SHAKAPACKER VERSION REQUIREMENTS: # - Basic pack generation: Shakapacker 6.5.1+ # - Advanced auto-registration with nested entries: Shakapacker 7.0.0+ # - Async loading support: Shakapacker 8.2.0+ # # Feature Compatibility Matrix: # | Shakapacker Version | Basic Pack Generation | Auto-Registration | Nested Entries | Async Loading | # |-------------------|----------------------|-------------------|----------------|---------------| # | 6.5.1 - 6.9.x | ✅ Yes | ❌ No | ❌ No | ❌ No | # | 7.0.0 - 8.1.x | ✅ Yes | ✅ Yes | ✅ Yes | ❌ No | # | 8.2.0+ | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes | # ################################################################################ # components_subdirectory is the name of the subdirectory matched to detect and register components automatically # The default is nil. You can enable the feature by updating it in the next line. config.components_subdirectory = nil # Change to a value like this example to enable this feature # config.components_subdirectory = "ror_components" # stores_subdirectory is the name of the subdirectory matched to detect and register Redux stores automatically. # Works the same way as components_subdirectory but for Redux stores used with the `redux_store` helper. # Note: Redux stores are less common since React Hooks were introduced. Most new apps use # components without Redux. Only configure this if your app uses Redux stores. # The default is nil. You can enable the feature by updating it in the next line. config.stores_subdirectory = nil # Change to a value like this example to enable this feature # config.stores_subdirectory = "ror_stores" # Default is false. # The default can be overridden as an option in calls to view helpers # `react_component`, `react_component_hash`, and `redux_store`. # You may set to true to change the default to auto loading. # NOTE: Requires Shakapacker 6.5.1+ for basic functionality, 7.0.0+ for full auto-registration features. # See version requirements matrix above for complete feature compatibility. config.auto_load_bundle = false # Default is false # Set this to true & instead of trying to import the generated server components into your existing # server bundle entrypoint, the PacksGenerator will create a server bundle entrypoint using # config.server_bundle_js_file for the filename. config.make_generated_server_bundle_the_entrypoint = false # Configuration for how generated component packs are loaded. # Options: :sync, :async, :defer # - :sync (default for Shakapacker < 8.2.0): Loads scripts synchronously # - :async (default for Shakapacker ≥ 8.2.0): Loads scripts asynchronously for better performance # - :defer: Defers script execution until after page load config.generated_component_packs_loading_strategy = :async # 🚫 REMOVED in v17.0.0: `defer_generated_component_packs` now raises NoMethodError at boot. # Use `generated_component_packs_loading_strategy` (above) instead: # `defer_generated_component_packs = true` → `generated_component_packs_loading_strategy = :defer` # `defer_generated_component_packs = false` → delete the line (the old `false` was a no-op that # fell through to the default strategy; set `:sync` only if you relied on synchronous loading). # See CHANGELOG.md and the [upgrade guide](../upgrading/upgrading-react-on-rails.md) for more details. ################################################################################ # DEPRECATED CONFIGURATION ################################################################################ # 🚫 DEPRECATED: immediate_hydration is no longer used # # This configuration option has been removed. Immediate hydration is now # automatically enabled for React on Rails Pro users and cannot be disabled. # # If you still have this in your config, it will log a deprecation warning: # config.immediate_hydration = false # ⚠️ Logs warning, has no effect # # Action Required: Remove this line from your config/initializers/react_on_rails.rb # See CHANGELOG.md for migration instructions. # # Historical Context: # Previously controlled whether Pro components hydrated immediately upon their # server-rendered HTML reaching the client, vs waiting for full page load. ################################################################################ # I18N OPTIONS ################################################################################ # Replace the following line to the location where you keep translation.js & default.js for use # by the npm packages react-intl. Be sure this directory exists! # config.i18n_dir = Rails.root.join("client", "app", "libs", "i18n") # # If not using the i18n feature, then leave this section commented out or set the value # of config.i18n_dir to nil. # # Replace the following line to the location where you keep your client i18n yml files # that will source for automatic generation on translations.js & default.js # By default(without this option) all yaml files from Rails.root.join("config", "locales") # and installed gems are loaded config.i18n_yml_dir = Rails.root.join("config", "locales") # Possible output formats are js and json # The default format is json config.i18n_output_format = 'json' # Possible YAML.safe_load options pass-through for locales # config.i18n_yml_safe_load_options = { permitted_classes: [Symbol] } ################################################################################ ################################################################################ # TEST CONFIGURATION OPTIONS # build_test_command is used with ReactOnRails::TestHelper: # - RSpec: ReactOnRails::TestHelper.configure_rspec_to_compile_assets(config) # - Minitest: ReactOnRails::TestHelper.ensure_assets_compiled # # NOTE: # Alternative (simpler): use Shakapacker auto-compilation in tests: # 1. Set compile: true in config/shakapacker.yml for test environment # 2. Remove ReactOnRails::TestHelper wiring ################################################################################ # If you are using this in your RSpec helper files: # # ReactOnRails::TestHelper.configure_rspec_to_compile_assets(config) # # then this controls what yarn/pnpm/npm command is run # to automatically refresh your Webpack assets on every test run. # end ``` ### server_bundle_js_file **Type:** String **Default:** `""` **Required for:** Server-side rendering The filename of your server bundle used for server-side rendering with `prerender: true`. - Set to `"server-bundle.js"` if using server rendering - Set to `""` if not using server rendering - This file is used by React on Rails' JavaScript execution pool for server rendering Note: There should be ONE server bundle that can render all your server-rendered components, unlike client bundles where you minimize size. ### build_test_command **Type:** String **Default:** `""` **Used with:** ReactOnRails::TestHelper (`configure_rspec_to_compile_assets` for RSpec or `ensure_assets_compiled` for Minitest) **Important:** This option is only needed if you're using the React on Rails test helper. The two approaches below are **mutually exclusive** - use one or the other, not both. #### Recommended Approach: React on Rails Test Helper + build_test_command Set `build_test_command` and wire TestHelper into your test framework. Keep `compile: false` in `config/shakapacker.yml` test section. Keep test `public_output_path` separate from development (for example, `webpack/test` vs `webpack/dev`) so test and development manifests never overwrite each other. If your project uses both RSpec and Minitest, configure both helper files. If you are also running `bin/dev`, run `bin/dev test-watch` in a separate terminal for fast test iteration. Use `--test-watch-mode=full` or `--test-watch-mode=client-only` to override auto mode when needed. This shared-writer issue exists because server bundles usually go to `private_output_path` (default: `ssr-generated`) across environments. Advanced static-only workflow (optional): - If you intentionally run `bin/dev static`, you may set `test.public_output_path` equal to development so tests reuse static build output. - Do not use shared test/development output paths with `bin/dev` (HMR mode), or manifests can collide. ```ruby # config/initializers/react_on_rails.rb config.build_test_command = "RAILS_ENV=test bin/shakapacker" ``` ```ruby # spec/rails_helper.rb (RSpec) require "react_on_rails/test_helper" RSpec.configure do |config| ReactOnRails::TestHelper.configure_rspec_to_compile_assets(config) end ``` ```ruby # test/test_helper.rb (Minitest) require "react_on_rails/test_helper" class ActiveSupport::TestCase setup do ReactOnRails::TestHelper.ensure_assets_compiled end end ``` **Pros:** - Explicit control over compilation timing - Only compiles once before test suite runs - Can customize the build command - Reliable for SSR tests because bundles are built before first render **Cons:** - Requires additional setup in spec helpers - More configuration to maintain #### Alternative Approach: Shakapacker Auto-Compilation Set `compile: true` in `config/shakapacker.yml` and remove TestHelper wiring: ```yaml test: compile: true public_output_path: webpack/test ``` This is simpler but less explicit, and may be less reliable for SSR test ordering if server bundles are not prebuilt. Use `bundle exec rake react_on_rails:doctor` to verify your current setup, or `FIX=true bundle exec rake react_on_rails:doctor` to auto-apply supported test setup fixes. For more details on testing configuration, see the [Testing Configuration Guide](../building-features/testing-configuration.md). ## File-Based Component Registry If you have many components and want to avoid manually managing webpack entry points for each one, React on Rails can automatically generate component packs based on your file system structure. This feature is particularly useful for large applications with dozens of components. Redux store auto-registration is also supported (see the linked guide). For complete information about the file-based component registry feature (including `components_subdirectory`, `auto_load_bundle`, and `make_generated_server_bundle_the_entrypoint` configuration options), see: [Auto-Bundling: File-System-Based Automated Bundle Generation](../core-concepts/auto-bundling-file-system-based-automated-bundle-generation.md) ## Advanced Configuration The following sections document advanced configuration options. Most applications won't need to change these as they have sensible defaults. ### Component Loading Strategy #### generated_component_packs_loading_strategy **Type:** Symbol (`:async`, `:defer`, or `:sync`) **Default:** `:async` for Pro users with Shakapacker 8.2.0+, `:defer` for non-Pro users, `:sync` for older Shakapacker **Auto-configured:** ✅ Yes Controls how generated component pack scripts are loaded: - `:async` - Loads scripts asynchronously (Pro users, best performance) - `:defer` - Defers script execution until after page load (non-Pro users) - `:sync` - Loads scripts synchronously (fallback for Shakapacker < 8.2.0) **You typically don't need to set this** - React on Rails automatically selects the best strategy based on your Pro license status and Shakapacker version. **When to override:** Only change this if you have specific performance requirements or constraints. For example, you might use `:defer` if you need to ensure all page content loads before scripts execute, or `:sync` for testing purposes. ```ruby config.generated_component_packs_loading_strategy = :defer ``` ### Server Bundle Security and Organization #### server_bundle_output_path **Type:** String or nil **Default:** `"ssr-generated"` > ⚠️ **DO NOT change this setting unless you have a specific reason.** The default is correct for virtually all applications. Directory (relative to Rails root) where server bundles are output. ```ruby # No need to set this - the default is recommended # config.server_bundle_output_path = "ssr-generated" ``` - When set to a string: Server bundles output to this directory (e.g., `ssr-generated/`) - When `nil`: Server bundles loaded from same public directory as client bundles (not recommended) The default `"ssr-generated"` keeps server bundles separate from public assets for security. #### enforce_private_server_bundles **Type:** Boolean **Default:** `false` **Recommended for production:** `true` When true, React on Rails only loads server bundles from private directories (configured via `server_bundle_output_path`), preventing accidental exposure of server code: ```ruby config.enforce_private_server_bundles = true ``` Benefits: - Prevents server-side code from being web-accessible - Protects against malicious JavaScript execution - Especially important for React Server Components ### Production Build #### build_production_command **Type:** String or Module **Default:** `nil` **Typical usage:** Only if customizing asset compilation Command to run during `assets:precompile` to build production assets: ```ruby config.build_production_command = "RAILS_ENV=production bin/shakapacker" ``` **Important:** When setting this, you must disable Shakapacker's precompile by setting `shakapacker_precompile: false` in `config/shakapacker.yml`. **Most apps don't need this** - Shakapacker handles asset compilation automatically. ### Common Configuration These are commonly used configuration options that many applications will need: #### rendering_extension **Type:** Module **Default:** `nil` Module that adds custom values to the `railsContext` object passed to all components: ```ruby module RenderingExtension def self.custom_context(view_context) { somethingUseful: view_context.session[:something_useful], currentUser: view_context.current_user&.as_json } end end config.rendering_extension = RenderingExtension ``` #### rendering_props_extension **Type:** Module **Default:** `nil` Module that modifies props for client-side hydration (useful for stripping server-only props): ```ruby module RenderingPropsExtension def self.adjust_props_for_client_side_hydration(component_name, props) component_name == 'HelloWorld' ? props.except(:server_side_only) : props end end config.rendering_props_extension = RenderingPropsExtension ``` ### Server Rendering Options #### prerender **Type:** Boolean **Default:** `false` Global default for server-side rendering. When true, all `react_component` calls will server render by default. **Most apps prefer to set this at the `react_component` call level** rather than globally: ```ruby # Preferred: Set per-component react_component("MyComponent", prerender: true) ``` To set a global default: ```ruby config.prerender = true # Server render all components by default ``` You can override the global setting per-component: ```ruby react_component("MyComponent", prerender: false) # Skip SSR for this component ``` ### Development and Debugging #### trace **Type:** Boolean **Default:** `Rails.env.development?` **Auto-configured:** ✅ Yes Enables detailed logging for server rendering, including stack traces for setTimeout/setInterval calls: ```ruby config.trace = Rails.env.development? # default ``` #### development_mode **Type:** Boolean **Default:** `Rails.env.development?` **Auto-configured:** ✅ Yes Forces Rails to reload server bundle when modified: ```ruby config.development_mode = Rails.env.development? # default ``` #### replay_console **Type:** Boolean **Default:** `true` When true, server-side console messages replay in the browser console. This is valuable for debugging server-rendering issues. ```ruby config.replay_console = true # default ``` **When to disable:** You might set this to `false` in production if console logs contain sensitive data or to reduce client-side payload size. #### logging_on_server **Type:** Boolean **Default:** `true` Logs server rendering messages to `Rails.logger.info`: ```ruby config.logging_on_server = true # default ``` **Pro Node Renderer Note:** When using the Pro Node Renderer, you might set this to `false` to avoid duplication of logs, as the Node Renderer handles its own logging. #### raise_on_prerender_error **Type:** Boolean **Default:** `Rails.env.development?` **Auto-configured:** ✅ Yes Raises exceptions when JavaScript errors occur during server rendering (development only by default): ```ruby config.raise_on_prerender_error = Rails.env.development? # default ``` ### Development Server (bin/dev) #### check_database_on_dev_start **Type:** Boolean **Default:** `true` Controls whether `bin/dev` checks database connectivity before starting the development server. When enabled, it verifies the database exists and is accessible, and warns about pending migrations. ```ruby config.check_database_on_dev_start = false # Disable the check ``` This is the lowest-priority opt-out mechanism. You can also disable the check per-invocation via the `--skip-database-check` CLI flag or the `SKIP_DATABASE_CHECK=true` environment variable. See the [Process Managers guide](../building-features/process-managers.md#database-connectivity-check) for details. ### Server Renderer Pool (ExecJS) #### server_renderer_pool_size **Type:** Integer **Default:** `1` (or environment-based) **Auto-configured:** ✅ Yes Number of JavaScript execution instances in the server rendering pool: ```ruby config.server_renderer_pool_size = 1 # MRI default (avoid deadlock) config.server_renderer_pool_size = 5 # JRuby (can handle multi-threading) ``` **MRI users:** Keep at 1 to avoid deadlocks **JRuby users:** Can increase for multi-threaded rendering #### server_renderer_timeout **Type:** Integer (seconds) **Default:** `20` Maximum time to wait for server rendering to complete: ```ruby config.server_renderer_timeout = 20 # default ``` ### Component DOM IDs #### random_dom_id **Type:** Boolean **Default:** `true` Controls whether component DOM IDs include a random UUID: - `true` - IDs like `MyComponent-react-component-a1b2c3d4` - `false` - IDs like `MyComponent-react-component` ```ruby config.random_dom_id = false # Use fixed IDs ``` **When to use false:** Modern apps typically have one component instance per page. **When to use true:** Multiple instances of same component on one page. Can be overridden per-component: ```ruby react_component("MyComponent", random_dom_id: false) ``` ### Component Registry Timeout #### component_registry_timeout **Type:** Integer (milliseconds) **Default:** `5000` Maximum time to wait for client-side component registration after page load: ```ruby config.component_registry_timeout = 5000 # default (5 seconds) ``` Set to `0` to wait indefinitely (not recommended for production). ### I18n Configuration These options are for applications using [react-intl](https://formatjs.io/docs/react-intl/) or similar internationalization libraries. If your application doesn't need i18n, you can skip this section. #### i18n_dir **Type:** String or nil **Default:** `nil` Directory where i18n translation files are output for use by react-intl: ```ruby config.i18n_dir = Rails.root.join("client", "app", "libs", "i18n") ``` Set to `nil` to disable i18n features. #### i18n_yml_dir **Type:** String **Default:** `Rails.root.join("config", "locales")` Directory where i18n YAML source files are located: ```ruby config.i18n_yml_dir = Rails.root.join("config", "locales") ``` #### i18n_output_format **Type:** String **Default:** `'json'` Format for generated i18n files (`'json'` or `'js'`): ```ruby config.i18n_output_format = 'json' # default ``` #### i18n_yml_safe_load_options **Type:** Hash **Default:** `{}` Options passed to `YAML.safe_load` when reading locale files: ```ruby config.i18n_yml_safe_load_options = { permitted_classes: [Symbol] } ``` ### Webpack Integration #### webpack_generated_files **Type:** Array of Strings **Default:** `%w[manifest.json]` (auto-populated with server bundle files) Files that webpack generates, used by test helper to check if compilation is needed: ```ruby config.webpack_generated_files = %w[server-bundle.js manifest.json] ``` **Note:** Don't include hashed filenames (from manifest.json) as they change on every build. #### same_bundle_for_client_and_server **Type:** Boolean **Default:** `false` When true, React on Rails reads the server bundle from webpack-dev-server (useful if using same hashed bundle for client and server): ```ruby config.same_bundle_for_client_and_server = false # default ``` **This should almost never be true.** Almost all apps should use separate client/server bundles. When true, also set in `config/shakapacker.yml`: ```yaml dev_server: hmr: false ``` ### Internal Options #### node_modules_location **Type:** String **Default:** `Rails.root` Location of `node_modules` directory. With Shakapacker, this should typically be `""` (project root): ```ruby config.node_modules_location = "" # Shakapacker default ``` The open-source gem always renders on the server with ExecJS; there is no configuration option to select a different server render method. For a standalone Node rendering process, use [React on Rails Pro](https://www.shakacode.com/react-on-rails-pro/)'s Node renderer, which is configured via `ReactOnRailsPro.configure`. For deprecated configuration options, see [configuration-deprecated.md](configuration-deprecated.md). ## Complete Example Here's a complete example showing commonly changed options: ```ruby # frozen_string_literal: true ReactOnRails.configure do |config| ################################################################################ # Essential Configuration ################################################################################ # Server rendering bundle config.server_bundle_js_file = "server-bundle.js" # Test configuration config.build_test_command = "RAILS_ENV=test bin/shakapacker" # File-based component registry config.components_subdirectory = "ror_components" config.auto_load_bundle = true # config.stores_subdirectory = "ror_stores" # Optional: for Redux store auto-registration ################################################################################ # Optional Overrides (most apps don't need these) ################################################################################ # Production build (only if not using standard Shakapacker) # config.build_production_command = "RAILS_ENV=production bin/shakapacker" # Server bundle security (recommended for production) # config.enforce_private_server_bundles = true # Custom rendering hooks # config.rendering_extension = RenderingExtension # config.rendering_props_extension = RenderingPropsExtension end ``` ## Pro Features For React Server Components (RSC) and other Pro-specific configuration options, see: [configuration-pro.md](configuration-pro.md) ## Deprecated Options For deprecated and removed configuration options, see: [configuration-deprecated.md](configuration-deprecated.md) ## Support Examples ### Custom Rendering Extension ```ruby module RenderingExtension def self.custom_context(view_context) if view_context.controller.is_a?(ActionMailer::Base) {} else { somethingUseful: view_context.session[:something_useful], currentUser: view_context.current_user&.as_json } end end end ``` ### Custom Props Extension ```ruby module RenderingPropsExtension def self.adjust_props_for_client_side_hydration(component_name, props) # Strip server-only props before sending to client props.except(:server_side_authentication_token, :internal_admin_data) end end ``` ### Custom Build Command Module ```ruby module BuildProductionCommand include FileUtils def self.call sh "RAILS_ENV=production NODE_ENV=production bin/shakapacker" # Additional custom build steps here end end # In your config: config.build_production_command = BuildProductionCommand ``` ## Bundle Organization Example Recommended directory structure with private server bundles: ```text app/ ├── ssr-generated/ # Private server bundles (never served to browsers) │ ├── server-bundle.js │ └── rsc-bundle.js └── public/ └── webpack/development/ # Public client bundles (web-accessible) ├── application.js ├── manifest.json └── styles.css ``` Access methods: - **Client bundles:** `ReactOnRails::Utils.public_bundles_full_path` - **Server bundles:** `ReactOnRails::Utils.server_bundle_js_file_path` ## Need Help? - **Documentation:** [React on Rails Guides](https://reactonrails.com/docs/) - **Pro Features:** [React on Rails Pro](../../pro/react-on-rails-pro.md) - **Support:** [ShakaCode Forum](https://forum.shakacode.com/) - **Consulting:** [justin@shakacode.com](mailto:justin@shakacode.com) --- **Note:** This configuration file is meant to be a complete reference. For most applications, you'll only use a small subset of these options. Start with the [Essential Configuration](#essential-configuration) and add advanced options only as needed. ================================================================================ PAGE: https://reactonrails.com/docs/configuration/configuration-pro SOURCE: docs/oss/configuration/configuration-pro.md ================================================================================ # React on Rails Pro Configuration > **Pro Feature** — Available with [React on Rails Pro](../../pro/react-on-rails-pro.md). > Free or very low cost for startups and small companies. [Upgrade or licensing details →](../../pro/upgrading-to-pro.md#try-pro-risk-free) For general React on Rails configuration options, see [Configuration](README.md). `config/initializers/react_on_rails_pro.rb` 1. You don't need to create an initializer if you are satisfied with the defaults as described below. 1. Values beginning with `renderer` pertain only to using an external rendering server. You will need to ensure these values are consistent with your configuration for the external rendering server, as given in [JS configuration](../building-features/node-renderer/js-configuration.md) 1. `config.prerender_caching` works for standard mini_racer server rendering and using an external rendering server. ## Example of Configuration Also see [spec/dummy/config/initializers/react_on_rails_pro.rb](https://github.com/shakacode/react_on_rails/blob/main/react_on_rails_pro/spec/dummy/config/initializers/react_on_rails_pro.rb) for how the testing app is setup. The below example is a typical production setup, using the separate `NodeRenderer`, where development takes the defaults when the ENV values are not specified. ```ruby ReactOnRailsPro.configure do |config| # If true, then capture timing of React on Rails Pro calls including server rendering and # component rendering. # Default for `tracing` is false. config.tracing = true # Array of globs to find any files for which changes should bust the fragment cache for # cached_react_component and cached_react_component_hash. This should include any files used to # generate the JSON props, webpack and/or webpacker configuration files, and npm package lockfiles. # Default for `dependency_globs` is an empty array config.dependency_globs = [ File.join(Rails.root, "app", "views", "**", "*.jbuilder") ] # Array of globs to exclude from config.dependency_globs for ReactOnRailsPro cache key hashing # Default for `excluded_dependency_globs` is an empty array config.excluded_dependency_globs = [ File.join(Rails.root, "app", "views", "**", "dont_hash_this.jbuilder") ] # Remote bundle caching saves deployment time by caching bundles. # See /docs/oss/building-features/bundle-caching.md for usage and examples. config.remote_bundle_cache_adapter = nil # ALL OPTIONS BELOW ONLY APPLY IF SERVER RENDERING # If true, then cache the evaluation of JS for prerendering using the standard Rails cache. # Applies to all rendering engines. # Default for `prerender_caching` is false. config.prerender_caching = true # Retry request in case of time out on the node-renderer side # 5 - default, if not specified # 0 - no retry config.renderer_request_retry_limit = 5 # NodeRenderer is for a renderer that is stateless. It does not need restarting when the JS bundles # are updated. It is the only custom renderer currently supported. Leave blank to use the standard # mini_racer rendering. Other option is NodeRenderer # Default for `server_renderer` is "ExecJS" config.server_renderer = "NodeRenderer" # React on Rails Node Renderer now support render functions returning promises! To enable this optional functionality, # toggle the following option. # Default is false. config.rendering_returns_promises = false # If you're using the NodeRenderer, a value of true allows errors to be thrown from the bundle # code for SSR so that an error tracking system on the NodeRender can use the exceptions. # If you are using ExecJS as your rendering method, set this to false. # Default is true. config.throw_js_errors = true # You may provide a password and/or a port that will be sent to renderer for simple authentication. # `https://:<password>@url:<port>`. For example: https://:YOUR_SECURE_PASSWORD@renderer:3800. Don't forget # the leading `:` before the password. Your password must also not contain certain characters that # would break calling URI(config.renderer_url). This includes: `@`, `#`, '/'. # **Note:** Don't forget to set up **SSL** connection (https) otherwise password will useless # since it will be easy to intercept it. # If you provide an ENV value (maybe only for production) and there is no value, then you get the default. # Default for `renderer_url` is "http://localhost:3800". config.renderer_url = ENV["REACT_RENDERER_URL"] # If you don't want to worry about special characters in your password within the url, use this config value # Default for `renderer_password` is nil # config.renderer_password = ENV["RENDERER_PASSWORD"] # Set the `ssr_timeout` configuration so the Rails server will not wait more than this many seconds # for a renderer socket read once issued. With the async-http renderer client, this is applied as # the per-read socket timeout on the renderer connection. Increase this value for long-running # streaming SSR responses with legitimate gaps between chunks. config.ssr_timeout = 5 # If false, then crash if no backup rendering when the remote renderer is not available # Can be useful to set to false in development or testing to make sure that the remote renderer # works and any non-availability of the remote renderer does not just do ExecJS. # Suggest setting this to false if the SSR JS code cannot run in ExecJS # Default for `renderer_use_fallback_exec_js` is true. config.renderer_use_fallback_exec_js = false # Maximum number of concurrent async-http connections per client to the Node renderer. # HTTP/2 may multiplex multiple request streams over those pooled connections. # When a Fiber.scheduler already exists before the renderer request enters `Sync {}`, the # client is reused across requests within that long-lived scheduler (persistent connection / # keep-alive; see the tuning section below), so this limit bounds connection concurrency for # streamed renders sharing one client. # Otherwise the adapter uses a request-scoped client. Under standard Puma (no pre-existing scheduler), `Sync {}` # creates that scheduler/client for the request and cleans it up when the request ends. # See "Renderer Performance Tuning for Streamed RSC" below. # Default for `renderer_http_pool_size` is 10 config.renderer_http_pool_size = 10 # TCP connect timeout in seconds. After the socket connects, request processing and streaming # are bounded by `ssr_timeout`. # Default for `renderer_http_pool_timeout` is 5 config.renderer_http_pool_timeout = 5 # warn_timeout - Displays a warning message if a request takes longer than the given time in seconds. # Default is 0.25 config.renderer_http_pool_warn_timeout = 0.25 # seconds # Snippet of JavaScript to be run right at the beginning of the server rendering process. The code # to be executed must either be self contained or reference some globally exposed module. # For example, suppose that we had to call `SomeLibrary.clearCache()`between every call to server # renderer to ensure no leakage of state between calls. Note, SomeLibrary needs to be globally # exposed in the server rendering webpack bundle. This code is visible in the tracing of the calls # to do server rendering. Default is nil. config.ssr_pre_hook_js = "SomeLibrary.clearCache();" # When using the Node Renderer, you may require some extra assets in addition to the bundle. # The assets_to_copy option allows the Node Renderer to have assets copied at the end of # the assets:precompile task or directly by the # react_on_rails_pro:copy_assets_to_remote_vm_renderer task. # These assets are also transferred any time a new bundle is sent from Rails to the renderer. # The value should be a file_path or an Array of file_paths. The files should have extensions # to resolve the content types, such as "application/json". config.assets_to_copy = [ Rails.root.join("public", "webpack", Rails.env, "loadable-stats.json"), Rails.root.join("public", "webpack", Rails.env, "manifest.json") ] ################################################################################ # REACT SERVER COMPONENTS (RSC) CONFIGURATION ################################################################################ # Enable React Server Components support # When enabled, React on Rails Pro will support RSC rendering and streaming # Default is false config.enable_rsc_support = true # Path to the RSC bundle file (relative to webpack output directory or absolute path) # The RSC bundle contains only server components and references to client components. # It's generated using the RSC Webpack Loader which transforms client components into # references. This bundle is specifically used for generating RSC payloads and is # configured with the 'react-server' condition. # Default is "rsc-bundle.js" config.rsc_bundle_js_file = "rsc-bundle.js" # Path to the React client manifest file (typically in your webpack output directory) # This manifest contains mappings for client components that need hydration. # It's automatically generated by the React Server Components Webpack plugin and is # required for client-side hydration of components. # Only set this if you've configured the plugin to use a different filename. # Default is "react-client-manifest.json" config.react_client_manifest_file = "react-client-manifest.json" # Path to the React server-client manifest file (typically in your webpack output directory) # This manifest is used during server-side rendering with RSC to properly resolve # references between server and client components. # It's automatically generated by the React Server Components Webpack plugin. # Only set this if you've configured the plugin to use a different filename. # Default is "react-server-client-manifest.json" config.react_server_client_manifest_file = "react-server-client-manifest.json" # These RSC configuration files are crucial when implementing React Server Components # with streaming, which offers benefits like: # - Reduced JavaScript bundle sizes # - Faster page loading # - Selective hydration of client components # - Progressive rendering with Suspense boundaries end ``` ## Renderer Performance Tuning for Streamed RSC The dominant contributors to a streamed route's `responseEnd` tail are Node renderer round-trip overhead, cold or under-warmed renderer workers, and per-request connection setup between Rails and the renderer. Three levers address these (see [issue #4240](https://github.com/shakacode/react_on_rails/issues/4240)). Measure changes with before/after page-load timing for the streamed route, `Server-Timing` for the early Rails/renderer phases that are known before the first stream write, the inline RSC stream performance marks described in the [Streaming SSR guide](../../pro/streaming-ssr.md), and renderer logs or tracing for cold-worker behavior. Inline marks remain the source for late payload, flush, hydration, and stream-drain timing because `ActionController::Live` commits headers on the first stream write. ### 1. Warm up renderer workers Each worker compiles its bundle on its **first** render request, so the first measured render after a deploy is cold. Pre-warm every worker before serving real traffic so cold-start cost does not land on a user (or skew a benchmark): - Send a warm-up render (or hit `/ready` after a warm-up render) to each replica during deploy. - With `workersCount > 1`, a single warm-up render is not enough. Route warm-up traffic so it reaches **every** worker under your actual load-balancing policy; sticky or hash-based routing may require replica-local hooks or an explicit fan-out endpoint. **Do not gate all traffic on `/ready` without a separate warm-up path** — if no render requests reach the renderer, `/ready` never flips to 200 (deadlock). Full warm-up patterns (Kubernetes probes, `postStart` hooks, the `/ready` cold-start contract) are in [Node renderer health checks → Gating traffic on `/ready`](../building-features/node-renderer/health-checks.md#gating-traffic-on-ready). ### 2. Size the worker pool and the connection pool together Two independent limits gate renderer throughput: | Setting | Where | Default | Governs | | --------------------------------------------------------------------------------------------------- | -------- | -------- | ----------------------------------------------------------------- | | [`workersCount`](../building-features/node-renderer/js-configuration.md) / `RENDERER_WORKERS_COUNT` | Renderer | CPUs − 1 | How many renders the renderer can execute concurrently. | | `renderer_http_pool_size` | Rails | 10 | Max concurrent async-http connections per client to the renderer. | Guidance: - With Falcon or another long-lived scheduler, keep `renderer_http_pool_size` close to (and generally not far above) `workersCount`; streamed renders sharing that scheduler use the same async-http client, and HTTP/2 may multiplex request streams over the pooled connections. Sending many more concurrent renderer requests than there are workers just queues renders at the renderer while adding connection and scheduling overhead. - Under standard Puma streaming, `Sync {}` creates a request-scoped client, so `renderer_http_pool_size` only bounds concurrent async-http connections inside one streamed response. Use a value near the number of renderer calls one response can overlap; scale `workersCount` and renderer replicas for cross-request concurrency. - Account for your Rails concurrency: with many Puma threads/workers all streaming, a renderer with only one or two workers becomes the bottleneck. Scale `workersCount` (and renderer replicas) to your real concurrent streamed-render load. - Tune `ssr_timeout` for legitimate long gaps between streamed chunks — it applies as a per-read socket timeout, so it fires when a single read from the renderer blocks for `ssr_timeout` seconds. It is not a total response-duration cap; avoid masking renderer hangs with an unnecessarily high value. ### 3. Rails ↔ renderer keep-alive (persistent on Falcon/async scheduler; per-request on standard Puma) Connection reuse is automatic when the renderer request runs under a long-lived `Fiber.scheduler`, such as Falcon or Puma configured with an async scheduler. In that setup, the async-http client is stored on the scheduler and reused across streaming requests, so HTTP/2 connections stay alive and renders multiplex over them instead of paying TCP handshake and H2 connection setup per request ([issue #3283](https://github.com/shakacode/react_on_rails/issues/3283)). No React on Rails configuration is required to enable this. Under standard Puma, the streaming helper's `Sync {}` block creates a per-request scheduler. The async-http client is cleaned up when that streaming response ends, so connection reuse does not persist across consecutive Rails requests. The benefit is still meaningful inside a single streamed response: renderer calls in that response can share the same client lifecycle and `renderer_http_pool_size` still bounds concurrent async-http connections within that request. Call the renderer from the normal Rails request path. The adapter chooses scheduler-scoped reuse whenever a `Fiber.scheduler` already exists before it enters `Sync {}`; custom middleware or background code that installs a scheduler with an unclear lifecycle can therefore keep renderer clients alive longer than intended. Keep those calls inside the request's scheduler lifecycle, or use the standard path where `Sync {}` creates and cleans up the per-request client. `config.renderer_http_keep_alive_timeout` is **deprecated** and ignored: the async-http adapter manages connection lifecycle automatically (connections are reused within the scheduler and cleaned up when it ends). Explicitly setting it to a non-`nil` value in your `configure` block emits a deprecation warning; leaving it unset or setting it to `nil` is accepted silently. If you previously set it to `30` (the old default), remove the line from your `configure` block entirely. To confirm reuse, compare before/after `responseEnd` timing and streamed RSC performance marks, and trace renderer sockets when you need to distinguish long-lived scheduler reuse from standard Puma's per-request scheduler cleanup. ## Need Help? - **Pro Features:** [React on Rails Pro](../../pro/react-on-rails-pro.md) - **Consulting:** [justin@shakacode.com](mailto:justin@shakacode.com) ================================================================================ PAGE: https://reactonrails.com/docs/configuration/configuration-deprecated SOURCE: docs/oss/configuration/configuration-deprecated.md ================================================================================ # Deprecated Configuration Options This document lists configuration options that have been deprecated or removed from React on Rails. For current configuration options, see [Configuration](README.md). ## Removed Options ### immediate_hydration **Status:** ⚠️ REMOVED in v16.6.0 This configuration option has been removed. React on Rails Pro now performs early hydration automatically for streamed components; there is no per-component toggle. Non-Pro users are not affected. **Migration:** Remove any `config.immediate_hydration` lines from your configuration and any `immediate_hydration:` keys passed to `react_component` / `stream_react_component` — both are no-ops and can be safely deleted. See [CHANGELOG.md](https://github.com/shakacode/react_on_rails/blob/main/CHANGELOG.md) for details. ### defer_generated_component_packs **Status:** ⚠️ REMOVED in v17.0.0 Deprecated in v16 and removed in v17. Setting `config.defer_generated_component_packs` now raises `NoMethodError` at boot. Use `config.generated_component_packs_loading_strategy` instead. **Migration:** ```ruby # Old (removed): config.defer_generated_component_packs = true # → :defer config.defer_generated_component_packs = false # → delete the line (was a no-op) # New: config.generated_component_packs_loading_strategy = :defer # or :sync ``` The old option was truthy-gated: only `= true` had any effect (it set `:defer`). `= false` was a no-op that fell through to the default strategy — it did **not** mean `:sync`. So migrate `= true` to `:defer`, and simply delete `= false`. Set `:sync` explicitly only if you specifically relied on synchronous (blocking) pack loading. If you delete the line without setting `generated_component_packs_loading_strategy`, the default strategy applies: `:async` for Pro or `:defer` for non-Pro on Shakapacker 8.2.0+, and `:sync` on older Shakapacker. See [CHANGELOG.md](https://github.com/shakacode/react_on_rails/blob/main/CHANGELOG.md) for more details. ### generated_assets_dirs **Status:** ⚠️ REMOVED in v17.0.0 Deprecated in v16 and removed in v17. Setting `config.generated_assets_dirs` now raises `NoMethodError` at boot. Delete the line — public asset paths are determined automatically from `public_output_path` in `config/shakapacker.yml`. ### skip_display_none **Status:** ⚠️ REMOVED in v17.0.0 Deprecated in v16 and removed in v17. Setting `config.skip_display_none` now raises `NoMethodError` at boot. Delete the line — it had no runtime effect. ## Need Help? - **Documentation:** [React on Rails Guides](https://reactonrails.com/docs/) - **Support:** [ShakaCode Forum](https://forum.shakacode.com/) - **Consulting:** [justin@shakacode.com](mailto:justin@shakacode.com) ================================================================================ PAGE: https://reactonrails.com/docs/api-reference/view-helpers-api SOURCE: docs/oss/api-reference/view-helpers-api.md ================================================================================ # View and Controller Helpers ## View Helpers API Once the bundled files have been generated in your `app/assets/webpack` folder, and you have registered your components, you will want to render these components on your Rails views using the included helper method, [`react_component`](#react_component). --- ### react_component ```ruby react_component(component_name, props: {}, prerender: nil, hydrate_on: :immediate, html_options: {}) ``` Uncommonly used options: ```ruby trace: nil, replay_console: nil, raise_on_prerender_error: nil, id: nil, ``` - **component_name:** Can be a React component, created using a React Function Component, an ES6 class or a Render-Function that returns a React component (or, only on the server side, an object with shape `{ renderedHtml, clientProps?, redirectLocation?, routeError? }`), or a "renderer function" that manually renders a React component to the DOM (client-side only). Note, a "renderer function" is a special type of "Render-Function." A "renderer function" takes a 3rd param of a DOM ID. > If your render function returns a hash with multiple HTML strings (e.g., `{ renderedHtml: { componentHtml, title, metaTags } }`), `react_component` raises a `ReactOnRails::Error` telling you to use [`react_component_hash`](#react_component_hash) instead. `react_component` is for rendering a single HTML result; `react_component_hash` is for rendering multiple HTML strings to place in different parts of the page. All options except `props, id, html_options` will inherit from your `react_on_rails.rb` initializer, as described in the [configuration documentation](../configuration/README.md). - **general options:** - **props:** Ruby Hash which contains the properties to pass to the React object, or a JSON string. If you pass a string, we'll escape it for you. - **prerender:** enable server-side rendering of a component. Set to false when debugging! - **Environment override:** set `REACT_ON_RAILS_PRERENDER_OVERRIDE=true|false` to force prerendering on or off globally. Precedence is: `REACT_ON_RAILS_PRERENDER_OVERRIDE` > component option (`prerender:`) > initializer default (`config.prerender`). - **auto_load_bundle:** will automatically load the bundle for component by calling `append_javascript_pack_tag` and `append_stylesheet_pack_tag` under the hood. - **hydrate_on:** controls when React hydrates or client-renders this root. Supported OSS modes are `:immediate` (default), `:visible`, and `:idle`. See [Hydration Scheduling](../building-features/hydration-scheduling.md). `:interaction` is not supported. Deferred modes are OSS-only; React on Rails Pro currently accepts only `:immediate`. - **id:** Id for the div, will be used to attach the React component. This will get assigned automatically if you do not provide an id. Must be unique. - **html_options:** Any other HTML options get placed on the added div for the component. For example, you can set a class (or inline style) on the outer div so that it behaves like a span, with the styling of `display:inline-block`. You may also use an option of `tag: "span"` to replace the use of the default DIV tag to be a SPAN tag. - **trace:** set to true to print additional debugging information in the browser. Defaults to true for development, off otherwise. Only on the **client side** will you will see the `railsContext` and your props. - **random_dom_id:** True to automatically generate random dom ids when using multiple instances of the same React component on one Rails view. - **options if prerender (server rendering) is true:** - **replay_console:** Default is true. False will disable echoing server-rendering logs to the browser. While this can make troubleshooting server rendering difficult, so long as you have the configuration of `logging_on_server` set to true, you'll still see the errors on the server. - **logging_on_server:** Default is true. True will log JS console messages and errors to the server. - **raise_on_prerender_error:** Default is `Rails.env.development?` (true in development, false in production). True will throw an error on server-side rendering. Your controller will have to handle the error. - **`clientProps` merge behavior:** If a prerender result includes `clientProps`, React on Rails merges them into the generated client hydration props payload (`props.merge(clientProps)`). The original `props:` value must be a Ruby Hash or a JSON string representing an object. --- ### react_on_rails_preload_links ```erb <%= react_on_rails_preload_links("HelloWorld", "comments_list") %> ``` Use `react_on_rails_preload_links` in a layout or view `<head>` when you know which auto-bundled React components the page will render. The helper resolves each component to its generated Shakapacker pack (`generated/ComponentName`) and emits preload link tags for the manifest assets. Pass component names as PascalCase, camelCase, or snake_case strings; hyphenated names are rejected because they cannot be normalized reliably. For JavaScript chunks, plain script assets render as `<link rel="preload" as="script">`. Module assets render as `<link rel="modulepreload">` when the manifest marks the asset as a module or the emitted file has an `.mjs` extension. CSS chunks render as `<link rel="preload" as="style">`. Component packs without CSS assets simply skip the stylesheet preload. ```erb <head> <%= react_on_rails_preload_links("ProductPage") %> <%= stylesheet_pack_tag "application" %> </head> <body> <%= react_component("ProductPage", props: @product_props, auto_load_bundle: true) %> <%= javascript_pack_tag "application" %> </body> ``` Because preload hints belong in `<head>`, pass component names that are known before the component renders. This helper only emits HTML link tags. Keep the normal `stylesheet_pack_tag` and `javascript_pack_tag` calls in the layout so the browser still applies and executes the assets. When using a CDN asset host, keep Shakapacker's Subresource Integrity and `crossorigin` settings consistent between preload tags and the final script/style tags so the browser can reuse the preloaded response. With Shakapacker versions before 8.4 that do not expose `config.integrity`, preload links are still emitted without `integrity` attributes. React on Rails only adds preload SRI attributes when Shakapacker exposes integrity settings and marks them enabled. --- ### react_component_hash > **React 19 Alternative:** For metadata use cases (page titles, meta tags, canonical URLs), consider using [React 19 Native Metadata](../building-features/react-19-native-metadata.md) with `react_component` or `stream_react_component` instead. React 19 natively hoists `<title>`, `<meta>`, and `<link>` tags to `<head>`, eliminating the need for a render-function and `react_component_hash`. See the [migration guide](../building-features/react-19-native-metadata.md#migration-guide) for step-by-step instructions. `react_component_hash` is used to return multiple HTML strings for server rendering, such as for adding meta-tags to a page. It is exactly like `react_component` except for the following: 1. **`prerender: true` is forced**, not defaulted. This helper always prerenders on the server — passing `prerender: false` has no effect. Client-only rendering is incompatible with the "return multiple HTML strings" use case, so the option cannot be disabled. 2. Your JavaScript Render-Function for server rendering must return an Object rather than a React Component. The object must have shape `{ renderedHtml: { componentHtml, ...otherKeys } }`, where: - **`componentHtml` is mandatory.** Missing it raises `ReactOnRails::Error` with a message pointing to this requirement. This key contains the main server-rendered HTML that gets placed where the helper is called. - All other keys are optional and are returned to your view as `html_safe` strings, ready to be inserted anywhere in the layout (meta tags in `<head>`, sidebars, etc.). 3. Your view code must expect an object and not a string. Access keys with `react_component_hash_result["componentHtml"]`, `["title"]`, etc. 4. If the render function returns a string instead of an object, the helper raises an error telling you to return a render function that produces a hash. Here is an example of ERB view code: ```erb <% react_helmet_app = react_component_hash("ReactHelmetApp", prerender: true, props: { helloWorldData: { name: "Mr. Server Side Rendering"}}, id: "react-helmet-0", trace: true) %> <% content_for :title do %> <%= react_helmet_app['title'] %> <% end %> <%= react_helmet_app["componentHtml"] %> ``` And here is the JavaScript code: ```js export default (props, _railsContext) => { const componentHtml = renderToString(<ReactHelmet {...props} />); const helmet = Helmet.renderStatic(); const renderedHtml = { componentHtml, title: helmet.title.toString(), }; return { renderedHtml }; }; ``` --- ### rails_context You can call `rails_context` or `rails_context(server_side: true|false)` from your controller or view to see what values are in the Rails Context. Pass true or false depending on whether you want to see the server-side or the client-side `rails_context`. Typically, for computing cache keys, you should leave `server_side` as the default true. When calling this from a controller method, use `helpers.rails_context`. --- ### Renderer Functions (function that will call ReactDOM.render or ReactDOM.hydrate) A **renderer function** is a Render-Function that declares **three** parameters: `(props, railsContext, domNodeId) => { ... }`. React on Rails detects renderer functions purely by parameter count (`Function.length === 3`) — the names don't matter. Instead of returning a React component, a renderer function is responsible for mounting the React tree itself by calling `ReactDOM.hydrateRoot` (for SSR'd HTML) or `ReactDOM.createRoot(...).render(...)` (for empty containers) against the DOM node identified by `domNodeId`. The renderer function is invoked at the point where React on Rails would normally mount the component automatically. Why would you want to take over mounting yourself? One use case is code splitting: you may want to defer mounting a component until its code chunk has loaded, or until the container scrolls into view, instead of mounting it eagerly on page load. For modern code splitting with server-side rendering, see the [React on Rails Pro loadable-components guide](../building-features/code-splitting.md). > [!IMPORTANT] > **Renderer functions are strictly client-only.** There is no DOM on the server, so a renderer function cannot produce SSR output. React on Rails detects renderer functions at registration time and will throw a descriptive error like `Detected a renderer while server rendering component 'X'. See https://reactonrails.com/docs/core-concepts/render-functions for more information.` if you attempt to use one with `react_component(... prerender: true)`, `react_component_hash` (which forces prerendering), or `stream_react_component` (which is server-streaming only). For rendering that needs to run on the server, use a regular render function instead. #### Cleaning up on Turbo/Turbolinks navigation (optional teardown) Because a renderer function owns the React root it creates, React on Rails cannot unmount that root for you the way it does for the components it mounts itself. With [Turbo](https://turbo.hotwired.dev/) or Turbolinks, the page swaps without a full reload, so a renderer that never unmounts leaks its root (and any subscriptions or timers it holds) on every navigation. To opt in to cleanup, **return a teardown wrapper** — `{ teardown: () => void | Promise<void> }`, or a promise resolving to one — from the renderer. React on Rails stores it and runs it when the mount is torn down: on Turbo/Turbolinks navigation (when the framework swaps in the next page) or when the same `domNodeId` node is replaced. Returning nothing keeps the previous (leaky) behavior, so existing renderers are unaffected. ```jsx import ReactDOMClient from 'react-dom/client'; // Renderer function: 3 params, mounts itself, returns a teardown wrapper. const MyRenderer = (props, _railsContext, domNodeId) => { const domNode = document.getElementById(domNodeId); if (!domNode) { throw new Error(`Missing DOM element with id: ${domNodeId}`); } // This example always creates a fresh root. See the hydration note below if your renderer // needs to hydrate server-rendered markup. const root = ReactDOMClient.createRoot(domNode); root.render(<MyComponent {...props} />); // Unmounted automatically on the next Turbo navigation (or same-id node replacement). return { teardown: () => root.unmount() }; }; ``` > [!NOTE] > **Hydrating server-rendered markup?** `prerender` is not a prop React on Rails injects — the top-level `prerender:` render option only controls server rendering and is rejected for renderer functions (see the note above). If your client renderer also serves components that were rendered on the server through a separate server bundle (a server/client split), pass an application-level signal in the component's `props`, such as `serverRendered`, and branch on it. The in-repo dummy apps use their own fixture props for this decision; the custom flag here is just an example for renderers that need an explicit hydrate-vs-render signal. Remove that renderer-only flag before spreading props into your component: `const { serverRendered, ...componentProps } = props;`, then call `ReactDOMClient.hydrateRoot(domNode, <MyComponent {...componentProps} />)` when `serverRendered` is true. Under the React 16/17 legacy API there is no root handle, so unmount by container node instead: ```jsx import ReactDOM from 'react-dom'; const MyLegacyRenderer = (props, _railsContext, domNodeId) => { const { serverRendered, ...componentProps } = props; const domNode = document.getElementById(domNodeId); if (!domNode) { throw new Error(`Missing DOM element with id: ${domNodeId}`); } if (serverRendered) { ReactDOM.hydrate(<MyComponent {...componentProps} />, domNode); } else { ReactDOM.render(<MyComponent {...componentProps} />, domNode); } return { teardown: () => ReactDOM.unmountComponentAtNode(domNode) }; }; ``` > [!NOTE] > Synchronous teardowns are always honored. An **async** teardown is best-effort in the open-source package: if a navigation or node replacement happens before the renderer resolves its teardown, that still-pending teardown may be dropped. React on Rails logs a `console.error` when this happens — search for `resolved after its mount was removed` (the teardown was dropped) or `Error resolving renderer teardown` (the render promise rejected) — so the dropped teardown is diagnosable rather than silent. React on Rails Pro's client renderer awaits the renderer and handles this race reliably. --- ### React Router [React Router](https://reactrouter.com/) is supported via manual integration, including server-side rendering. See: 1. [React on Rails docs for React Router](../building-features/react-router.md) 2. Examples in [spec/dummy/app/views/react_router](https://github.com/shakacode/react_on_rails/tree/main/react_on_rails/spec/dummy/app/views/react_router) and follow to the JavaScript code in the [spec/dummy/client/app/startup/RouterApp.server.tsx](../../../react_on_rails/spec/dummy/client/app/startup/RouterApp.server.tsx). 3. [React on Rails Pro loadable-components guide](../building-features/code-splitting.md) for modern code splitting with server-side rendering. ### TanStack Router TanStack Router has a first-class SSR helper through `react-on-rails-pro/tanstack-router` (requires React on Rails Pro). See [TanStack Router guide](../building-features/tanstack-router.md). --- ## server_render_js `server_render_js(js_expression, options = {})` - js_expression, like 2 + 3, and not a block of js code. If you have more than one line that needs to be executed, wrap it in an [IIFE](https://en.wikipedia.org/wiki/Immediately-invoked_function_expression). JS exceptions will be caught, and console messages will be handled properly - Currently, the only option you may pass is `replay_console` (boolean) This is a helper method that takes any JavaScript expression and returns the output from evaluating it. If you have more than one line that needs to be executed, wrap it in an IIFE. JS exceptions will be caught and console messages handled properly. --- ## Pro-Only View Helpers The following view helpers are available exclusively with [React on Rails Pro](../../pro/react-on-rails-pro.md). Install the Pro gem to use them. ShakaCode Trust-Based Commercial Licensing lets you evaluate Pro without a token in development, test, CI/CD, and staging; production deployments require a paid license from [Pro pricing and sign up](https://pro.reactonrails.com/). ### cached_react_component and cached_react_component_hash Fragment caching helpers that cache React component rendering to improve performance. The API is the same as `react_component` and `react_component_hash`, but with these differences: 1. The `cache_key` takes the same parameters as any Rails `cache` view helper. 2. The **props** are passed via a block so that evaluation of the props is not done unless the cache is broken. Example usage: ```erb <%= cached_react_component("App", cache_key: [@user, @post], prerender: true) do some_slow_method_that_returns_props end %> ``` ### stream_react_component Progressive server-side rendering using React 18+ streaming with `renderToPipeableStream`. This enables: - Faster Time to First Byte (TTFB) - Progressive page loading with Suspense boundaries - Better perceived performance See the [Streaming Server Rendering guide](../building-features/streaming-server-rendering.md) for usage details. > [!IMPORTANT] > `stream_react_component` always forces `prerender: true` — passing `prerender: false` has no effect. It only supports React components and render functions that return React components; render functions returning a `{ renderedHtml }` hash are incompatible (see [compatibility matrix](../core-concepts/render-functions.md#compatibility-matrix-component-types-and-ruby-helpers)). ### stream_react_component_with_async_props Async-props variant of `stream_react_component`. Use it when Rails has synchronous props plus other props that should stream later through Suspense boundaries. Use this helper for RSC Server Components with `config.enable_rsc_support = true`. For non-RSC streaming SSR, use `stream_react_component`. It accepts the same options as `stream_react_component`, plus a block that receives an emitter. Call `emit.call(prop_name, value)` for each async prop: ```erb <%= stream_react_component_with_async_props("ProductPage", props: { name: @product.name, price: @product.price }) do |emit| emit.call("reviews", @product.reviews.as_json(only: [:id, :text, :rating])) end %> ``` RSC Server Components rendered this way receive `getReactOnRailsAsyncProp`, which returns a Promise for each emitted prop. For the complete React component pattern using `WithAsyncProps` and `getReactOnRailsAsyncProp`, see [Data Fetching in React on Rails Pro](../migrating/rsc-data-fetching.md#data-fetching-in-react-on-rails-pro). > [!IMPORTANT] > `stream_react_component_with_async_props` requires `config.enable_rsc_support = true` and always forces `prerender: true` — passing `prerender: false` has no effect. It requires the same controller setup as `stream_react_component`: the controller must call `stream_view_containing_react_components`. Like `stream_react_component`, it only supports React components and render functions that return React components; render functions returning a `{ renderedHtml }` hash are incompatible (see [compatibility matrix](../core-concepts/render-functions.md#compatibility-matrix-component-types-and-ruby-helpers)). > > The emitter block runs normal Ruby code sequentially, so `emit.call` does **not** parallelize slow queries by itself. For independent slow data sources, start the work concurrently before emitting values; see [Avoiding Server-Side Waterfalls](../migrating/rsc-data-fetching.md#avoiding-server-side-waterfalls). ### rsc_payload_react_component Renders React Server Component (RSC) payloads in NDJSON format for client-side consumption. Used in conjunction with RSC support to enable: - Reduced JavaScript bundle sizes - Server-side data fetching - Selective client-side hydration The mounted `rsc_payload_route` normally calls this helper for you. Call it directly only for custom RSC payload rendering. See the [React on Rails Pro Configuration](../configuration/configuration-pro.md) for RSC setup. ### rsc_payload_react_component_with_async_props Async-props variant of `rsc_payload_react_component`. Use it only when custom RSC payload rendering needs Rails-emitted async props, such as an overridden payload route or template. For standard streamed ERB views, use [`stream_react_component_with_async_props`](#stream_react_component_with_async_props). Requires `enable_rsc_support = true` in configuration, same as `rsc_payload_react_component` — see [React on Rails Pro Configuration](../configuration/configuration-pro.md). It accepts the same options as `rsc_payload_react_component`, plus a block that receives an emitter: ```erb <%= rsc_payload_react_component_with_async_props("ProductPage", props: { name: @product.name, price: @product.price }) do |emit| emit.call("reviews", @product.reviews.as_json(only: [:id, :text, :rating])) end %> ``` > [!IMPORTANT] > `rsc_payload_react_component_with_async_props` requires `config.enable_rsc_support = true` and always forces `prerender: true` — passing `prerender: false` has no effect. Use this helper only for custom RSC payload rendering; standard streamed ERB views should use `stream_react_component_with_async_props`. > > The emitter block runs normal Ruby code sequentially, so `emit.call` does **not** parallelize slow queries by itself. For independent slow data sources, start the work concurrently before emitting values; see [Avoiding Server-Side Waterfalls](../migrating/rsc-data-fetching.md#avoiding-server-side-waterfalls). --- ## More details See the [lib/react_on_rails/helper.rb](https://github.com/shakacode/react_on_rails/blob/main/react_on_rails/lib/react_on_rails/helper.rb) source. ================================================================================ PAGE: https://reactonrails.com/docs/api-reference/javascript-api SOURCE: docs/oss/api-reference/javascript-api.md ================================================================================ # ReactOnRails JavaScript API ## CSRF protection Rails has built-in protection for Cross-Site Request Forgery (CSRF), see [Rails Documentation](http://guides.rubyonrails.org/security.html#cross-site-request-forgery-csrf). To nicely utilize this feature in JavaScript requests, React on Rails provides two helpers that can be used as following for POST, PUT or DELETE requests: ```js import ReactOnRails from 'react-on-rails'; // reads from DOM csrf token generated by Rails in <%= csrf_meta_tags %> csrfToken = ReactOnRails.authenticityToken(); // compose Rails specific request header as following { X-CSRF-Token: csrfToken, X-Requested-With: XMLHttpRequest } header = ReactOnRails.authenticityHeaders(otherHeader); ``` If you are using [jquery-ujs](https://github.com/rails/jquery-ujs) for AJAX calls, then these helpers are not needed because the [jquery-ujs](https://github.com/rails/jquery-ujs) library updates header automatically, see [jquery-ujs documentation](https://robots.thoughtbot.com/a-tour-of-rails-jquery-ujs#cross-site-request-forgery-protection). ## API The best source of docs is the `interface ReactOnRails` in [types/index.ts](https://github.com/shakacode/react_on_rails/blob/main/packages/react-on-rails/src/types/index.ts). Here's a quick summary. No guarantees that this won't be outdated! ```js /** * Main entry point to using the react-on-rails NPM package. This is how Rails will be able to * find your components for rendering. * * Component detection: React on Rails distinguishes between component types by parameter count: * - 0-1 params: Regular React component (function or class) * - 2 params, or any function with `.renderFunction = true`: Render-Function — called with (props, railsContext), * returns a React component, `{ renderedHtml }` object, or Promise (Pro Node renderer only) * - 3 params: Renderer function — called with (props, railsContext, domNodeId), * responsible for calling ReactDOM.render/hydrate directly (client-only). * May optionally return a `{ teardown }` wrapper (or a promise resolving to one); React on Rails * runs it on Turbo/Turbolinks navigation or same-id node replacement to unmount the renderer's root * instead of leaking it. See the view-helpers renderer-function docs. * * Render-Functions can return: * - A React component (function or class) — used with `react_component` * - `{ renderedHtml: string }` — raw HTML string, used with `react_component` * - `{ renderedHtml: ReactElement }` — server rendering only, used with `react_component` * - `{ renderedHtml: { componentHtml, ...otherKeys } }` — used with `react_component_hash` * - `{ renderedHtml, clientProps }` — clientProps are merged into client hydration props * - `{ redirectLocation, routeError }` — legacy (React Router v3/v4), see render-functions docs * * @param components (key is component name, value is component) */ register(components); /** * Allows registration of store generators for legacy or advanced pages where multiple React * roots on one Rails view share a Redux store. Store generators receive props and railsContext, * then return a store. Note that the setStore API is different in that it's the actual store * hydrated with props. * @param stores (key is store name, value is the store generator) */ registerStoreGenerators(storesGenerators); /** * Allows retrieval of the store by name. This store will be hydrated by any Rails form props. * Pass optional param throwIfMissing = false if you want to use this call to get back undefined if * the store with name is not hydrated. * @param name * @param throwIfMissing Defaults to true. Set to false to have this call return undefined if * there is no store with the given name. * @returns Redux Store, possibly hydrated */ getStore(name, (throwIfMissing = true)); /** * Renders or hydrates the React element passed. In case React version is >=18 will use the root API. * @param domNode * @param reactElement * @param hydrate if true will perform hydration, if false will render * @returns {Root|ReactComponent|ReactElement|null} */ reactHydrateOrRender(domNode, reactElement, hydrate); /** * Set options for ReactOnRails, typically before you call ReactOnRails.register * Available Options: * `traceTurbolinks: true|false` Gives you debugging messages on Turbolinks events * `rootErrorHandlers: { onRecoverableError, onCaughtError, onUncaughtError }` React root error * callbacks applied to every React root created by React on Rails. Each callback receives * React's (error, errorInfo) plus a context object whose componentName and domNodeId fields * are optional. * Partial updates merge per key (setting one callback later keeps the others). * onRecoverableError requires React 18+; onCaughtError/onUncaughtError require React 19. * Unsupported React versions retain registrations for future upgrades, but the current runtime * cannot invoke unsupported callbacks and logs a one-time warning. * On React on Rails Pro RSC hydration roots, onRecoverableError is chained after Pro's * internal default reporting instead of replacing it; do not report the same error again there. * See https://reactonrails.com/docs/building-features/debugging-hydration-mismatches */ setOptions(options); /** * Allow directly calling the page loaded script in case the default events that trigger React * rendering are not sufficient, such as when loading JavaScript asynchronously with TurboLinks: * More details can be found here: * https://reactonrails.com/docs/building-features/turbolinks */ reactOnRailsPageLoaded(); /** * Returns CSRF authenticity token inserted by Rails csrf_meta_tags * @returns String or null */ authenticityToken(); /** * Returns header with csrf authenticity token and XMLHttpRequest * @param {*} other headers * @returns {*} header */ authenticityHeaders((otherHeaders = {})); ``` For TanStack Router integration utilities, see [`react-on-rails-pro/tanstack-router`](../building-features/tanstack-router.md) (requires React on Rails Pro). ================================================================================ PAGE: https://reactonrails.com/docs/api-reference/redux-store-api SOURCE: docs/oss/api-reference/redux-store-api.md ================================================================================ # Redux Store API > [!WARNING] > > This runtime API remains supported for existing apps and advanced shared-store use cases, but it is not recommended as the default state model for new React on Rails apps. Prefer the standard `react_component` view helper with props or a render-function unless multiple React islands must coordinate through one client store. Keeping one large shared store can also prevent dynamic code splitting for performance. > [!IMPORTANT] > > **Script Loading Requirement:** If you use Redux shared stores with inline component registration (registering components in view templates with `<script>ReactOnRails.register({ MyComponent })</script>`), you **must use `defer: true`** in your `javascript_pack_tag` instead of `async: true`. With async loading, the bundle may execute before inline scripts, causing component registration failures. See the [auto-bundling layout integration](../core-concepts/auto-bundling-file-system-based-automated-bundle-generation.md#layout-integration-with-auto-loading) guidance for related script-ordering patterns. You don't need to use the `redux_store` API to use Redux inside a single React root. This API was set up to support multiple calls to `react_component` on one page that all talk to the same Redux store. If you are rendering one React component on a page, pass props to that component through `react_component` and keep local UI state inside that React tree. A render-function is also a better fit when you need `railsContext`, routing setup, or custom hydration behavior for one root. Choose state ownership before reaching for `redux_store`: - **Island-local state:** use React Hooks or React Context inside one `react_component` root. - **Server state:** use Rails controller props for initial data, then Rails JSON endpoints, GraphQL, or a server-state cache such as [TanStack Query](../building-features/tanstack-query.md) for data that belongs on the server. - **Multi-island shared client state:** use `redux_store` when separate React roots on one Rails page must read and update the same client-side state. Consider using the `redux_store` helper for the following advanced use cases: 1. You want multiple React roots or islands to access the same store at once. 2. You want to place the props that hydrate client-side stores at the very end of your HTML, probably server-rendered, so that the browser can render all earlier HTML first. This is particularly useful if your props will be large. However, you're probably better off using [React on Rails Pro](../../pro/react-on-rails-pro.md) if you're at all concerned about performance. ## Multiple React Islands on a Page with One Store You may wish to have two separate React roots share the same Redux store. For example, if your navbar is a React island, you may want it to use the same store as another island in the main area of the page. You may even want multiple React islands in the main area, which allows for greater modularity. Also, you may want this to work with Turbo or Turbolinks to minimize reloading the JavaScript. A good example of this would be something like a notifications counter in a header. As each notification is read in the body of the page, you would like to update the header. If both the header and body share the same Redux store, then this is trivial. Otherwise, we have to rely on other solutions, such as the header polling the server to see how many unread notifications exist. Suppose the Redux store is called `appStore`, and you have 3 React components that each needs to connect to a store: `NavbarApp`, `CommentsApp`, and `BlogsApp`. I named them with `App` to indicate that they are the registered components. You will need to make a function that can create the store you will be using for all components and register it via the `registerStore` method. Note: this is a **storeCreator**, meaning that it is a function that takes (props, location) and returns a store: ```js function appStore(props, railsContext) { // Create a hydrated redux store, using props and the railsContext (object with // Rails contextual information). return myAppStore; } ReactOnRails.registerStore({ appStore, }); ``` When registering your component with React on Rails, you can get the store via `ReactOnRails.getStore`: ```js // getStore retrieves the store that React on Rails created and hydrated from the redux_store props const appStore = ReactOnRails.getStore('appStore'); return ( <Provider store={appStore}> <CommentsApp /> </Provider> ); ``` From your Rails view, you can use the provided helper `redux_store(store_name, props)` to create a fresh version of the store (because it may already exist if you came from visiting a previous page). Note: for this example, since we're initializing this from the main layout, we're using a generic name of `@react_props`. In other words, the Rails controller would set `@react_props` to the properties to hydrate the Redux store. **app/views/layouts/application.html.erb** ```erb ... <%= redux_store("appStore", props: @react_props) %>; <%= react_component("NavbarApp") %> yield ... ``` Components should be created as [function components](https://react.dev/learn/your-first-component#defining-a-component). Since you can pass in initial props via the helper `redux_store`, you do not need to pass any props directly to the component. Instead, the component hydrates by connecting to the store. **\_comments.html.erb** ```erb <%= react_component("CommentsApp") %> ``` **\_blogs.html.erb** ```erb <%= react_component("BlogsApp") %> ``` _Note:_ You will not be doing any partial updates to the Redux store when loading a new page. When the page content loads, React on Rails will rehydrate a new version of the store with whatever props are placed on the page. ## Controller Extension Include the module `ReactOnRails::Controller` in your controller, probably in ApplicationController. This will provide the following controller method, which you can call in your controller actions: `redux_store(store_name, props: {})` - **store_name:** A name for the store. You'll refer to this name in 2 places in your JavaScript: 1. You'll call `ReactOnRails.registerStore({storeName})` in the same place that you register your components. 2. In your component definition, you'll call `ReactOnRails.getStore('storeName')` to get the hydrated Redux store to attach to your components. - **props:** Named parameter `props`. ReactOnRails takes care of setting up the hydration of your store with props from the view. For an example, see [spec/dummy/app/controllers/pages_controller.rb](https://github.com/shakacode/react_on_rails/blob/main/react_on_rails/spec/dummy/app/controllers/pages_controller.rb). Note: this is preferable to using the equivalent view_helper `redux_store` in that you can be assured that the store is initialized before your components. ## View Helper `redux_store(store_name, props: {})` This method has the same API as the controller extension. **HOWEVER**, we recommend the controller extension instead because the Rails executes the template code in the controller action's view file (`erb`, `haml`, `slim`, etc.) before the layout. So long as you call `redux_store` at the beginning of your action's view file, this will work. However, it's an easy mistake to put this call in the wrong place. Calling `redux_store` in the controller action ensures proper load order, regardless of where you call this in the controller action. Note: you won't know of this subtle ordering issue until you server render and you find that your store is not hydrated properly. `redux_store_hydration_data` Place this view helper (no parameters) at the end of your shared layout so ReactOnRails will render the redux store hydration data. Since we're going to be setting up the stores in the controllers, we need to know where on the view to put the client-side rendering of this hydration data, which is a hidden div with a matching class that contains a data props. For an example, see [spec/dummy/app/views/layouts/application.html.erb](https://github.com/shakacode/react_on_rails/blob/main/react_on_rails/spec/dummy/app/views/layouts/application.html.erb). ## More Details - [lib/react_on_rails/controller.rb](https://github.com/shakacode/react_on_rails/blob/main/react_on_rails/lib/react_on_rails/controller.rb) source - [lib/react_on_rails/helper.rb](https://github.com/shakacode/react_on_rails/blob/main/react_on_rails/lib/react_on_rails/helper.rb) source ================================================================================ PAGE: https://reactonrails.com/docs/api-reference/ruby-api-pro SOURCE: docs/oss/api-reference/ruby-api-pro.md ================================================================================ # Ruby API (Pro) > **Pro Feature** — Available with [React on Rails Pro](../../pro/react-on-rails-pro.md). > Free or very low cost for startups and small companies. [Upgrade or licensing details →](../../pro/upgrading-to-pro.md#try-pro-risk-free) ## View Helpers These helpers are available in Rails views when `react_on_rails_pro` is installed. They extend the base `react_component` and `react_component_hash` helpers from the OSS gem. ### `cached_react_component(component_name, options = {}, &block)` Fragment-cached version of `react_component`. Skips prop evaluation and rendering when the cache is hit. **Key differences from `react_component`:** 1. Props must be passed as a block (so evaluation is deferred on cache hit) 2. `cache_key` option is required 3. Optional `cache_options` for Rails cache settings (`:expires_in`, `:compress`, `:race_condition_ttl`) 4. Optional `:if` / `:unless` for conditional caching ```ruby <%= cached_react_component("App", cache_key: [@user, @post], prerender: true) do { user: @user.as_json, post: @post.as_json } end %> ``` ### `cached_react_component_hash(component_name, options = {}, &block)` Fragment-cached version of `react_component_hash`. Automatically sets `prerender: true` (required because the hash return value splits server-rendered HTML from the console replay script). Returns a hash with `"html"` and `"consoleReplayScript"` keys. Same caching options as `cached_react_component`. ```ruby <% result = cached_react_component_hash("App", cache_key: [@user, @post]) do { user: @user.as_json } end %> <%= result["html"] %> <%= content_for :script_tags, result["consoleReplayScript"] %> ``` ### `stream_react_component(component_name, options = {})` Streams a server-rendered React component using React 18's `renderToPipeableStream`. Enables progressive rendering with Suspense boundaries. Requires the controller to use `stream_view_containing_react_components`. `stream_react_component` forces `prerender: true`; passing `prerender: false` has no effect. Common options mirror `react_component`, including `props`, `id`, `html_options`, `trace`, and `raise_on_prerender_error`. > **Note (Pro):** React on Rails Pro hydrates streamed components early (before `DOMContentLoaded`) automatically — no per-component toggle is exposed. ```ruby <%= stream_react_component("App", props: { data: @data }) %> ``` ### `buffered_stream_react_component(component_name, options = {})` Renders through the same streaming/RSC renderer as `stream_react_component`, but buffers every chunk and returns the complete HTML string to Rails. Use this for public, static, or cacheable pages where all props are available before rendering and progressive flushing is not needed. Unlike `stream_react_component`, this helper does not require the controller to use `stream_view_containing_react_components`. `buffered_stream_react_component` forces `prerender: true`; passing `prerender: false` has no effect. Common options mirror `stream_react_component`, including `props`, `id`, `html_options`, `trace`, `raise_on_prerender_error`, and `on_complete`. When provided, `on_complete` receives the buffered string chunks after rendering finishes; mutating those chunks does not change the returned HTML. ```ruby <%= buffered_stream_react_component("MarketingPage", props: @marketing_page_props, id: "marketing-page") %> ``` ### `stream_react_component_with_async_props(component_name, options = {}, &block)` Async-props variant of `stream_react_component`. Use this when the view has synchronous props plus slower values that should stream to React behind Suspense boundaries. Use this helper for RSC Server Components with `config.enable_rsc_support = true`. For non-RSC streaming SSR, use `stream_react_component`. Requires the controller to use `stream_view_containing_react_components`, same as `stream_react_component`. This helper accepts the same options as `stream_react_component`, plus a block that receives an emitter. Call `emit.call(prop_name, value)` for each async prop as it becomes available. RSC Server Components read emitted values through the injected `getReactOnRailsAsyncProp` prop. For the complete React component pattern using `WithAsyncProps` and `getReactOnRailsAsyncProp`, see [Data Fetching in React on Rails Pro](../migrating/rsc-data-fetching.md#data-fetching-in-react-on-rails-pro). ```ruby <%= stream_react_component_with_async_props("ProductPage", props: { name: @product.name, price: @product.price }) do |emit| emit.call("reviews", @product.reviews.as_json(only: [:id, :text, :rating])) end %> ``` > [!IMPORTANT] > `stream_react_component_with_async_props` requires `config.enable_rsc_support = true` and always forces `prerender: true`; passing `prerender: false` has no effect. The emitter block runs normal Ruby code sequentially, so `emit.call` does **not** parallelize slow queries by itself. For independent slow data sources, start the work concurrently before emitting values; see [Avoiding Server-Side Waterfalls](../migrating/rsc-data-fetching.md#avoiding-server-side-waterfalls). ### `cached_stream_react_component(component_name, options = {}, &block)` Fragment-cached version of `stream_react_component`. Cache hits replay stored chunks without re-rendering. Same caching options as `cached_react_component`. ### `cached_buffered_stream_react_component(component_name, options = {}, &block)` Fragment-cached version of `buffered_stream_react_component`. Cache hits return the complete buffered HTML string without evaluating the props block or re-rendering in Node. Cache key, tag, and expiry options are the same as `cached_react_component`. Unlike `cached_react_component`, this helper always forces `prerender: true`, so deploy bundle digests are always included in the cache key. It also uses a buffered-stream cache namespace so its complete HTML entries do not collide with streaming chunk entries. The `on_complete` callback is not supported because cache hits return complete buffered HTML without replaying chunks. ```ruby <%= cached_buffered_stream_react_component("MarketingPage", cache_key: ["marketing-page", I18n.locale], cache_tags: ["marketing-page"], cache_options: { expires_in: 30.minutes }, id: "marketing-page") do @marketing_page_props end %> ``` ### `cached_static_rsc_component(component_name, options = {}, &block)` Cached buffered RSC helper for static public pages that render server HTML but intentionally do not hydrate the generated page pack. It renders through `buffered_stream_react_component`, strips only embedded RSC payload/bootstrap scripts that reference `REACT_ON_RAILS_RSC_PAYLOADS`, and caches that stripped HTML. Use this when the page appends a small explicit sidecar pack for client effects instead of loading the generated component pack. Props must be passed as a block, `cache_key` is required, and `on_complete` is not supported because cache hits cannot replay chunk callbacks. The cache key is namespaced separately from `cached_buffered_stream_react_component` while still including the same deploy bundle digests via the Pro cache key builder. Unlike older cached helpers, an explicit `auto_load_bundle: false` is respected even when global `config.auto_load_bundle` is true. If `auto_load_bundle` is omitted, the global default is used. Set `rsc_render_diagnostics: true` or pass a callback to collect the static RSC render summary. The summary is also emitted in development and when `ReactOnRailsPro.configuration.tracing` is enabled via the `render_static_rsc_component.react_on_rails_pro` notification. It reports cache hit/miss status, a SHA-256 digest of the expanded cache key, effective `auto_load_bundle`, HTML byte counts, stripped RSC payload/bootstrap script counts and bytes, manifest-derived JS/CSS assets, and RSC client-reference manifest entries when those files are available. Use `rsc_diagnostic_packs:` to include explicit sidecar packs that the view appends outside the helper. ```ruby <%= cached_static_rsc_component("MarketingPage", cache_key: ["marketing-page", I18n.locale], cache_tags: ["marketing-page"], cache_options: { expires_in: 30.minutes }, auto_load_bundle: false, rsc_diagnostic_packs: ["generated/PublicPageClientEffects"], rsc_render_diagnostics: ->(summary) { Rails.logger.info(summary.to_json) }, id: "marketing-page") do @marketing_page_props end %> <%= javascript_pack_tag("generated/PublicPageClientEffects") %> ``` ### `rsc_payload_react_component(component_name, options = {})` Renders the React Server Component payload as NDJSON. Each line contains: - `html` — the RSC payload - `consoleReplayScript` — server-side console log replay - `hasErrors` — boolean - `isShellReady` — boolean Requires `enable_rsc_support = true` in configuration. This helper is normally used by `rsc_payload_route`; call it directly only when you need custom RSC payload rendering. Common options include `props`, `trace`, and `id`. The helper forces `prerender: true`; passing `prerender: false` has no effect. ```ruby <%= rsc_payload_react_component("RSCPage", props: { id: @post.id }) %> ``` ### `rsc_payload_react_component_with_async_props(component_name, options = {}, &block)` Async-props variant of `rsc_payload_react_component`. Use this only when custom RSC payload rendering needs Rails-emitted async props, such as an overridden payload route or template. For standard streamed ERB views, use `stream_react_component_with_async_props`. Requires `enable_rsc_support = true` in configuration, same as `rsc_payload_react_component`. This helper accepts the same options as `rsc_payload_react_component`, plus a block that receives an emitter. Call `emit.call(prop_name, value)` for each async prop. ```ruby <%= rsc_payload_react_component_with_async_props("ProductPage", props: { name: @product.name, price: @product.price }) do |emit| emit.call("reviews", @product.reviews.as_json(only: [:id, :text, :rating])) end %> ``` > [!IMPORTANT] > `rsc_payload_react_component_with_async_props` requires `config.enable_rsc_support = true` and always forces `prerender: true`; passing `prerender: false` has no effect. The emitter block runs normal Ruby code sequentially, so `emit.call` does **not** parallelize slow queries by itself. For independent slow data sources, start the work concurrently before emitting values; see [Avoiding Server-Side Waterfalls](../migrating/rsc-data-fetching.md#avoiding-server-side-waterfalls). ### `async_react_component(component_name, options = {})` Renders a component asynchronously, returning an `AsyncValue`. Multiple calls execute concurrently. Requires the controller to include `ReactOnRailsPro::AsyncRendering` and call `enable_async_react_rendering`. ```ruby <% header = async_react_component("Header", props: @header_props) %> <% sidebar = async_react_component("Sidebar", props: @sidebar_props) %> <!-- Both render concurrently --> <%= header.value %> <%= sidebar.value %> ``` ### `cached_async_react_component(component_name, options = {}, &block)` Combines async rendering with fragment caching. Cache lookup is synchronous — hits return immediately, misses trigger async render and cache the result. ```ruby <% card = cached_async_react_component("ProductCard", cache_key: @product) { @product.to_props } %> <%= card.value %> ``` ## Utility Methods ### `ReactOnRailsPro::Utils` | Method | Description | | ---------------------------------------- | --------------------------------------------------------------------- | | `rsc_bundle_js_file_path` | Resolved path to the RSC bundle file | | `react_client_manifest_file_path` | Resolved path to the React client manifest | | `react_server_client_manifest_file_path` | Resolved path to the server-client manifest | | `rsc_support_enabled?` | Whether RSC support is enabled in configuration | | `license_status` | Current license status (`:valid`, `:expired`, `:invalid`, `:missing`) | | `bundle_hash` | Cache-key component based on server bundle content | | `rsc_bundle_hash` | Cache-key component based on RSC bundle content | | `server_bundle_file_name` | Hashed filename of the server bundle (for cache keys) | | `digest_of_globs(globs)` | MD5 digest of files matching the given glob patterns | | `copy_assets` | Copies configured `assets_to_copy` to the node renderer | ## Source - [View Helpers](https://github.com/shakacode/react_on_rails/blob/main/react_on_rails_pro/app/helpers/react_on_rails_pro_helper.rb) - [Utils](https://github.com/shakacode/react_on_rails/blob/main/react_on_rails_pro/lib/react_on_rails_pro/utils.rb) ================================================================================ PAGE: https://reactonrails.com/docs/api-reference/generator-details SOURCE: docs/oss/api-reference/generator-details.md ================================================================================ # Generator Details The `react_on_rails:install` generator combined with the example pull requests of generator runs will get you up and running efficiently. There's a fair bit of setup with integrating a bundler with Rails. Most options default to off. The exception is the bundler: **fresh installs now default to Rspack**, so pass `--no-rspack` (or its alias `--webpack`) if you want Webpack instead. Existing apps that already declare a bundler in `config/shakapacker.yml` are left unchanged. Run `rails generate react_on_rails:install --help` for descriptions of all available options: ```text Usage: rails generate react_on_rails:install [options] Options: -T, [--typescript], [--no-typescript] # Generate TypeScript files and install TypeScript dependencies. Default: false [--rspack], [--no-rspack] # Use Rspack (default) as the bundler; pass --no-rspack to use Webpack [--webpack], [--no-webpack] # Use Webpack as the bundler (alias for --no-rspack) [--tailwind], [--no-tailwind] # Install Tailwind CSS v4 and style the generated SSR example. Default: false [--pro], [--no-pro] # Install React on Rails Pro with Node Renderer. Default: false [--rsc], [--no-rsc] # Install React Server Components support (includes Pro). Default: false [--ignore-warnings], [--no-ignore-warnings] # Skip warnings. Default: false Runtime options: -f, [--force] # Overwrite files that already exist -p, [--pretend], [--no-pretend] # Run but do not make any changes -q, [--quiet], [--no-quiet] # Suppress status output -s, [--skip], [--no-skip] # Skip files that already exist Description: The react_on_rails:install generator integrates a JavaScript bundler with Rails with ease. Fresh installs use Rspack by default; pass --no-rspack to use Webpack. You can pass the options below to customize the generated example and supporting configuration. ``` > [!WARNING] > The Redux installer path (`--redux` / `-R`) is a hidden legacy escape hatch, not > a recommended starter architecture. New apps should start with the > `react_component` view helper, React local state or context for island-local UI > state, and Rails props or server-state tools such as TanStack Query for data > loaded from the server. Use Redux only for an existing Redux app or an advanced > multi-island page where separate React roots must coordinate through one shared > client store. Additional option details: - **TypeScript**: Passing the `--typescript` generator option generates TypeScript files (`.tsx`) instead of JavaScript files (`.jsx`) and sets up TypeScript configuration. - **Tailwind CSS v4**: Passing the `--tailwind` generator option installs Tailwind CSS v4, configures `@tailwindcss/postcss` for Webpack or Rspack, and styles the generated SSR HelloWorld page. See [Styling with Tailwind CSS v4](../building-features/styling-with-tailwind.md). - **Rspack (default)**: Rspack is the default bundler for fresh installs, providing significantly faster builds (~20x improvement with SWC). Pass `--no-rspack` (or its alias `--webpack`) to use Webpack instead. Either way you get a unified configuration that works with both bundlers and a `bin/switch-bundler` utility to switch between them post-installation. - **Pro**: Passing the `--pro` generator option sets up React on Rails Pro with Node server rendering, fragment caching, and code-splitting support. Requires the `react_on_rails_pro` gem (add it to your Gemfile first). Creates the Pro initializer, `renderer/node-renderer.js`, and adds the Node Renderer process to `Procfile.dev`. - **RSC (React Server Components)**: Passing the `--rsc` generator option sets up React Server Components support. This automatically includes Pro setup (`--rsc` implies `--pro`). Creates RSC webpack configuration, a HelloServer example component, and RSC routes. Requires React 19 with a compatible `react-on-rails-rsc` version. Then you may run `rails s`. Another good option is to create a simple test app per the [Tutorial](../getting-started/tutorial.md). ## Understanding the Organization of the Generated Client Code The React on Rails generator normally creates the simple component structure below. A hidden legacy Redux path remains available for existing apps and recovery work, but it is not the structure recommended for new React on Rails apps. ### Default Structure (Recommended, Without Redux) The basic generator creates a simple, flat structure optimized for auto-bundling: ```text app/javascript/ └── src/ └── HelloWorld/ └── ror_components/ # Components auto-registered by React on Rails ├── HelloWorld.jsx # Your React component ├── HelloWorld.module.css └── HelloWorld.server.js # Optional: separate server rendering logic ``` - **`src/`**: Source directory for all React components - **`ror_components/`**: Directory name is configurable via `config.components_subdirectory` in `config/initializers/react_on_rails.rb` - **Auto-registration**: Components in `ror_components/` directories are automatically discovered and registered when using `auto_load_bundle: true` For components that need different client vs. server implementations, use `.client.jsx` and `.server.jsx` suffixes (e.g., `HelloWorld.client.jsx` and `HelloWorld.server.jsx`). ### Legacy Redux Structure (Hidden `--redux` Path) The hidden legacy Redux generator creates a more structured organization with familiar Redux patterns: ```text app/javascript/ └── src/ └── HelloWorldApp/ ├── actions/ # Redux action creators │ └── helloWorldActionCreators.js ├── components/ # Presentational components │ ├── HelloWorld.jsx │ └── HelloWorld.module.css ├── constants/ # Action type constants │ └── helloWorldConstants.js ├── containers/ # Connected components (smart components) │ └── HelloWorldContainer.js ├── reducers/ # Redux reducers │ └── helloWorldReducer.js ├── ror_components/ # Auto-registered entry points │ ├── HelloWorldApp.client.jsx │ └── HelloWorldApp.server.jsx └── store/ # Redux store configuration └── helloWorldStore.js ``` This legacy structure is useful only when you intentionally maintain Redux: - **`components/`**: Presentational "dumb" components that receive data via props - **`containers/`**: Container "smart" components connected to Redux store - **`actions/`** and **`reducers/`**: Standard Redux patterns - **`ror_components/`**: Entry point files that initialize Redux and render the app If you already have a React on Rails app and intentionally need to recreate the legacy Redux example, use the direct hidden generator after the base installer has configured React on Rails: ```bash rails generate react_on_rails:react_with_redux ``` For an app that is already configured for TypeScript, add `--typescript` to generate `.ts` and `.tsx` Redux example files. > **Note:** The standalone `react_on_rails:react_with_redux` generator does not support `--tailwind`. > If you intentionally need the legacy Redux scaffold with Tailwind, run the full installer path instead: > `rails generate react_on_rails:install --redux --tailwind`. For full install recovery of an older Redux-generated app, the hidden `react_on_rails:install --redux` option still exists, but do not use it for greenfield apps. ### TypeScript Support The generator also supports a `--typescript` option for generating TypeScript files: ```bash rails generate react_on_rails:install --typescript ``` This creates `.tsx` files instead of `.jsx` and adds TypeScript configuration. ### Rspack Support Rspack is the default bundler for fresh installs, so a plain install gives you Rspack: ```bash # Rspack (default) rails generate react_on_rails:install # Webpack instead (--webpack is an alias for --no-rspack) rails generate react_on_rails:install --no-rspack ``` The default applies only to fresh installs. If `config/shakapacker.yml` already declares an `assets_bundler`, the generator keeps your existing choice. An explicit `--rspack` / `--no-rspack` (or its `--webpack` alias) always wins. (Rspack requires Shakapacker 9.0+; on older Shakapacker the generator falls back to Webpack.) **Benefits:** - **~20x faster builds** with SWC transpilation (build times of ~53-270ms vs typical webpack builds) - **Unified configuration** - same webpack config files work for both bundlers - **Easy switching** - includes `bin/switch-bundler` utility to switch between bundlers post-installation **What gets installed:** - Rspack core packages (`@rspack/core`, `@rspack/cli`) - Rspack-specific plugins (`@rspack/plugin-react-refresh`, `rspack-manifest-plugin`) - Shakapacker configured with `assets_bundler: 'rspack'` and `webpack_loader: 'swc'` **Switching bundlers after installation:** ```bash # Switch to Rspack bin/switch-bundler rspack # Switch back to Webpack bin/switch-bundler webpack ``` The switch-bundler script automatically: - Updates shakapacker.yml configuration - Installs/removes appropriate dependencies - Works with npm, yarn, and pnpm **Limitations of `bin/switch-bundler`:** The switch-bundler utility handles the standard configuration and dependencies, but has some limitations: - **Custom webpack plugins**: Does not modify custom webpack plugins or loaders in your config files - **Manual updates needed**: If you have custom webpack configuration, you may need to update it to use unified patterns (see examples in [Webpack Configuration](../core-concepts/webpack-configuration.md#unified-configuration)) - **Third-party dependencies**: Does not detect or update third-party webpack-specific packages you may have added - **YAML formatting**: Uses YAML.dump which may change formatting/whitespace (but preserves functionality) For apps with custom webpack configurations, review the generated config templates to understand the unified configuration patterns that work with both bundlers. **Combining with other options:** ```bash # Rspack (default) with TypeScript rails generate react_on_rails:install --typescript # Webpack with TypeScript rails generate react_on_rails:install --no-rspack --typescript ``` For more details on Rspack configuration, see the [Webpack Configuration](../core-concepts/webpack-configuration.md#rspack-vs-webpack) docs. ### React on Rails Pro Support The generator supports a `--pro` option for setting up React on Rails Pro with Node server rendering, fragment caching, and code-splitting support: ```bash rails generate react_on_rails:install --pro ``` **Prerequisites:** - Add `gem 'react_on_rails_pro'` to your Gemfile and run `bundle install` (check [the CHANGELOG](https://github.com/shakacode/react_on_rails/blob/main/CHANGELOG.md) for the latest version) - Under ShakaCode Trust-Based Commercial Licensing, no token is needed for evaluation, development, test, CI/CD, or staging - For production, get a license from [Pro pricing and sign up](https://pro.reactonrails.com/) or contact [justin@shakacode.com](mailto:justin@shakacode.com) **What gets created:** - `config/initializers/react_on_rails_pro.rb` - Pro configuration with Node Renderer settings - `renderer/node-renderer.js` - Node Renderer bootstrap file - Node Renderer process added to `Procfile.dev` - Pro npm packages (`react-on-rails-pro`, `react-on-rails-pro-node-renderer`) **After installation:** For production, configure your license token: `export REACT_ON_RAILS_PRO_LICENSE="your-token"`. See [LICENSE_SETUP.md](https://github.com/shakacode/react_on_rails/blob/main/react_on_rails_pro/LICENSE_SETUP.md) for all options. **Combining with other options:** ```bash # Pro with TypeScript rails generate react_on_rails:install --pro --typescript # Pro with Rspack rails generate react_on_rails:install --pro --rspack ``` The standalone Pro generator also modifies `config/webpack/serverWebpackConfig.js` (enables `libraryTarget: 'commonjs2'`, adds `extractLoader`, sets `target = 'node'`, changes exports to object style) and updates the import in `config/webpack/ServerClientOrBoth.js`. If your webpack configs use the legacy filename `generateWebpackConfigs.js`, the generator will rename it automatically. **Upgrading an existing React on Rails app to Pro:** For existing apps, use the standalone Pro generator to avoid re-processing base files: ```bash rails generate react_on_rails:pro ``` See the [React on Rails Pro overview](../../pro/react-on-rails-pro.md) for feature details. ### React Server Components Support The generator supports a `--rsc` option for setting up React Server Components: ```bash rails generate react_on_rails:install --rsc ``` **Note:** `--rsc` automatically includes Pro setup (`--rsc` implies `--pro`). **Prerequisites:** - React on Rails Pro gem installed (see Pro prerequisites above) - React 19 with a compatible `react-on-rails-rsc` version RSC builds on React on Rails Pro's Node rendering infrastructure. The generator adds a separate webpack entry point for server components, configures the `RSCWebpackPlugin` in both client and server webpack configs, and sets up the `RSC_BUNDLE_ONLY` environment variable handling in `ServerClientOrBoth.js` for independent RSC bundle compilation. **What gets created:** In addition to all Pro files: - `config/webpack/rscWebpackConfig.js` or `config/rspack/rscWebpackConfig.js` - RSC-specific bundler configuration - `app/javascript/src/HelloServer/` - Example RSC component (replaces HelloWorld) - `app/controllers/hello_server_controller.rb` - Controller with streaming support - `app/views/hello_server/index.html.erb` - View using `stream_react_component` - RSC routes (`rsc_payload_route`, `hello_server`) - RSC bundle watcher added to `Procfile.dev` - RSC npm package (`react-on-rails-rsc`) **Combining with other options:** ```bash # RSC with TypeScript rails generate react_on_rails:install --rsc --typescript # RSC with Rspack rails generate react_on_rails:install --rsc --rspack ``` Do not combine RSC with the hidden legacy Redux installer for new apps. Existing Redux Client Components can continue to work beside RSC when Redux access stays in Client Components; see [RSC context and state migration](../migrating/rsc-context-and-state.md#redux-toolkit). **Upgrading an existing Pro app to RSC:** For existing Pro apps, use the standalone RSC generator: ```bash rails generate react_on_rails:rsc rails generate react_on_rails:rsc --typescript ``` See the [RSC performance guide](../../pro/major-performance-breakthroughs-upgrade-guide.md) for details. ### Auto-Bundling and Component Registration Modern React on Rails uses auto-bundling to eliminate manual webpack configuration. Components placed in the configured `components_subdirectory` (default: `ror_components`) are automatically: 1. Discovered by the generator 2. Bundled into separate webpack entry points 3. Registered for use with `react_component` helper 4. Loaded on-demand when used in views For detailed information on auto-bundling, see the [Auto-Bundling Guide](../core-concepts/auto-bundling-file-system-based-automated-bundle-generation.md). ================================================================================ PAGE: https://reactonrails.com/docs/api-reference/rails-view-rendering-from-inline-javascript SOURCE: docs/oss/api-reference/rails-view-rendering-from-inline-javascript.md ================================================================================ # Using ReactOnRails in JavaScript You can easily render React components in your JavaScript with the `render` method. Under React 18+, it returns a React root. Under React 16/17, legacy return values vary by render or hydrate path, such as a component instance, an element, or `void`. ```js /** * ReactOnRails.render("HelloWorldApp", {name: "Stranger"}, 'app'); * * Under React 16/17, this is equivalent to: * ReactDOM.render(React.createElement(HelloWorldApp, {name: "Stranger"}), * document.getElementById('app')) * * Under React 18+, it uses: * const root = ReactDOMClient.createRoot(document.getElementById('app')); * root.render(React.createElement(HelloWorldApp, {name: "Stranger"})); * return root; * * @param name Name of your registered component * @param props Props to pass to your component * @param domNodeId * @param hydrate [optional] Pass truthy to update server rendered html. Default is falsy * @returns {Root|Component|Element|void} React root in React 18+, or legacy return values in * React 16/17 depending on the render or hydrate path */ ReactOnRails.render(componentName, props, domNodeId); ``` ## Why do we need this? Imagine that some external JavaScript decides when a component should mount with the current value. ```html <input id="input" type="range" min="0" max="100" /> <div id="root"></div> <script> const input = document.getElementById('input'); ReactOnRails.render('componentName', { value: input.value }, 'root'); </script> ``` For subsequent updates on the same DOM node, let the mounted React component manage its own state or props flow. The public `ReactOnRails.render` API does not deduplicate repeated calls, so calling it on `#root` will invoke React unless you unmount or replace that node first. ================================================================================ PAGE: https://reactonrails.com/docs/deployment SOURCE: docs/oss/deployment/README.md ================================================================================ # Deployment > [!NOTE] > **Summary for AI agents:** Use this page to route to the correct deployment guide. For Docker/Kamal/Kubernetes/Control Plane, see [Docker Deployment](./docker-deployment.md). For Heroku, see [Heroku Deployment](./heroku-deployment.md). For SSR issues in production, see [Troubleshooting](./troubleshooting.md). ## Deployment guides - [Docker Deployment](./docker-deployment.md) — Containerized deployments with Kamal, Kubernetes, and Control Plane - [Heroku Deployment](./heroku-deployment.md) — PaaS deployment on Heroku - [Review App Security](./review-app-security.md) — Safe review-app defaults for public repositories and fork PRs - [Security Model and Hardening](./security-model-and-hardening.md) — Props escaping contract, Node renderer threat model, RSC advisory posture ## Troubleshooting - [Server Rendering Tips](./server-rendering-tips.md) — SSR debugging and optimization - [Troubleshooting Build Errors](./troubleshooting-build-errors.md) — Webpack build issues - [Troubleshooting](./troubleshooting.md) — General deployment troubleshooting - [Troubleshooting Shakapacker](./troubleshooting-when-using-shakapacker.md) — Shakapacker-specific issues - [Troubleshooting Webpacker](./troubleshooting-when-using-webpacker.md) — Webpacker-specific issues ## Archived guides These legacy guides were removed but are available in git history: - [Capistrano Deployment](https://github.com/shakacode/react_on_rails/blob/b3d30a15c/docs/oss/deployment/capistrano-deployment.md) - [Elastic Beanstalk](https://github.com/shakacode/react_on_rails/blob/a5312aeb6/docs/oss/deployment/elastic-beanstalk.md) ================================================================================ PAGE: https://reactonrails.com/docs/deployment/docker-deployment SOURCE: docs/oss/deployment/docker-deployment.md ================================================================================ # Docker Deployment This guide covers deploying a React on Rails application using Docker containers, with specific instructions for Kamal, Kubernetes, and Control Plane. ## Dockerfile for React on Rails Rails 7.1+ ships with a production-ready `Dockerfile`. React on Rails needs Node.js available during the build stage to compile JavaScript bundles. Here is a representative multi-stage Dockerfile: ```dockerfile # syntax=docker/dockerfile:1 ARG RUBY_VERSION=3.3 ARG NODE_VERSION=20 ############################################################################### # Base stage — shared between build and runtime ############################################################################### FROM docker.io/library/ruby:$RUBY_VERSION-slim AS base WORKDIR /rails ENV RAILS_ENV="production" \ NODE_ENV="production" \ BUNDLE_DEPLOYMENT="1" \ BUNDLE_PATH="/usr/local/bundle" \ BUNDLE_WITHOUT="development:test" ############################################################################### # Build stage — install gems, Node, and compile assets ############################################################################### FROM base AS build # Install build dependencies RUN apt-get update -qq && \ apt-get install --no-install-recommends -y \ build-essential curl git libpq-dev node-gyp pkg-config python-is-python3 && \ rm -rf /var/lib/apt/lists/* # Install Node.js and Yarn (or use corepack for pnpm/yarn) ARG NODE_VERSION RUN curl -fsSL https://deb.nodesource.com/setup_${NODE_VERSION}.x | bash - && \ apt-get install --no-install-recommends -y nodejs && \ corepack enable && \ rm -rf /var/lib/apt/lists/* # Install gems COPY Gemfile Gemfile.lock ./ RUN bundle install && \ rm -rf ~/.bundle/ "${BUNDLE_PATH}"/ruby/*/cache "${BUNDLE_PATH}"/ruby/*/bundler/gems/*/.git # Install JS dependencies COPY package.json yarn.lock ./ RUN yarn install --immutable # Yarn Berry (v2+); for Yarn Classic (v1), use --frozen-lockfile # Copy the full application COPY . . # Precompile assets (builds client and server bundles) RUN SECRET_KEY_BASE_DUMMY=1 bundle exec rails assets:precompile # Remove node_modules — not needed at runtime and saves hundreds of MBs RUN rm -rf node_modules ############################################################################### # Runtime stage — lean image for production ############################################################################### FROM base # Install runtime dependencies only RUN apt-get update -qq && \ apt-get install --no-install-recommends -y libpq5 && \ rm -rf /var/lib/apt/lists/* # Copy built artifacts COPY --from=build "${BUNDLE_PATH}" "${BUNDLE_PATH}" COPY --from=build /rails /rails # Create non-root user RUN groupadd --system --gid 1000 rails && \ useradd rails --uid 1000 --gid 1000 --create-home --shell /bin/bash && \ chown -R rails:rails db log storage tmp USER 1000:1000 ENTRYPOINT ["/rails/bin/docker-entrypoint"] EXPOSE 3000 CMD ["bundle", "exec", "puma", "-C", "config/puma.rb"] ``` [Diagram: A three-stage Docker build for React on Rails. The base stage sets the shared Ruby image and production environment. The build stage adds Node.js and build tools, installs gems and JS dependencies, runs assets:precompile to build the client and server bundles, then deletes node_modules. The runtime stage starts fresh from base and copies in only the built artifacts — gems, compiled bundles, and app code — leaving Node.js and node_modules behind, producing a lean production image hundreds of megabytes smaller.] ### Key points - **Node.js is only needed at build time.** The runtime stage does not include Node unless you use the Pro Node Renderer (see [Node Renderer in containers](#node-renderer-in-containers) below). - **`SECRET_KEY_BASE_DUMMY=1`** lets `assets:precompile` run without a real secret. Rails 7.1+ supports this natively. - **Server bundles** land in `ssr-generated/` (private, never served to browsers) while client bundles land in `public/webpack/production/`. Both are copied into the runtime image. - If you use `config.build_production_command`, it runs during `assets:precompile`. See [Configuration](../configuration/README.md#build_production_command). - **Add a `.dockerignore` file** to prevent host-specific files from being copied into the build. Without it, `COPY . .` can overwrite the freshly installed `node_modules/` with modules built for a different OS/architecture. A minimal `.dockerignore` (expand as appropriate for your project): ```text node_modules .git log tmp spec test .github ``` ### Using pnpm instead of Yarn Replace the Yarn lines with: ```dockerfile RUN corepack enable && corepack prepare pnpm@10.33.4 --activate # match packageManager in package.json COPY package.json pnpm-lock.yaml ./ RUN pnpm install --frozen-lockfile ``` ## Environment variables Set these at runtime (not baked into the image): | Variable | Purpose | | -------------------------- | --------------------------------------------------------------------- | | `SECRET_KEY_BASE` | Rails secret key | | `DATABASE_URL` | Database connection string | | `RAILS_SERVE_STATIC_FILES` | Set to `true` when there is no CDN or reverse proxy serving `/public` | | `RAILS_LOG_TO_STDOUT` | Set to `true` for container log collection | | `RAILS_ENV` | Should be `production` | ## Deploying with Kamal [Kamal](https://kamal-deploy.org/) deploys Docker containers to bare servers over SSH using Traefik as a reverse proxy. It is the default deployment tool for Rails 8. ### Setup ```bash bundle add kamal kamal init ``` ### config/deploy.yml ```yaml service: myapp image: your-registry/myapp servers: web: hosts: - 192.168.0.1 options: memory: 512m proxy: ssl: true host: myapp.example.com registry: server: ghcr.io username: your-username password: - KAMAL_REGISTRY_PASSWORD env: clear: RAILS_SERVE_STATIC_FILES: true RAILS_LOG_TO_STDOUT: true secret: - SECRET_KEY_BASE - DATABASE_URL builder: arch: amd64 ``` ### Deploy ```bash kamal setup # first deploy — provisions Traefik kamal deploy # subsequent deploys ``` ### Kamal tips for React on Rails - **Build caching**: Kamal uses Docker layer caching. Structure your Dockerfile so `Gemfile.lock` and `yarn.lock` are copied before the full source to maximize cache hits. - **Health checks**: Kamal probes `/up` by default (Rails 7.1+). Ensure this route is defined. - **Asset serving**: Set `RAILS_SERVE_STATIC_FILES=true` or configure an asset host / CDN. - **Memory**: Webpack/Rspack compilation is memory-intensive. If building on the server, allocate at least 2 GB for the builder. Using remote builds (`builder.remote`) avoids this issue. ## Deploying with Kubernetes ### Container image Build and push your image to a container registry: ```bash docker build -t your-registry/myapp:latest . docker push your-registry/myapp:latest ``` ### Deployment manifest ```yaml apiVersion: apps/v1 kind: Deployment metadata: name: myapp spec: replicas: 2 selector: matchLabels: app: myapp template: metadata: labels: app: myapp spec: containers: - name: rails image: your-registry/myapp:latest ports: - containerPort: 3000 env: - name: RAILS_ENV value: production - name: RAILS_SERVE_STATIC_FILES value: 'true' - name: RAILS_LOG_TO_STDOUT value: 'true' - name: SECRET_KEY_BASE valueFrom: secretKeyRef: name: myapp-secrets key: secret-key-base - name: DATABASE_URL valueFrom: secretKeyRef: name: myapp-secrets key: database-url readinessProbe: httpGet: path: /up port: 3000 initialDelaySeconds: 5 periodSeconds: 10 livenessProbe: httpGet: path: /up port: 3000 initialDelaySeconds: 60 periodSeconds: 20 resources: requests: memory: '256Mi' cpu: '250m' limits: memory: '512Mi' cpu: '1000m' --- apiVersion: v1 kind: Service metadata: name: myapp spec: selector: app: myapp ports: - port: 80 targetPort: 3000 type: ClusterIP ``` ### Kubernetes tips for React on Rails - **Secrets**: Use Kubernetes Secrets with `secretKeyRef` (as shown above) rather than hardcoding values directly in the `env` section. Never commit secret values to your manifest files. - **Migrations**: Run migrations as a Kubernetes Job or init container before the Deployment rolls out: > [!WARNING] > With `replicas > 1`, each pod's init container runs concurrently. Prefer a Kubernetes Job for migrations unless every migration is idempotent. ```yaml initContainers: - name: migrate image: your-registry/myapp:latest command: ['bundle', 'exec', 'rails', 'db:migrate'] env: - name: RAILS_ENV value: production - name: DATABASE_URL valueFrom: secretKeyRef: name: myapp-secrets key: database-url - name: SECRET_KEY_BASE valueFrom: secretKeyRef: name: myapp-secrets key: secret-key-base ``` - **Horizontal Pod Autoscaler**: Scale based on CPU or custom metrics. React on Rails apps doing SSR are CPU-bound, so CPU-based scaling is a good starting point. - **Ingress**: Use an Ingress controller (nginx-ingress, Traefik, etc.) with TLS termination in front of the Service. ## Deploying with Control Plane [Control Plane](https://controlplane.com/) provides Heroku-like ease of use with Kubernetes-level infrastructure. ShakaCode maintains the [Control Plane Flow](https://github.com/shakacode/control-plane-flow/) gem (`cpflow`) for Rails deployments. ### Setup ```bash gem install cpflow cpflow setup ``` This creates a `.controlplane/` directory with configuration templates. ### .controlplane/controlplane.yml ```yaml aliases: common: &common cpln_org: your-org location: aws-us-east-2 one_off_workload: rails app_workloads: - rails additional_workloads: - redis - postgres apps: myapp: <<: *common ``` ### .controlplane/templates/rails.yml Control Plane workloads are similar to Kubernetes Deployments. Key settings for React on Rails: ```yaml kind: workload name: rails spec: type: standard containers: - name: rails cpu: '500m' memory: 512Mi ports: - number: 3000 protocol: http env: - name: RAILS_ENV value: production - name: RAILS_SERVE_STATIC_FILES value: 'true' - name: RAILS_LOG_TO_STDOUT value: 'true' - name: SECRET_KEY_BASE value: 'cpln://secret/myapp-secrets.SECRET_KEY_BASE' - name: DATABASE_URL value: 'cpln://secret/myapp-secrets.DATABASE_URL' readinessProbe: httpGet: path: /up port: 3000 initialDelaySeconds: 5 periodSeconds: 10 livenessProbe: httpGet: path: /up port: 3000 initialDelaySeconds: 60 periodSeconds: 20 ``` ### Deploy ```bash cpflow build-image -a myapp # build + push image to registry cpflow deploy-image -a myapp # deploy the pushed image to Control Plane ``` ### Control Plane tips for React on Rails - **GVC environment variables**: Set shared environment variables at the GVC level so all workloads inherit them. See the [Control Plane Flow guide to secrets and ENV values](https://github.com/shakacode/control-plane-flow/blob/main/docs/secrets-and-env-values.md). - **Secrets**: Use Control Plane's built-in secrets management (`cpln://secret/...`) instead of environment variables for sensitive values. - **One-off tasks**: Run migrations and other one-off commands via `cpflow run -a myapp -- bundle exec rails db:migrate`. - **Public demo and starter staging apps**: Keep `type: standard` workloads with `minScale: 1`, the autoscaling metric disabled, and `capacityAI: true`. Avoid CPU Utilization autoscaling pinned to `minScale: 1` / `maxScale: 1`, because that prevents Capacity AI from right-sizing the warm workload. When the autoscaling metric is disabled, do not rely on `maxScale` for bursts; use a compatible autoscaling metric for that separate scaling posture. Use `serverless` scale-to-zero only as an explicit first-deploy choice or planned delete/recreate migration. See the [Control Plane Flow capacity tips](https://github.com/shakacode/control-plane-flow/blob/main/docs/tips.md#enable-capacity-ai-for-demo-and-starter-staging-apps). - **Multiple locations**: Control Plane supports multi-region deployment. Add locations to your GVC to deploy globally. ## Node Renderer in containers If you use [React on Rails Pro's Node Renderer](../building-features/node-renderer/basics.md) for high-performance SSR, the runtime image needs Node.js. ### Multi-container setup Run the Node Renderer as a separate container/sidecar alongside the Rails container. The node-renderer container needs a separate image that includes Node.js — the main runtime image from the [Dockerfile above](#dockerfile-for-react-on-rails) does not include Node. ```yaml # Kubernetes example — two containers in one Pod containers: - name: rails image: your-registry/myapp:latest ports: - containerPort: 3000 env: - name: REACT_RENDERER_URL value: 'http://localhost:3800' - name: node-renderer image: your-registry/myapp-node-renderer:latest # must include Node.js command: ['node', 'renderer/node-renderer.js'] ports: - containerPort: 3800 env: - name: RENDERER_HOST value: '0.0.0.0' - name: RENDERER_PORT value: '3800' startupProbe: tcpSocket: port: 3800 initialDelaySeconds: 10 periodSeconds: 5 failureThreshold: 6 timeoutSeconds: 1 readinessProbe: # Omits initialDelaySeconds: startupProbe above defers readiness/liveness until boot succeeds (K8s 1.20+). # If you skip startupProbe or run an older cluster, add initialDelaySeconds to cover the boot window. # tcpSocket is a shallow fallback: port reachability only, not application readiness. tcpSocket: port: 3800 periodSeconds: 10 failureThreshold: 3 timeoutSeconds: 1 livenessProbe: # tcpSocket is port-open only; a hung event loop can still pass. For stricter hung-process # detection, use an exec probe with curl --http2-prior-knowledge and a short --max-time. tcpSocket: port: 3800 periodSeconds: 10 failureThreshold: 3 timeoutSeconds: 1 ``` > **Note:** `REACT_RENDERER_URL` must be read in your initializer for it to take effect: > > ```ruby > # config/initializers/react_on_rails_pro.rb > ReactOnRailsPro.configure do |config| > config.renderer_url = ENV["REACT_RENDERER_URL"] > end > ``` ### Configuration for containers When running the Node Renderer in containers: - Set `host` to `0.0.0.0` so health checks and the Rails container can reach it. See [Node Renderer configuration](../building-features/node-renderer/js-configuration.md). - On Control Plane, use `process.env.PORT` for the port — Control Plane assigns the port dynamically. See the [Control Plane port docs](https://docs.controlplane.com/reference/workload/containers#port-variable). - Set `workersCount` explicitly rather than relying on CPU auto-detection, which can over-allocate workers in constrained containers. - Use `tcpSocket` probes for shallow Kubernetes startup, readiness, and liveness checks. Kubernetes `httpGet` probes use HTTP/1.1 and cannot check the h2c-only Node Renderer listener directly. - The manifest above uses portable `tcpSocket` checks. For application-level readiness, use an `exec` probe with an h2c-capable client packaged in the renderer image, or expose a separate HTTP/1.1 health endpoint in your own application code. See [Configuring Startup, Readiness, and Liveness Probes](../building-features/node-renderer/js-configuration.md#configuring-startup-readiness-and-liveness-probes) for timing values and `curl --http2-prior-knowledge` examples. ## Static assets and CDN For all Docker deployments, choose one of: 1. **Rails serves static files** — Set `RAILS_SERVE_STATIC_FILES=true`. Simplest option, suitable for low-traffic apps. 2. **Reverse proxy serves files** — Nginx, Traefik, or a cloud load balancer serves files from `/public` directly. 3. **CDN** — Upload `public/webpack/production/` to a CDN and set `config.asset_host` in Rails. Best for global performance. ## Troubleshooting ### Assets missing at runtime If styles or JS are missing after deploy, verify: 1. `assets:precompile` ran successfully during `docker build` 2. Client bundles exist in `public/webpack/production/` in the built image 3. `RAILS_SERVE_STATIC_FILES=true` is set if there is no external file server ```bash # Check assets inside a running container docker exec <container> ls public/webpack/production/ ``` ### Out of memory during build Webpack/Rspack compilation can exceed default container memory. Solutions: - Increase Docker builder memory: `docker build --memory=4g` - Use a separate CI pipeline for image builds with higher resource limits - With Kamal, use `builder.remote` to offload builds to a more powerful machine ### Server rendering fails If SSR with ExecJS fails in the container but works locally: 1. Ensure `ssr-generated/server-bundle.js` exists in the image 2. Check that a JavaScript runtime is available. The Dockerfile above intentionally excludes Node from the runtime stage. If your app needs runtime JS execution (e.g. ExecJS), either add `mini_racer` to your Gemfile (no Node required) or install Node in the runtime stage. For high-performance SSR, consider the [Pro Node Renderer sidecar](#node-renderer-in-containers) instead. 3. Check logs: `RAILS_LOG_TO_STDOUT=true bundle exec rails console` and try `ReactOnRails::ServerRenderingPool.reset_pool` ## See also - [Heroku Deployment](./heroku-deployment.md) — PaaS deployment without Docker - [Configuration Reference](../configuration/README.md) — All React on Rails settings - [Node Renderer Configuration](../building-features/node-renderer/js-configuration.md) — Pro Node Renderer setup - [Server Rendering Tips](./server-rendering-tips.md) — SSR debugging and optimization - [Control Plane Flow](https://github.com/shakacode/control-plane-flow/) — cpflow gem for Control Plane deployments ================================================================================ PAGE: https://reactonrails.com/docs/deployment/heroku-deployment SOURCE: docs/oss/deployment/heroku-deployment.md ================================================================================ # Heroku Deployment > **Note:** This guide is based on the working tutorial app at [www.reactrails.com](https://www.reactrails.com). While the instructions work, some versions referenced are older. For current Heroku best practices with Rails 7, see [Heroku's Rails 7 Guide](https://devcenter.heroku.com/articles/getting-started-with-rails7). ## Create Your Heroku App _Assuming you can log in to heroku.com and have logged into your shell for Heroku._ 1. Visit [https://dashboard.heroku.com/new](https://dashboard.heroku.com/new) and create an app, say named `my-name-react-on-rails`:  Run this command that looks like this from your new Heroku app ```bash heroku git:remote -a my-name-react-on-rails ``` ## Heroku buildpacks React on Rails requires both a ruby environment (for Rails) and a Node environment (for Webpack), so you will need to have Heroku use multiple buildpacks. Set heroku to use multiple buildpacks: ```bash heroku buildpacks:set heroku/ruby heroku buildpacks:add --index 1 heroku/nodejs ``` For more information, see [Using Multiple Buildpacks for an App](https://devcenter.heroku.com/articles/using-multiple-buildpacks-for-an-app) ## Swap out sqlite for postgres Heroku requires your app to use Postgresql. If you have not set up your app with Postgresql, you need to change your app settings to use this database. Run the following command (in Rails 6+): ```bash rails db:system:change --to=postgresql ``` If for any reason you want to do this process manually, run these two commands: ```bash bundle remove sqlite3 bundle add pg ```  Now replace your `database.yml` file with this (assuming your app name is "ror"). ```yml default: &default adapter: postgresql username: password: host: localhost development: <<: *default database: ror_development # Warning: The database defined as "test" will be erased and # re-generated from your development database when you run "rake". # Do not set this db to the same as development or production. test: <<: *default database: ror_test production: <<: *default database: ror_production ``` Then you need to set up Postgres so you can run locally: ```bash rake db:setup rake db:migrate ```  Optionally you can add this line to your `routes.rb`. That way, your root page will go to the Hello World page for React On Rails. ```ruby root "hello_world#index" ```  ## Configure Puma Next, configure your app for Puma, per the [instructions on Heroku](https://devcenter.heroku.com/articles/deploying-rails-applications-with-the-puma-web-server). Create `./Procfile` with the following content. This is what Heroku uses to start your app. ```procfile web: bundle exec puma -C config/puma.rb ``` Note, newer versions of Rails create this file automatically. However, the [docs on Heroku](https://devcenter.heroku.com/articles/deploying-rails-applications-with-the-puma-web-server#config) have something a bit different, so please make it conform to those docs. As of 2020-06-04, the docs looked like this: `config/puma.rb` ```rb workers Integer(ENV['WEB_CONCURRENCY'] || 2) threads_count = Integer(ENV['RAILS_MAX_THREADS'] || 5) threads threads_count, threads_count preload_app! rackup DefaultRackup port ENV['PORT'] || 3000 environment ENV['RACK_ENV'] || 'development' on_worker_boot do # Worker specific setup for Rails 4.1+ # See: https://devcenter.heroku.com/articles/deploying-rails-applications-with-the-puma-web-server#on-worker-boot ActiveRecord::Base.establish_connection end ``` ## Specify Node and Yarn versions Next, update your `package.json` to specify the version of yarn and node. Add this section: ```json "engines": { "node": "20.0.0", "yarn": "1.22.4" }, ``` ## Deploy Then after all changes are done don't forget to commit them with git and finally, you can push your app to Heroku! ```bash git add -A git commit -m "Changes for Heroku" git push heroku master ``` Then run: ```bash heroku open ``` and you will see your live app and you can share this URL with your friends. Congrats! ## assets:precompile ### Shakapacker Webpack configuration Shakapacker hooks up a new `shakapacker:compile` task to `assets:precompile`, which gets run whenever you run `assets:precompile`. If you are not using Sprockets, `shakapacker:compile` is automatically aliased to `assets:precompile`. If you're using the standard `shakacode/shakapacker` configuration for Webpack, then `shakacode/shakapacker` will automatically modify or create an `assets:precompile` task to build your assets. Alternatively, you can specify `config.build_production_command` to have `react_on_rails` invoke a command for you during `assets:precompile`. ```bash config.build_production_command = "RAILS_ENV=production NODE_ENV=production bin/shakapacker" ``` ### Consider Removing Shakapacker's clean task If you are deploying on Heroku, then you don't need Shakapacker's clean task which might delete files that you need. ```bash Rake::Task['shakapacker:clean'].clear ``` ================================================================================ PAGE: https://reactonrails.com/docs/deployment/review-app-security SOURCE: docs/oss/deployment/review-app-security.md ================================================================================ # Review App Security Review apps are useful for validating React on Rails changes in a production-like environment, but they run the code from a pull request. In public repositories, treat review-app deployment as execution of untrusted code. ## Recommended Policy - Allow automatic review-app deployments only for pull requests whose branch is in the same repository. - Require an explicit maintainer action before deploying a review app for a forked pull request. - Use a dedicated review-app environment, organization, namespace, or account that contains only disposable resources. - Do not mount production, staging, package-registry, cloud-provider, or deployment-admin secrets into review apps. - Run Rails and JavaScript in production-like mode: `RAILS_ENV=production` and `NODE_ENV=production`. - Delete review apps when pull requests close, and run scheduled cleanup for stale apps. GitHub does not pass repository secrets to ordinary `pull_request` workflows from forks, except for `GITHUB_TOKEN`. That default protects secrets from untrusted fork code. A maintainer-triggered deployment workflow can reintroduce risk if it checks out and builds the pull request with deployment credentials available. GitHub's [secure use reference](https://docs.github.com/en/actions/reference/security/secure-use) warns against combining privileged workflow triggers with untrusted code checkout. Heroku uses the same conservative boundary for public repositories: Review apps run pull request code in disposable apps, and Heroku does not automatically create review apps for public-repository pull requests sent from forks for security and billing reasons. See Heroku's [Review Apps documentation](https://devcenter.heroku.com/articles/github-integration-review-apps). ## Secrets and Runtime Environment Assume that any environment variable available to a deployed review app can be read by the pull request code. Secret storage protects values at rest and in configuration, but it does not protect a secret after the value is injected into a container that runs untrusted code. For review apps, prefer: - generated dummy `SECRET_KEY_BASE` values; - disposable databases, Redis instances, queues, and object stores; - review-only deployment credentials scoped to the smallest possible environment; - no npm, RubyGems, SSH, license, Sentry, Honeybadger, payment, email, or production API tokens. If a review app must use a sensitive credential, treat the deployment as a maintainer-approved trusted operation, rotate the credential after suspected exposure, and never reuse production credentials. ## Dummy App Notes The React on Rails dummy app contains test and development tooling that is not intended for public hosting. In particular, test helpers and browser-test middleware may be able to execute server-side code when enabled. Public review apps must therefore run with `RAILS_ENV=production` and should not expose development-only or test-only endpoints. For fork pull requests, the safest operational model is: 1. Run normal CI with no repository secrets. 2. Let a maintainer review the change. 3. Deploy only with a review-app credential that cannot access staging or production secrets. 4. Destroy the review app after review. ================================================================================ PAGE: https://reactonrails.com/docs/deployment/security-model-and-hardening SOURCE: docs/oss/deployment/security-model-and-hardening.md ================================================================================ # Security Model and Hardening > [!NOTE] > **Summary for AI agents:** This page documents the React on Rails security model: how component props are escaped into HTML, the trust boundary and hardening options for the Pro Node renderer, and the React Server Components (RSC) advisory posture. For review-app-specific guidance, see [Review App Security](./review-app-security.md). To report a vulnerability, see [SECURITY.md](https://github.com/shakacode/react_on_rails/blob/main/SECURITY.md). This guide is written for security reviewers. Every claim is tied to specific code in the [shakacode/react_on_rails](https://github.com/shakacode/react_on_rails) repository so you can verify it yourself; where a guarantee does **not** exist, that is stated explicitly. Scope: - [Props escaping contract](#props-escaping-contract) — applies to all React on Rails apps (OSS and Pro). - [Node renderer threat model](#node-renderer-threat-model-pro) — applies to React on Rails Pro apps using the standalone Node renderer. - [React Server Components advisory posture](#react-server-components-advisory-posture-pro) — applies to Pro apps using RSC. - [Reporting vulnerabilities](#reporting-vulnerabilities). Out of scope here: the general security of your own React components and Rails app (authentication, authorization, CSRF, etc. remain standard Rails concerns — React on Rails does not add a separate authentication or authorization layer in front of your Rails app). ## Props escaping contract ### How props reach the page `react_component` and `redux_store` embed your props as JSON inside `<script type="application/json">` data tags — not as executable JavaScript: - Component props: `generate_component_script` in `react_on_rails/lib/react_on_rails/pro_helper.rb` (part of the OSS gem despite the file name) builds `content_tag(:script, json_safe_and_pretty(render_options.client_props).html_safe, type: "application/json", ...)`. - Store props: `generate_store_script` in the same file does the same for Redux store hydration data. - Rails context: `rails_context_if_not_already_rendered` in `react_on_rails/lib/react_on_rails/helper.rb` embeds the rails context the same way. The client-side package reads these tags back with `JSON.parse` and passes the result to your components. ### What is escaped, and by what All three paths above escape the JSON through one function: `ReactOnRails::JsonOutput.escape`, which delegates to Rails' `ERB::Util.json_escape` (`react_on_rails/lib/react_on_rails/json_output.rb`, line 8). `ERB::Util.json_escape` replaces the HTML-significant characters `<`, `>`, and `&` with their Unicode escape sequences (`\u003c`, `\u003e`, `\u0026`) and escapes the U+2028/U+2029 line separators. Because no literal `<` can survive, a props value containing `</script><script>alert('xss')</script>` cannot terminate the surrounding `<script>` tag — it is emitted as `\u003c/script\u003e\u003cscript\u003ealert('xss')\u003c/script\u003e`, which `JSON.parse` later restores to the original string for your component as plain data. The helper entry points that apply this escaping: - `sanitized_props_string` (`react_on_rails/lib/react_on_rails/helper.rb`) — escapes props whether passed as a `Hash` (serialized via `to_json` first) or as a pre-serialized JSON `String`. - `json_safe_and_pretty` (`react_on_rails/lib/react_on_rails/helper.rb`) — same contract, used by the script-tag generators above. ### Test coverage This contract is covered by specs in the repository: - `react_on_rails/spec/react_on_rails/json_output_spec.rb` — unit specs for `JsonOutput.escape`, including an explicit `</script><script>...` payload. - `react_on_rails/spec/dummy/spec/helpers/react_on_rails_helper_spec.rb` (`#sanitized_props_string` examples) — asserts that a props hash containing `</script><script>alert('foo')</script>` is escaped in the rendered output, for both hash and string-typed props. ### What this does and does not guarantee **Guaranteed (by the code above):** - Props values cannot break out of the JSON `<script type="application/json">` data tags, because `<`, `>`, and `&` never appear literally in the emitted JSON. - Props are delivered to React as data. React's normal JSX text rendering then escapes them again on output, as in any React app. **Not guaranteed — your responsibility:** - **What your components do with props.** If a component passes a props value to `dangerouslySetInnerHTML`, interpolates it into a URL (`javascript:` schemes), or otherwise treats it as markup, the embedding-layer escaping above does not protect you. Escaping happens at the HTML-embedding boundary, not inside your component tree. - **Pre-serialized string props are trusted as JSON.** If you pass props as a `String` instead of a `Hash`, React on Rails HTML-escapes it for the client-side script tag but does **not** validate that it is well-formed JSON. On the server-rendering path, the string is interpolated directly into the JavaScript evaluated by the SSR runtime (`var props = #{props_string};` in `react_on_rails/lib/react_on_rails/server_rendering_js_code.rb`; see also the comment above the `js_code` construction in `server_rendered_react_component` in `react_on_rails/lib/react_on_rails/helper.rb`, which only escapes U+2028/U+2029 there). A string built by concatenating untrusted input is therefore JavaScript injection into your own SSR context. **Build props from Ruby data structures (`Hash`); never concatenate user input into a JSON string yourself.** - **Server-rendered HTML is inserted as-is.** The HTML your server-rendered components produce is marked `html_safe` and inserted without further sanitization — the output of your own bundle is trusted by design. The escaping contract covers props going _in_, not component HTML coming _out_. ## Node renderer threat model (Pro) This section applies to React on Rails Pro deployments using the standalone Node renderer (`react-on-rails-pro-node-renderer`). If you use ExecJS-based SSR (the OSS default), there is no separate renderer process or network hop, and this section does not apply. ### Trust model: the renderer executes your app's code The Node renderer is a service that accepts JavaScript bundles uploaded by your Rails app and executes them to render components. This is its purpose, not a flaw — but it has a direct consequence: > **Anyone who can reach the renderer's port and authenticate can execute arbitrary JavaScript with the > renderer process's privileges** (by uploading a bundle, or by sending a rendering request that the > bundle evaluates). The renderer is **not** a sandbox for untrusted code and must be treated as an > internal service with the same trust level as your Rails app servers. Concretely, the worker exposes these HTTP endpoints (`packages/react-on-rails-pro-node-renderer/src/worker.ts`): | Endpoint | Auth | Purpose | | ------------------------------------------------------------------------ | -------------------------------------------------------- | ----------------------------------------------------------- | | `POST /bundles/:bundleTimestamp/render/:renderRequestDigest` | password (via `performRequestPrechecks`) | Evaluate a rendering request; may also carry bundle uploads | | `POST /bundles/:bundleTimestamp/incremental-render/:renderRequestDigest` | password (via `performRequestPrechecks`) | Streaming/incremental rendering | | `POST /upload-assets` | password (via `performRequestPrechecks`) | Upload server bundles and assets | | `POST /asset-exists` | password (via `authenticate`, no protocol-version check) | Check whether an uploaded asset exists | | `GET /info` | **none** | Returns `node_version` and `renderer_version` | Note for reviewers: unlike the other authenticated endpoints, `/asset-exists` calls `authenticate` directly rather than through `performRequestPrechecks`, so it skips the protocol-version check — a compatibility control, not a security control. Known limitation: `GET /info` is unauthenticated and discloses the Node and renderer versions (`worker.ts`, the `app.get('/info', ...)` route). This is harmless on a private network but is version disclosure if you expose the port publicly — one more reason never to do so. ### Network exposure - The renderer binds to `localhost` by default (`host: env.RENDERER_HOST || 'localhost'` in `packages/react-on-rails-pro-node-renderer/src/shared/configBuilder.ts`). Setting `RENDERER_HOST=0.0.0.0` is needed for containerized deployments; if you do, network access control must come from your infrastructure (security groups, network policies, private VPC subnets). - The renderer listens for **cleartext HTTP/2 (h2c)** and does not terminate TLS itself (see the server construction in `run()` in `worker.ts`). The shared password travels in the request body. Treat the Rails-to-renderer link as plaintext: keep it on a private network, or place TLS-terminating infrastructure in front of the renderer and use an `https://` value for `config.renderer_url` on the Rails side. - **Never expose the renderer port to the public internet.** There is no rate limiting, no TLS, and the authenticated surface is "execute JavaScript". ### Authentication between Rails and the renderer Authentication is a single shared secret: - The renderer checks the password from the request body (`authenticate` in `packages/react-on-rails-pro-node-renderer/src/worker/authHandler.ts`). A submitted password whose byte length differs from the configured secret is rejected with `401` _before_ any comparison; only same-length candidates are then compared with `crypto.timingSafeEqual`. The comparison is therefore timing-safe for same-length guesses, but the early length check means the secret's length is not protected — use a long random secret, not a short passphrase. Comparison errors are also rejected with `401`. - **Production-like environments fail closed on both sides.** If neither `RAILS_ENV` nor `NODE_ENV` is a development/test value, the renderer refuses to start without a password (`validatePasswordForProduction` in `configBuilder.ts`), and the Rails side raises at configuration time (`validate_renderer_password_for_production` in `react_on_rails_pro/lib/react_on_rails_pro/configuration.rb`). When both environments are unset, the code treats the environment as production-like and still requires a password. - Both sides warn at startup if the password matches a known-default value or is shorter than 16 characters (`KNOWN_WEAK_PASSWORDS` / `MIN_PASSWORD_LENGTH` in `configBuilder.ts`; `warn_if_renderer_password_weak` in the Pro gem's `configuration.rb`). In these audited paths the literal password value is not logged: the weak-password warnings report only length/known-default status, and the renderer masks the password in its config diagnostics. Other logging or error-reporting paths in your app (e.g. exception trackers capturing config objects) are outside this guarantee — audit them yourself. - Rails resolves the password in this order: `config.renderer_password`, then a password embedded in `config.renderer_url` (`https://:password@host:3800`), then `ENV["RENDERER_PASSWORD"]` (documented in the error message in `configuration.rb`). Known limitations of this model (by design — plan your network accordingly): - One shared secret, not per-client credentials; there is no second factor and no built-in rotation mechanism. Rotate by deploying a new `RENDERER_PASSWORD` to both sides. - In `development`/`test` environments the password is optional, and with no password set the renderer accepts unauthenticated requests (`authenticate` returns success when no password is configured). Do not run a password-less renderer outside an isolated development machine. - Authentication grants access to all endpoints equally; there is no per-endpoint authorization. ### Code execution and the VM context The renderer evaluates bundles inside a Node `vm` context. Two configuration options control how much of the host the bundle can reach, and their security semantics are documented in the config source (`packages/react-on-rails-pro-node-renderer/src/shared/configBuilder.ts`, `Config` interface): - `supportModules: true` injects a default set of Node globals **and wraps the bundle so it receives the host `require`**, granting access to Node built-ins such as `fs` and `child_process`. This is required for loadable-components and most real-world SSR bundles. - `additionalContext`: any plain-object value (even `{}`) also switches the bundle into CommonJS mode with the host's unrestricted `require`. - The most restricted mode is `supportModules: false` **and** `additionalContext: null`. Even in the most restricted mode, do not treat the `vm` context as a security boundary: Node's `vm` module is explicitly [not a security mechanism](https://nodejs.org/api/vm.html) and the renderer makes no sandboxing claim beyond it. The security boundary is **who can reach the port and authenticate**, plus the OS-level privileges of the renderer process. ### Hardening checklist Every item below maps to a configuration option or behavior verified in this repository: 1. **Set a strong `RENDERER_PASSWORD`** (random, ≥ 16 characters) on both Rails and the renderer. Production-like environments refuse to start without one; the length/known-default checks only warn. 2. **Keep the renderer on a private network.** Default bind is `localhost`; if you set `RENDERER_HOST=0.0.0.0` for containers, restrict ingress to your Rails app servers and your health checker. 3. **Treat the link as plaintext.** The renderer speaks cleartext h2c; use a private network or external TLS termination, and prefer an `https://` `config.renderer_url` when a TLS hop exists. 4. **Run the renderer as an unprivileged OS user / minimal container, with resource limits.** The bundle typically runs with host `require` (see above), so the renderer process's OS privileges and resource ceiling are the effective blast radius. Set `--max-old-space-size` on the Node process and enforce container `memory` + `cpu` limits to bound the impact of a rogue or compromised bundle. 5. **Don't expose `GET /info`** beyond your monitoring network; it is unauthenticated version disclosure. 6. **Rotate the shared secret on a schedule** by redeploying both sides with a new value; there is no built-in rotation. 7. **Keep `NODE_ENV`/`RAILS_ENV` set correctly.** The fail-closed password requirement keys off these; an unset environment is treated as production-like (strict), but a mistakenly set `development` value disables the requirement. ## React Server Components advisory posture (Pro) RSC support in React on Rails Pro is built directly on React's Flight packages: the `react-on-rails-rsc` package wraps React's `react-server-dom-webpack`. Vulnerabilities in those upstream packages therefore apply to this stack, and the project's response is enforced in code: - **December 2025 React RSC advisories.** The React team published critical advisories affecting React Server Components, including a remote code execution issue ([CVE-2025-55182](https://react.dev/blog/2025/12/03/critical-security-vulnerability-in-react-server-components)) and follow-on [denial-of-service and source-code exposure fixes](https://react.dev/blog/2025/12/11/denial-of-service-and-source-code-exposure-in-react-server-components). React on Rails Pro shipped corresponding dependency floors; see the `CHANGELOG.md` security entries for CVE-2025-55182 ([PR 2175](https://github.com/shakacode/react_on_rails/pull/2175)) and CVE-2025-55183/55184/67779 ([PR 2233](https://github.com/shakacode/react_on_rails/pull/2233)). - **The patched-version requirement is checked, not just documented.** For RSC, the supported React range is `19.0.x` with patch `>= 19.0.4` (`~19.0.4`) — not an open-ended `>= 19.0.4` floor; newer minors such as 19.1.x are flagged as unverified by the doctor and rejected by the renderer's startup check: - `rake react_on_rails:doctor` warns when the installed React is 19.0.x below 19.0.4, citing the known security vulnerabilities (`check_rsc_react_version` in `react_on_rails/lib/react_on_rails/doctor.rb`). - The RSC generator emits the same warning at setup time, naming CVE-2025-55182, CVE-2025-67779, and CVE-2026-23864 (`react_on_rails/lib/generators/react_on_rails/rsc_setup.rb`). - The Node renderer runs an RSC peer-compatibility check at startup (`runRscPeerCompatibilityCheck`, called from the renderer's master, worker, and wrapper entry points in `packages/react-on-rails-pro-node-renderer/src/`). Incompatible `react`, `react-dom`, or `react-on-rails-rsc` versions **fail startup**; an older-but-compatible `react-on-rails-rsc` only logs a warning. Setting `REACT_ON_RAILS_PRO_DISABLE_VERSION_CHECK=1` downgrades the hard startup failure to a warning — **do not set this in production: it allows the renderer to boot on React versions with known critical vulnerabilities (CVE-2025-55182 and related).** ### How to verify your own status ```bash # Reports your React/RSC versions and flags the security floor: bundle exec rake react_on_rails:doctor ``` Also subscribe to [React's blog](https://react.dev/blog) for upstream advisories, and watch this repository's `CHANGELOG.md` security entries for the corresponding React on Rails releases. ## Reporting vulnerabilities The supported-version policy, triage commitments, and private reporting process live in [SECURITY.md](https://github.com/shakacode/react_on_rails/blob/main/SECURITY.md) at the repository root. Formalizing the public advisory process (security contact alias, GitHub Security Advisories policy) is tracked in [issue #3266](https://github.com/shakacode/react_on_rails/issues/3266). ## Related documentation - [Review App Security](./review-app-security.md) — running untrusted PR code in review apps - [Node Renderer Basics](../building-features/node-renderer/basics.md) — renderer architecture - [Node Renderer JS Configuration](../building-features/node-renderer/js-configuration.md) — all renderer configuration options, including the `supportModules` / `additionalContext` runtime-globals notes - [Docker Deployment](./docker-deployment.md) — containerized deployment patterns ================================================================================ PAGE: https://reactonrails.com/docs/deployment/server-rendering-tips SOURCE: docs/oss/deployment/server-rendering-tips.md ================================================================================ # Server Rendering Tips :::tip Pro Upgrade For the best SSR performance, React on Rails Pro provides a [dedicated Node.js renderer](../../pro/node-renderer.md) (10-100x faster than ExecJS), [streaming SSR](../../pro/streaming-ssr.md) for faster TTFB, and [fragment caching](../../pro/fragment-caching.md) to skip redundant rendering entirely. [Learn more →](../../pro/upgrading-to-pro.md) ::: ## General Tips - **Module-level state persists across requests in the Node Renderer.** Any `Map`, `Set`, object cache, or `_.memoize` call at module scope will accumulate entries across all SSR requests and never be cleared. This is the most common cause of OOM in Node Renderer production deployments. See the [Memory Leaks guide](../../pro/js-memory-leaks.md) for patterns to avoid. - **Set `NODE_OPTIONS=--max-old-space-size=<MB>` in production.** Without this, V8 defers garbage collection in containers, amplifying any memory leaks. Size it based on your container memory divided by worker count. - Your code can't reference `document`. Server-side JS execution does not have access to `document`, so jQuery and some other libraries won't work in this environment. You can debug this by putting in `console.log` statements in your code. - You can conditionally avoid running code that references document by either checking if `window` is defined or using the "railsContext" in your top-level React component. Since the Hash passed in `props` from the view helper applies to both client- and server-side code, the best way to do this is to use a Render-Function. - If you're serious about server-side rendering, it's worth the effort to have different entry points for client-side and server-side rendering. It's worth the extra complexity. The point is that you have separate files for top-level client and server side, and you pass some extra option indicating that rendering is happening server-side. - You can enable Node.js server rendering via [React on Rails Pro](../../pro/react-on-rails-pro.md). ## Troubleshooting Server Rendering 1. First make sure your code works with server rendering disabled (`prerender: false`). 2. Set `config.trace` to true. You will get the server invocation code that renders your component. If you're not using Shakapacker, you will also get the whole file used to set up the JavaScript context. 3. If streaming SSR requests hang indefinitely, check whether your compression middleware (`Rack::Deflater`, `Rack::Brotli`) has an `:if` condition that calls `body.each`. This causes deadlocks with streaming responses. See the [Compression for Streamed RSC Responses](../../pro/streaming-ssr.md#compression-middleware-compatibility) section in the Streaming SSR guide. ## CSS Server bundles must always have CSS extracted. ## setTimeout, setInterval, and clearTimeout These methods are polyfilled for server rendering to be no-ops. We log calls to these when in `trace` mode. In the past, some libraries, namely babel-polyfill, did call `setTimeout`. Here's an example of this, showing the line numbers that end up calling `setTimeout`: ```text ➜ ~/shakacode/react_on_rails/gen-examples/examples/basic-server-rendering (add-rails-helper-to-generator u=) ✗ export SERVER_TRACE_REACT_ON_RAILS=TRUE ➜ ~/shakacode/react_on_rails/gen-examples/examples/basic-server-rendering (add-rails-helper-to-generator u=) ✗ rspec Hello World Building Webpack client-rendering assets... Completed building Webpack client-rendering assets. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ react_renderer.rb: 92 wrote file tmp/server-generated.js ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ react_renderer.rb: 92 wrote file tmp/base_js_code.js ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ [SERVER] setTimeout is not defined for execJS. See https://github.com/sstephenson/execjs#faq. Note babel-polyfill will call this. [SERVER] at setTimeout (<eval>:31:17) at defer (<eval>:4422:8) at setImmediate (<eval>:4387:6) at notify (<eval>:4481:16) at module.exports (<eval>:4490:6) at notify (<eval>:4081:4) at Promise.$resolve (<eval>:4189:8) at <eval>:793:18 at Function.resolve (<eval>:4265:6) the hello world example works ``` ================================================================================ PAGE: https://reactonrails.com/docs/deployment/troubleshooting SOURCE: docs/oss/deployment/troubleshooting.md ================================================================================ # Troubleshooting Guide Having issues with React on Rails? This guide covers the most common problems and their solutions. > [!NOTE] > **Summary for AI agents:** Use this page for general React on Rails troubleshooting. For quick fixes to common setup issues, see [Common Issues](../getting-started/common-issues.md). For Pro-specific issues (streaming SSR, Node renderer, RSC), see [Pro Troubleshooting](../../pro/troubleshooting.md). Always try `bundle exec rails react_on_rails:doctor` first. ## 🔍 Quick Diagnosis ### Is your issue with...? | Problem Area | Quick Check | Go to Section | | -------------------- | ------------------------------------------- | ------------------------------------------------------------ | | **Installation** | Generator fails or components don't appear | [Installation Issues](#-installation-issues) | | **Compilation** | Webpack errors, build failures | [Build Issues](#-build-issues) | | **Runtime** | Components not rendering, JavaScript errors | [Runtime Issues](#-runtime-issues) | | **CSS Modules** | Styles undefined, SSR CSS crashes | [CSS Modules Issues](#-css-modules-issues) | | **Styling (FOUC)** | Unstyled content flash, layout jumps | [Flash of Unstyled Content](#flash-of-unstyled-content-fouc) | | **Server Rendering** | SSR not working, hydration mismatches | [SSR Issues](#-server-side-rendering-issues) | | **Performance** | Slow builds, large bundles, memory issues | [Performance Issues](#-performance-issues) | ## 🚨 Installation Issues ### "Generator fails with uncommitted changes" **Error:** `You have uncommitted changes. Please commit or stash them.` **Solution:** ```bash git add . git commit -m "Add react_on_rails gem" bin/rails generate react_on_rails:install ``` **Why:** The generator needs clean git state to show you exactly what it changed. ### "Node or package manager not found" **Error:** `Node.js not found`, `npm executable was not detected`, or `Yarn executable was not detected` **Solution:** - Install Node.js 18+ from [nodejs.org](https://nodejs.org) - Use the bundled `npm`, or install another package manager such as `pnpm`, `yarn`, or `bun` - On macOS, for example: `brew install node pnpm` ## 🔧 Build Issues ### "Module not found: Can't resolve 'react-on-rails'" **Error in browser console or webpack output** **Solution:** ```bash # Make sure the npm package is installed pnpm add react-on-rails # or: npm install react-on-rails --save # or: yarn add react-on-rails # If using local development with yalc cd react_on_rails/ yalc publish cd your_app/ yalc add react-on-rails ``` ### "Webpack compilation failed" **Check these common causes:** 1. **Syntax errors** in your React components 2. **Missing dependencies** in package.json 3. **Incorrect imports** (check file paths and extensions) **Debug steps:** ```bash # Run webpack directly to see detailed errors bin/webpack # Or in development mode bin/webpack --mode development ``` ### "ExecJS::RuntimeUnavailable" **Error:** JavaScript runtime not available **Solution:** ```bash # Add to your Gemfile gem 'execjs' gem 'mini_racer', platforms: :ruby # Or use Node.js runtime export EXECJS_RUNTIME=Node ``` ## ⚡ Runtime Issues ### "Component not rendering" **Symptoms:** Empty div or no output where component should be **Check list:** 1. **Component registered?** ```javascript import ReactOnRails from 'react-on-rails'; import MyComponent from './MyComponent'; ReactOnRails.register({ MyComponent }); ``` 2. **Bundle included in view?** ```erb <%= javascript_pack_tag 'my-bundle' %> <%= react_component('MyComponent') %> ``` 3. **Component exported correctly?** ```javascript // Use default export export default MyComponent; // Not named export for registration ``` ### "ReferenceError: window is not defined" **Error during server-side rendering** **Solution:** Check your component for browser-only code: ```javascript // ❌ Bad - will break SSR const width = window.innerWidth; // ✅ Good - check if window exists const width = typeof window !== 'undefined' ? window.innerWidth : 1200; // ✅ Better - use useEffect hook useEffect(() => { const width = window.innerWidth; // Use width here }, []); ``` ### "Props not updating" **Symptoms:** Component shows initial props but doesn't update **Common causes:** 1. **Caching** - Rails fragment caching may cache React components 2. **Turbo/Turbolinks** - Page navigation isn't re-initializing React 3. **Development mode** - Hot reloading not working **Solutions:** ```erb <!-- Disable caching for development --> <% unless Rails.env.development? %> <% cache do %> <%= react_component('MyComponent', props: @props) %> <% end %> <% else %> <%= react_component('MyComponent', props: @props) %> <% end %> ``` ### "Flash of Unstyled Content (FOUC)" There are two common causes of FOUC in React on Rails applications: #### Type 1: SSR with `auto_load_bundle` **Symptoms:** Page briefly shows unstyled content before CSS loads, particularly with SSR and `auto_load_bundle` **Root Cause:** When using `auto_load_bundle = true` with server-side rendering, `react_component` calls trigger `append_stylesheet_pack_tag` during body rendering, but these appends must execute BEFORE the `stylesheet_pack_tag` in the `<head>`. **Solution:** Use the `content_for :body_content` pattern to ensure appends happen before the head renders. **See:** [FOUC Prevention Guide](../core-concepts/auto-bundling-file-system-based-automated-bundle-generation.md#2-css-not-loading-fouc---flash-of-unstyled-content) for detailed solutions and examples. **Quick fix:** ```erb <% content_for :body_content do %> <%= react_component "MyComponent", prerender: true %> <% end %> <!DOCTYPE html> <html> <head> <%= stylesheet_pack_tag(media: 'all') %> </head> <body> <%= yield :body_content %> </body> </html> ``` #### Type 2: Tailwind/Utility-First CSS Frameworks **Symptoms:** Layout appears broken or jumps on initial page load—sidebars collapse, flex containers stack vertically, backgrounds are white instead of colored. **Root Cause:** When using Tailwind CSS (or similar utility-first frameworks), your layout HTML contains CSS classes like `flex`, `h-screen`, `bg-slate-100` that have no effect until the CSS bundle loads. The browser renders the raw HTML structure without any styling. **Example of problematic layout:** ```erb <!-- These classes do nothing until Tailwind CSS loads --> <div class="flex flex-row h-screen w-screen"> <div class="flex flex-col bg-slate-100 min-w-[400px]"> <!-- sidebar --> </div> <div class="flex-1 overflow-y-auto"> <!-- main content --> </div> </div> ``` **Solution:** Inline critical CSS for layout-affecting properties in the `<head>` before your main stylesheet loads. Use stable semantic selectors (not Tailwind utility class names) so the critical CSS doesn't drift when you add or remove utility classes. **Step 1:** Add semantic classes to your layout's structural elements (alongside existing Tailwind classes): ```erb <body class="app-body bg-white"> <div class="app-shell flex flex-row h-screen w-screen"> <div class="app-sidebar flex flex-col overflow-y-auto p-5 bg-slate-100 ..."> <!-- sidebar content --> </div> <div class="app-main flex-1 overflow-x-hidden overflow-y-auto"> <div class="app-main-content p-5"> <!-- main content --> </div> </div> </div> ``` **Step 2:** Create a critical styles partial (e.g., `app/views/layouts/_critical_styles.html.erb`) targeting those semantic selectors: ```erb <%# Critical CSS for preventing FOUC. Uses semantic selectors so it doesn't need to change when Tailwind utility classes are added or removed. Only update when the fundamental layout structure changes. %> <style data-critical-styles> .app-body { background-color: #fff; } .app-shell { display: flex; flex-direction: row; height: 100vh; width: 100vw; } .app-sidebar { display: flex; flex-direction: column; overflow-y: auto; padding: 1.25rem; background-color: #f1f5f9; border-style: solid; border-right-width: 2px; border-color: #334155; min-width: 400px; max-width: 400px; } .app-main { flex: 1 1 0%; overflow-x: hidden; overflow-y: auto; } .app-main-content { padding: 1.25rem; } </style> ``` **Step 3:** Include it in your layout's `<head>` before the stylesheet: ```erb <head> <%= render "layouts/critical_styles" %> <%= stylesheet_pack_tag('application', media: 'all') %> </head> ``` **Guidelines for critical CSS:** - **Use semantic selectors** - `.app-shell`, `.app-sidebar`, etc. instead of mirroring Tailwind class names - **Keep it minimal** - Only define the layout shell (not component styles) - **Focus on layout-affecting properties** - `display`, `flex`, `width`, `height`, `position` - **Include visible defaults** - Background colors and borders that prevent jarring changes - **Add `data-critical-styles`** - Makes it easy to test that critical styles appear before the bundle ## 🎨 CSS Modules Issues ### "CSS modules returning undefined" (Shakapacker 9+) **Symptoms:** - `import css from './Component.module.scss'` returns `undefined` - SSR crashes: `Cannot read properties of undefined (reading 'className')` - Build warning: `export 'default' (imported as 'css') was not found` **Root Cause:** Shakapacker 9 changed the default CSS Modules configuration from default exports to named exports (`namedExport: true`). **Solution:** Configure CSS loader to use default exports: ```javascript // config/webpack/commonWebpackConfig.js const { generateWebpackConfig } = require('shakapacker'); const commonWebpackConfig = () => { const baseWebpackConfig = generateWebpackConfig(); baseWebpackConfig.module.rules.forEach((rule) => { if (rule.use && Array.isArray(rule.use)) { const cssLoader = rule.use.find((loader) => { const loaderName = typeof loader === 'string' ? loader : loader?.loader; return loaderName?.includes('css-loader'); }); if (cssLoader?.options?.modules) { cssLoader.options.modules.namedExport = false; cssLoader.options.modules.exportLocalsConvention = 'camelCase'; } } }); return baseWebpackConfig; }; ``` **See:** [Rspack Migration Guide](../migrating/migrating-from-webpack-to-rspack.md) for complete configuration details. ### "CSS modules work in dev but fail in SSR" **Cause:** Server-side config overwrites CSS modules settings instead of merging them. **Solution:** Preserve existing CSS modules configuration: ```javascript // ❌ Wrong cssLoader.options.modules = { exportOnlyLocals: true }; // ✅ Correct cssLoader.options.modules = { ...cssLoader.options.modules, exportOnlyLocals: true, }; ``` ### "Intermittent CSS failures with Rspack" **Cause:** CSS extraction not properly filtered from server bundle. Rspack uses different loader paths than Webpack. **Solution:** Filter both Webpack and Rspack CSS extract loaders: ```javascript rule.use = rule.use.filter((item) => { const testValue = typeof item === 'string' ? item : item?.loader; return !( testValue?.match(/mini-css-extract-plugin/) || testValue?.includes('cssExtractLoader') || // Rspack path testValue === 'style-loader' ); }); ``` ## 🖥️ Server-Side Rendering Issues ### "Server rendering not working" **Check:** 1. **Prerender enabled?** ```erb <%= react_component('MyComponent', props: @props, prerender: true) %> ``` 2. **JavaScript runtime available?** ```bash # Add to Gemfile if missing gem 'mini_racer' ``` 3. **No browser-only code in component?** (see "window is not defined" above) ### "Hydration mismatch warnings" **Symptoms:** React warnings about server/client content differences **Common causes:** - Different props between server and client render - Browser-only code affecting initial render - Date/time differences between server and client **Debug:** ```javascript // Add this to see what props are being used console.log('Server props:', props); console.log('Client render time:', new Date()); ``` ## 🐌 Performance Issues ### "Slow webpack builds" **Solutions:** 1. **Enable caching:** ```yaml # config/shakapacker.yml development: cache_manifest: true ``` 2. **Use webpack-dev-server:** ```bash ./bin/dev # Uses Procfile.dev with webpack-dev-server ``` 3. **Check for large dependencies:** ```bash yarn why package-name webpack-bundle-analyzer public/packs/manifest.json ``` ### "Large bundle sizes" **Solutions:** 1. **Code splitting:** ```javascript // Use dynamic imports const MyComponent = lazy(() => import('./MyComponent')); ``` 2. **Check bundle analysis:** ```bash ANALYZE=true bin/webpack ``` 3. **Remove unused dependencies:** ```bash yarn remove unused-package ``` ## 🛠️ Advanced Debugging For a comprehensive debugging guide covering SSR issues, hydration mismatches, and log analysis, see the [Debugging Guide](../building-features/debugging.md). ### Enable verbose logging ```ruby # config/initializers/react_on_rails.rb ReactOnRails.configure do |config| config.logging_on_server = true end ``` The open-source gem always renders on the server with ExecJS; there is no configuration option to select a different server render method. For a standalone Node rendering process, use [React on Rails Pro](https://www.shakacode.com/react-on-rails-pro/)'s Node renderer, which is configured via `ReactOnRailsPro.configure` rather than through the open-source configuration. ### Debug webpack configuration ```bash # See the final webpack config bin/webpack --config-dump ``` ### Check component registration ```javascript // In browser console console.log(ReactOnRails.registeredComponents()); ``` ## 🆘 Still Stuck? ### Before asking for help, gather this info - React on Rails version (`bundle list react_on_rails`) - Rails version (`rails -v`) - Ruby version (`ruby -v`) - Node version (`node -v`) - Error messages (full stack trace) - Relevant code snippets ### Get community help - **[GitHub Issues](https://github.com/shakacode/react_on_rails/issues)** - Bug reports and feature requests - **[GitHub Discussions](https://github.com/shakacode/react_on_rails/discussions)** - Questions and help - **[React + Rails Slack](https://reactrails.slack.com)** - Real-time community support ### Professional support - **[ShakaCode](https://www.shakacode.com)** offers consulting and support services - **[React on Rails Pro](../../pro/react-on-rails-pro.md)** includes priority support --- **💡 Tip:** Most issues are solved by ensuring your setup matches the [Quick Start Guide](../getting-started/quick-start.md) exactly. ================================================================================ PAGE: https://reactonrails.com/docs/deployment/troubleshooting-build-errors SOURCE: docs/oss/deployment/troubleshooting-build-errors.md ================================================================================ # Troubleshooting Build Errors This guide covers common webpack build errors encountered when using react_on_rails and how to resolve them. ## Table of Contents - [Missing Routes File Error](#missing-routes-file-error-js-routes-gem) - [ProvidePlugin Module Resolution Errors](#provideplugin-module-resolution-errors) - [Environment Setup Dependencies](#environment-setup-dependencies) - [Shakapacker Compatibility Issues](#shakapacker-compatibility-issues) - [Duplicate Build Execution (Versions < 16.2.0)](#duplicate-build-execution-versions--1620) - [For Coding Agents](#for-coding-agents) ## Missing Routes File Error (js-routes gem) **Note:** This error only occurs if you're using the optional `js-routes` gem to access Rails routes in JavaScript. ### Error Message ```text Cannot read properties of undefined (reading 'module') TypeError: Cannot read properties of undefined (reading 'module') at ProvidedDependencyTemplate.apply ``` ### Root Cause This error occurs when: 1. Your webpack config references Rails routes via ProvidePlugin 2. The `js-routes` gem hasn't generated the JavaScript routes file 3. You're using `js-routes` integration but missing the generated file ### When You Need js-routes `js-routes` is **optional** and typically used when: - Rails-heavy apps with React components that need to navigate to Rails routes - Server-side rendered apps mixing Rails and React routing - Legacy Rails apps migrating ERB views to React - Apps using Rails routing patterns for RESTful APIs ### When You DON'T Need js-routes Most modern React apps use: - Client-side routing (React Router) instead of Rails routes - Hardcoded API endpoints or environment variables - SPA (Single Page App) architecture with API-only Rails backend ### Solution (if using js-routes) 1. **Generate JavaScript routes file:** ```bash bundle exec rails js:export ``` 2. **Verify the routes file was created:** ```bash ls app/javascript/utils/routes.js ``` 3. **Check webpack configuration includes ProvidePlugin:** ```javascript new webpack.ProvidePlugin({ Routes: '$app/utils/routes', }); ``` ### Alternative Solution (if NOT using js-routes) Remove the Routes ProvidePlugin from your webpack configuration: ```javascript // Remove this line if you don't use js-routes new webpack.ProvidePlugin({ Routes: '$app/utils/routes', // ← Remove this }); ``` ## ProvidePlugin Module Resolution Errors ### Common Error Patterns - `Cannot read properties of undefined (reading 'module')` - `Module not found: Error: Can't resolve 'module_name'` - `ERROR in ./path/to/file.js: Cannot find name 'GlobalVariable'` ### Debugging Steps 1. **Check file existence:** ```bash find app/javascript -name "routes.*" -type f find app/javascript -name "*global*" -type f ``` 2. **Verify webpack aliases:** ```javascript // In your webpack config console.log('Webpack aliases:', config.resolve.alias); ``` 3. **Test module resolution:** ```bash # Run webpack with debug output bin/shakapacker --debug-shakapacker ``` 4. **Check for circular dependencies:** ```bash # Install circular dependency plugin npm install --save-dev circular-dependency-plugin ``` ### Common Fixes 1. **Missing global modules:** Ensure all modules referenced in ProvidePlugin exist 2. **Incorrect paths:** Verify alias paths are correct relative to project root 3. **File extensions:** Make sure webpack can resolve the file extension ## Environment Setup Dependencies ### Rails Environment Required Some operations require a working Rails environment: - `rails js:export` (generates routes - **only needed if using js-routes gem**) - Asset precompilation - Server-side rendering ### Common Issues 1. **Database Connection Errors:** ```text MONGODB | Error checking localhost:27017: Connection refused ``` **Solution:** These are usually warnings and don't prevent operation. To silence: ```bash # Run with minimal environment RAILS_ENV=development bundle exec rails js:export ``` 2. **Missing Dependencies:** ```text sidekiq-pro is not installed ``` **Solution:** This is typically a warning for optional gems and won't affect builds. ### Workarounds 1. **Skip database initialization:** ```bash DATABASE_URL=sqlite3:tmp/db.sqlite3 rails js:export ``` 2. **Use test environment:** ```bash RAILS_ENV=test rails js:export ``` ## Shakapacker Compatibility Issues ### Version Compatibility Matrix | react_on_rails | Shakapacker | Webpack | Node.js | | -------------- | ----------- | ------- | ------- | | v16.x | >= 6.0 | v5 | 20-22 | | v14.x | >= 6.0 | v5 | 18-20 | | v13.x | >= 6.0 | v5 | 16-18 | ### Common Upgrade Issues 1. **Webpacker to Shakapacker migration incomplete:** ```bash # Remove webpacker references grep -r "webpacker" config/ ``` 2. **Old webpack configuration:** ```bash # Check for deprecated webpack configs find config/webpack -name "*.js" -exec grep -l "webpacker" {} \; ``` ### Migration Steps 1. Follow the [Shakapacker upgrade guide](https://github.com/shakacode/shakapacker/blob/main/docs/v6_upgrade.md) 2. Update webpack configurations 3. Regenerate configurations with `rails generate react_on_rails:install` ## Duplicate Build Execution (Versions < 16.2.0) ### Symptom If you're using React on Rails **versions before 16.2.0**, you may notice: - Asset precompilation takes twice as long as expected - Webpack build runs twice during `rake assets:precompile` - Console output shows duplicate webpack compilation messages - CI builds are slower than necessary ### Root Cause In versions prior to 16.2.0, a bug in the Rails Engine caused rake task files to be loaded twice: 1. Once via explicit `load` calls in the Engine's `rake_tasks` block 2. Once via Rails Engine's automatic file loading from `lib/tasks/` This resulted in tasks like `react_on_rails:assets:webpack`, `react_on_rails:generate_packs`, and `react_on_rails:locale` executing twice. ### Solution **Upgrade to React on Rails 16.2.0 or later:** ```bash # Update Gemfile gem 'react_on_rails', '~> 16.2' # Install bundle update react_on_rails ``` The issue is fixed in version 16.2.0 ([PR #2052](https://github.com/shakacode/react_on_rails/pull/2052)). ### Workaround for Older Versions If you cannot upgrade immediately, you can temporarily work around this by creating an initializer: ```ruby # config/initializers/react_on_rails_fix.rb Rails.application.config.after_initialize do # Only apply if using affected versions next unless ReactOnRails::VERSION < '16.2.0' # Remove duplicate task actions %w[ react_on_rails:assets:webpack react_on_rails:generate_packs react_on_rails:locale ].each do |task_name| next unless Rake::Task.task_defined?(task_name) task = Rake::Task[task_name] task.actions.uniq! if task.actions.length > 1 end end ``` **Note:** This workaround is not recommended for production. Upgrade to 16.2.0+ for the proper fix. ## For Coding Agents ### Automated Diagnostics When encountering build errors, run this diagnostic script: ```bash #!/bin/bash echo "=== React on Rails Build Diagnostics ===" echo "1. Checking versions..." bundle show react_on_rails | grep "react_on_rails" npm list react-on-rails 2>/dev/null | grep "react-on-rails" echo "2. Checking required files..." [ -f "app/javascript/utils/routes.js" ] && echo "✓ Routes file exists" || echo "✗ Routes file missing - run 'rails js:export'" echo "3. Checking webpack config..." grep -q "ProvidePlugin" config/webpack/*.js && echo "✓ ProvidePlugin found" || echo "✗ ProvidePlugin not found" echo "4. Checking aliases..." grep -q "\$app" config/webpack/*.js && echo "✓ App alias found" || echo "✗ App alias missing" echo "5. Testing build..." npm run build 2>&1 | head -20 ``` ### Quick Fixes Checklist For agents encountering build errors: 1. ✅ **Generate routes:** `rails js:export` 2. ✅ **Check file existence:** Verify all ProvidePlugin modules exist 3. ✅ **Update dependencies:** `bundle update react_on_rails && npm install` 4. ✅ **Clear cache:** `rm -rf tmp/cache node_modules/.cache` 5. ✅ **Regenerate config:** `rails generate react_on_rails:install` (review before applying) ### Error Pattern Recognition Common error patterns for automated detection: ```regex # Missing routes file /Cannot read properties of undefined.*reading 'module'/ # ProvidePlugin issues /Error: Can't resolve.*\$app/ # Version compatibility /webpack.*incompatible/ # Missing dependencies /Module not found.*react-on-rails/ ``` ### Automated Solutions ```bash # Auto-fix missing routes if ! [ -f "app/javascript/utils/routes.js" ]; then echo "Generating missing routes file..." bundle exec rails js:export fi # Auto-fix dependency issues if grep -q "Cannot read properties" build.log; then echo "Updating dependencies..." bundle update react_on_rails npm install fi ``` --- ## Need More Help? - Check the [general troubleshooting guide](../deployment/troubleshooting-when-using-shakapacker.md) - Review [webpack configuration guide](../core-concepts/webpack-configuration.md) - Contact [justin@shakacode.com](mailto:justin@shakacode.com) for professional support ================================================================================ PAGE: https://reactonrails.com/docs/deployment/troubleshooting-when-using-shakapacker SOURCE: docs/oss/deployment/troubleshooting-when-using-shakapacker.md ================================================================================ # Troubleshooting Shakapacker Configuration Issues ## Client rendering crashes when configuring `optimization.runtimeChunk` to `multiple` ### Context 1. Ruby version: 3.1 2. Rails version: 7.0.6 3. Shakapacker version: 6.6.0 4. React on Rails version: 13.3.5 ### The failure Configuring Webpack to embed the runtime in each chunk and calling `react_component` twice in a Rails view/partial causes the client render to crash with the following error: ```text Could not find component registered with name XXX. Registered component names include [ YYY ]. Maybe you forgot to register the component? ``` ```text VM4859 clientStartup.js:132 Uncaught Error: ReactOnRails encountered an error while rendering component: XXX. See above error message. at Object.get (ComponentRegistry.js:40:15) at Object.getComponent (ReactOnRails.js:211:44) at render (VM4859 clientStartup.js:103:53) at forEachReactOnRailsComponentRender (VM4859 clientStartup.js:138:9) at reactOnRailsPageLoaded (VM4859 clientStartup.js:164:5) at renderInit (VM4859 clientStartup.js:205:9) at onPageReady (VM4859 clientStartup.js:234:9) at HTMLDocument.onReadyStateChange (VM4859 clientStartup.js:238:13) ``` ### Configs #### Webpack configuration ```js optimization: { runtimeChunk: 'multiple' }, ``` #### Rails view ```haml = react_component("XXX", props: @props) = yield = react_component("YYY", props: @props) ``` ### The problem Configuring Webpack to embed the runtime in each chunk and calling `react_component` twice in a Rails view/partial causes the client render to crash. Read more at https://github.com/shakacode/react_on_rails/issues/1558. ### Solution To overcome this issue, we could use [shakapacker](https://github.com/shakacode/shakapacker)'s default optimization configuration (pseudo-code): ```js const { webpackConfig: baseClientWebpackConfig } = require('shakapacker'); // ... config.optimization = baseClientWebpackConfig.optimization; ``` As it set the `optimization.runtimeChunk` to `single`. [See its source](https://github.com/shakacode/shakapacker/blob/cdf32835d3e0949952b8b4b53063807f714f9b24/package/environments/base.js#L115-L119): ```js optimization: { splitChunks: { chunks: 'all' }, runtimeChunk: 'single' }, ``` Or set `optimization.runtimeChunk` to `single` directly. ================================================================================ PAGE: https://reactonrails.com/docs/upgrading/upgrading-react-on-rails SOURCE: docs/oss/upgrading/upgrading-react-on-rails.md ================================================================================ # Upgrading React on Rails > [!NOTE] > **Summary for AI agents:** Use this page when the user is upgrading between React on Rails versions (e.g., v13 → v14). For upgrading from OSS to Pro, see [Upgrade to Pro](../../pro/upgrading-to-pro.md). For upgrading between **React on Rails Pro versions**, see [Upgrading React on Rails Pro](../../pro/updating.md) — Pro upgrades are coupled Ruby + JavaScript changes and need lockfile updates on both sides. For migrating from the `react-rails` gem, see [Migrating from react-rails](../migrating/migrating-from-react-rails.md). Check the [release notes](./release-notes/index.md) for version-specific breaking changes. ## Need Help Migrating? If you would like help in migrating between React on Rails versions or help with implementing server rendering, please contact [justin@shakacode.com](mailto:justin@shakacode.com) for more information about our [React on Rails Pro Support](../../pro/react-on-rails-pro.md). We specialize in helping companies to quickly and efficiently upgrade. The older versions use the Rails asset pipeline to package client assets. The current and recommended way is to use Webpack 4+ for asset preparation. You may also need help migrating from the `rails/webpacker`'s Webpack configuration to a better setup ready for Server Side Rendering. ## v15 Retraction Notice {#v15-retraction-notice} React on Rails v15.0.0 was retracted due to API design issues. When upgrading from v14 or earlier, skip v15 and upgrade directly to v16 or a later supported release. Historical v15 material remains available for maintaining older applications: [React on Rails 15.0.0 docs](https://github.com/shakacode/react_on_rails/tree/15.0.0/docs) and [React on Rails 15.0.0 code](https://github.com/shakacode/react_on_rails/tree/15.0.0). ## General Upgrade Process After upgrading to any major version, always run the generator to get the latest defaults: ```bash rails generate react_on_rails:install ``` **⚠️ Important**: Review generated changes carefully before applying to avoid overwriting custom configurations. The generator updates: - `bin/dev` (improved development workflow) - webpack configurations - `shakapacker.yml` settings - other configuration files ## Pro Users: Coupled Ruby + JavaScript Upgrade React on Rails Pro versions are a **coupled Ruby + JavaScript upgrade**: the gem (`react_on_rails_pro`), the npm packages (`react-on-rails-pro`, optionally `react-on-rails-pro-node-renderer` and `react-on-rails-rsc`), **and** both lockfiles (`Gemfile.lock` plus `yarn.lock` / `package-lock.json` / `pnpm-lock.yaml`) must move together. The gem and the npm package also use different prerelease formats (`16.7.0.rc.0` on RubyGems vs `16.7.0-rc.0` on npm). See [Upgrading React on Rails Pro → Coupled Pro Upgrade Checklist](../../pro/updating.md#coupled-pro-upgrade-checklist) for the full step-by-step. Following that checklist is required for Pro upgrades to avoid PRs that pass loose installs locally and then fail CI under frozen-lockfile install. ## Upgrade Preflight Before changing versions, check these first: 1. **Ruby and Node requirements**: React on Rails v17 requires Ruby 3.3+ and Node 18+. React on Rails v16 remains the upgrade path for apps that need older Ruby versions. 2. **Bundler age**: legacy apps may have lockfiles created by Bundler 1.x. Those lockfiles can fail on modern Ruby before the React on Rails upgrade even starts. 3. **Rails version**: current `react_on_rails` requires Rails 5.2+. Rails 5.1 apps need a Rails upgrade before they can bundle v17. 4. **Asset stack**: if the app still uses `webpacker`, upgrade to `shakapacker` first. 5. **Version pinning**: use exact gem and npm package versions for React on Rails-related packages. Avoid `^`, `~`, or `*`. If your app is both Ruby/Bundler-old and Webpacker-old, do those upgrades first. Trying to jump directly from a Rails 5 / Webpacker 3 / Bundler 1 stack to current React on Rails is usually more than one migration. If the first failure is a Bundler 1.x lockfile, refresh that lockfile with Bundler 2.x before changing React on Rails: ```bash gem install bundler # if Bundler 2.x is not already available bundle lock --update bundle install ``` ## Upgrading Precompile Hooks for SSR + HMR If your app uses server-side rendering with HMR, Shakapacker commonly runs two webpack processes during development (client HMR and server watcher). In that setup, direct-command precompile hooks are more fragile because each process can trigger the hook. Use a script-based hook with an explicit self-guard. This pattern is reliable across Shakapacker versions. ### Recommended setup 1. Create `bin/shakapacker-precompile-hook`: ```ruby #!/usr/bin/env ruby # frozen_string_literal: true exit 0 if ENV["SHAKAPACKER_SKIP_PRECOMPILE_HOOK"] == "true" system("bundle", "exec", "rake", "react_on_rails:locale", exception: true) ``` 2. Make it executable: ```bash chmod +x bin/shakapacker-precompile-hook ``` 3. Configure `config/shakapacker.yml`: ```yaml default: &default precompile_hook: 'bin/shakapacker-precompile-hook' ``` ### Version guidance - **Shakapacker 9.4.0+**: Native support for `SHAKAPACKER_SKIP_PRECOMPILE_HOOK` exists. - **Shakapacker 9.0-9.3**: Prefer script-based hooks with the self-guard for reliable behavior. - **All supported versions**: Script-based hooks are the safest choice for SSR + HMR development. ### CI recommendation In CI, run precompile preparation explicitly once before webpack compilation or test startup, rather than relying on hook timing in watch-like flows. ## Upgrading to v17 (from v16) ### Breaking Changes - **Ruby 3.3+ is required.** Upgrade Ruby before moving to React on Rails v17. React on Rails v16 remains the supported line for applications that must stay on Ruby 3.2 or older. - **React on Rails Pro already required Ruby 3.3+.** v17 aligns the open-source gem, Pro gem, create-app validator, and CI minimum matrix on the same Ruby floor. - **Three deprecated configuration options were removed.** They were deprecated in v16 and are gone in v17. Setting any of them in `config/initializers/react_on_rails.rb` now raises `NoMethodError` at boot. Run `bin/rake react_on_rails:doctor` to detect any that remain in your initializer. - `config.generated_assets_dirs` — delete the line. Public asset paths are determined automatically from `public_output_path` in `config/shakapacker.yml`. - `config.skip_display_none` — delete the line. It had no runtime effect. - `config.defer_generated_component_packs` — replaced by `config.generated_component_packs_loading_strategy`: - `config.defer_generated_component_packs = true` → `config.generated_component_packs_loading_strategy = :defer` - `config.defer_generated_component_packs = false` → **delete the line.** The old option was truthy-gated — only `= true` did anything (it set `:defer`); `= false` was a no-op that fell through to the default strategy. Deleting the line preserves that behavior. Set `config.generated_component_packs_loading_strategy = :sync` explicitly only if you specifically relied on synchronous (blocking) pack loading. - The default strategy (when you don't set one) is `:async` for Pro or `:defer` for non-Pro on Shakapacker 8.2.0+, and `:sync` on older Shakapacker. ### Migration Steps 1. Upgrade the app to Ruby 3.3 or newer and refresh the Ruby lockfile: ```bash ruby -v bundle install ``` 2. If you scaffold apps with `create-react-on-rails-app`, make sure your shell resolves Ruby 3.3+ before running the CLI. 3. Update the `react_on_rails` gem and `react-on-rails` npm package pins to the same v17 release, then install both lockfiles together: ```bash bundle update react_on_rails # then run your package manager's install command npm install # or: yarn install / pnpm install ``` 4. Run RuboCop, your app's test suite, and asset build after the Ruby and package updates. The Ruby baseline bump can activate cops that were previously inactive: ```bash bundle exec rubocop ``` ## Upgrading to v16.4.0 (from v16.3.x) This release includes major generator improvements, development workflow enhancements, and Pro stability fixes. See the [v16.4.0 Release Notes](release-notes/16.4.0.md) for full details. **Key actions required:** 1. **Update gem and npm package versions** to 16.4.0 2. **Pro users: remove legacy license key file** — `config/react_on_rails_pro_license.key` is no longer read. Move the token to the `REACT_ON_RAILS_PRO_LICENSE` environment variable 3. **Pro RSC users: check `custom_rsc_payload_template` overrides** — the template is now rendered with `formats: [:text]`. If your override is `.html.erb`, rename it to `.text.erb` 4. **Pro users upgrading from 3.x:** See the [Pro Upgrade Guide](../../pro/updating.md) for package rename steps, changed defaults, and version alignment notes ## Upgrading to v16.3.0 (from v16.2.x) This is a minor release. Update your gem and npm package versions, then run `bundle install` and your package manager's install command. See the [v16.3.0 Release Notes](release-notes/16.3.0.md) for details. **Key changes:** 1. **Simplified Shakapacker version handling** — obsolete minimum version checks removed 2. **ShakaCode Trust-Based Commercial Licensing** — Pro now works without a license token for evaluation, development, testing, and CI/CD. A paid license is only required for production deployments ## Upgrading to v16.2.x (from v16.1.x) This release focuses on clear separation between open-source and Pro features. See the [v16.2.x Release Notes](release-notes/16.2.0.md) for full details. **Key actions required:** 1. **Remove `config.immediate_hydration`** from your initializer - this config option has been removed (automatic for Pro users) 2. **Use exact versions** in `package.json` - semver wildcards (`^`, `~`, `*`) now cause boot failures 3. **Pro users:** If importing Pro methods from `react-on-rails`, switch to `react-on-rails-pro` 4. **RSC users:** Move RSC configurations from `ReactOnRails.configure` to `ReactOnRailsPro.configure` ## Upgrading to v16.1.x (from v16.0.x) This is a minor release - update your gem and npm package versions, then run `bundle install` and your package manager's install command. See the [v16.1.x Release Notes](release-notes/16.1.0.md) for new features and bug fixes. **Deprecation:** Remove `config.generated_assets_dirs` from your configuration if present. Asset paths are now automatically determined from `public_output_path` in `config/shakapacker.yml`. ## Upgrading to v16 (from v14/v15) ### Breaking Changes - **Webpacker support completely removed**. Shakapacker >= 6.0 is now required. - **Updated runtime requirements**: - Minimum Ruby version: 3.2 (v16 minimum; v17 requires 3.3+) - Minimum Node.js version: 20 - **Install generator now validates prerequisites** and requires at least one JavaScript package manager ### Migration Steps 1. **Update Dependencies** > **Note**: The versions below are examples. Check the [changelog](https://github.com/shakacode/react_on_rails/blob/master/CHANGELOG.md) for the latest stable release and substitute accordingly. ```ruby # Gemfile gem "react_on_rails", "16.4.0" ``` ```json // package.json — use the npm equivalent of the same release { "dependencies": { "react-on-rails": "16.4.0" } } ``` 2. **Install Updates** ```bash bundle update react_on_rails shakapacker # then run your package manager's install command npm install # or: yarn install / pnpm install ``` 3. **Run Generator** ```bash bundle exec rails generate react_on_rails:install ``` 4. **Review and Apply Changes** - If your app was still on `webpacker`, finish that migration first - Check webpack configuration exports (function naming may have changed) - Review `shakapacker.yml` settings - Update `bin/dev` if needed 5. **Test Your Application** ```bash # Test asset compilation bundle exec rails assets:precompile # Test development server bin/dev # Run your test suite bundle exec rspec # or your test command ``` ### Common Upgrade Issues #### Build Fails with Module Resolution Errors **Symptoms:** Webpack cannot find modules referenced in your configuration **Solutions:** 1. Clear webpack cache: `rm -rf node_modules/.cache` 2. Verify all ProvidePlugin modules exist 3. Check webpack alias configuration For troubleshooting build errors, see the [build errors guide](../deployment/troubleshooting-build-errors.md). ### Enhanced Features in v16 - **Enhanced error handling** in `react_on_rails:generate_packs` task with detailed debugging guidance - **Improved development tooling** with better error messages and troubleshooting steps - **Better package manager detection** with multi-strategy validation ## Upgrading to v13 ### Breaking Change Previously, the gem `webpacker` was a Gem dependency. v13 has changed slightly to switch to `shakapacker`. For details, see the Shakapacker guide to upgrading to [version 6](https://github.com/shakacode/shakapacker/blob/master/docs/v6_upgrade.md) and [version 7](https://github.com/shakacode/shakapacker/blob/master/docs/v7_upgrade.md) In summary: 1. Change the gem reference from 'webpacker' to 'shakapacker' 2. Change the npm reference from '@rails/webpacker' to 'shakapacker' 3. Other updates, depending on what version of `rails/webpacker` that you had. ## Upgrading to v12 ### Recent versions Make sure that you are on a relatively more recent version of Rails and Webpacker. Yes, the [rails/webpacker](https://github.com/rails/webpacker) gem is required! v12 is tested on Rails 6. It should work on Rails v5. If you're on any older version, and v12 doesn't work, please file an issue. ### Removed Configuration config.symlink_non_digested_assets_regex Remove `config.symlink_non_digested_assets_regex` from your `config/initializers/react_on_rails.rb`. If you still need that feature, please file an issue. ### i18n default format changed to JSON - If you're using the internationalization helper, then set `config.i18n_output_format = 'js'`. You can later update to the default JSON format as you will need to update your usage of that file. A JSON format is more efficient. ### Updated API for `ReactOnRails.register()` In order to solve the issues regarding React Hooks compatibility, the number of parameters for functions is used to determine if you have a Render-Function that will get invoked to return a React component, or you are registering a React component defined by a function. Please see [Render-Functions and the Rails Context](../core-concepts/render-functions-and-railscontext.md) for more information on what a Render-Function is. ##### Update required for registered functions taking exactly 2 params. Registered Objects are of the following type: 1. **Function that takes only zero or one params and returns a React Element**, often JSX. If the function takes zero or one params, there is **no migration needed** for that function. ```js export default (props) => <Component {...props} />; ``` 2. **Function that takes only zero or one params and returns an Object (_not a React Element_)**. If the function takes zero or one params, **you need to add one or two unused params so you have exactly 2 params** and then that function will be treated as a render function and it can return an Object rather than a React element. If you don't do this, you'll see this obscure error message: ```text [SERVER] message: Objects are not valid as a React child (found: object with keys {renderedHtml}). If you meant to render a collection of children, use an array instead. in YourComponentRenderFunction ``` So look in `YourComponentRenderFunction` and do this change ```js export default (props) => ({ renderedHTML: getRenderedHTML(), }); ``` To have exactly 2 arguments: ```js export default (props, _railsContext) => ({ renderedHTML: getRenderedHTML(), }); ``` 3. Function that takes **2 params** and returns **a React function or class component**. _Migration is needed as the older syntax returned a React Element._ A function component is a function that takes zero or one params and returns a React Element, like JSX. The correct syntax looks like: ```js export default (props, railsContext) => () => <Component {...{ ...props, railsContext }} />; ``` Note, you cannot return a React Element (JSX). See below for the migration steps. If your function that took **two params returned an Object**, then no migration is required. 4. Function that takes **3 params** and uses the 3rd param, `domNodeId`, to call `ReactDOM.hydrate`. If the function takes 3 params, there is **no migration needed** for that function. 5. ES6 or ES5 class. There is **no migration needed**. Previously, with case number 2, you could return a React Element. The fix is simple. Here is an example of the change you'll do:  ##### Broken, as this function takes two params and it returns a React Element from a JSX Literal ```js export default (props, _railsContext) => <Component {...props} />; ``` If you make this mistake, you'll get this warning `Warning: React.createElement: type is invalid -- expected a string (for built-in components) or a class/function (for composite components) but got: <Fragment />. Did you accidentally export a JSX literal instead of a component?` And this error: `react-dom.development.js:23965 Uncaught Error: Element type is invalid: expected a string (for built-in components) or a class/function (for composite components) but got: object.` In this example, you need to wrap the `<Component {...props} />` in a function call like this which results in the return value being a React function component. ```js export default (props, _railsContext) => () => <Component {...props} />; ``` If you have a pure component, taking one or zero parameters, and you have an unnecessary function wrapper such that you're returning a function rather than a React Element, then: 1. You won't see anything render. 2. You will see this warning in development mode: `Warning: Functions are not valid as a React child. This may happen if you return a Component instead of <Component /> from render. Or maybe you meant to call this function rather than return it.` --- ## Upgrading rails/webpacker from v3 to v4 ### Custom Webpack build file The default value for `extract_css` is **false** in `config/webpack.yml`. Custom Webpack builds should set this value to true, or else no CSS link tags are generated. You have a custom Webpack build if you are not using [rails/webpacker](https://github.com/rails/webpacker) to set up your Webpack configuration. ```yml default: &default # other stuff extract_css: true # by default, extract and emit a css file. The default is false ``` ## Upgrading to version 11 - Remove `server_render_method` from config/initializers/react_on_rails.rb. Alternate server rendering methods are part of React on Rails Pro. If you want to use a custom renderer, contact justin@shakacode.com. We have a custom node rendering solution in production for egghead.io. - Remove your usage of ENV["TRACE_REACT_ON_RAILS"] usage. You can get all tracing with either specifying **`trace`** at your component or in your config/initializers/react_on_rails.rb file. - ReactOnRails::Utils.server_bundle_file_name and ReactOnRails::Utils.bundle_file_name were removed. React on Rails Pro contains upgrades to enable component and other types caching with React on Rails. ## Upgrading to version 10 Pretty simple: - Follow the steps to migrate to version 9 (except installing 10.x instead of 9.x) - If you have `react_component` returning hashes, then switch to `react_component_hash` instead ## Upgrading to version 9 ### Why Webpacker? Webpacker provides areas of value: - View helpers that support bypassing the asset pipeline, which allows you to avoid double minification and enable source maps in production. This is 100% a best practice, as source maps in production greatly increases the value of services such as HoneyBadger or Sentry. - A default Webpack config so that you only need to do minimal modifications and customizations. However, if you're doing server rendering, you may not want to give up control. Since Webpacker's default Webpack config is changing often, we at Shakacode can give you definitive advice on Webpack configuration best practices. In general, if you're happy with doing your own Webpack configuration, then we suggest using the `client` strategy discussed below. Most corporate projects will prefer having more control than direct dependence on webpacker easily allows. ### Integrating Webpacker Reason for doing this: This enables your Webpack bundles to bypass the Rails asset pipeline and its extra minification, enabling you to use source-maps in production, while still maintaining total control over everything in the client directory. #### From version 7 or lower ##### ...while keeping your `client` directory - `.gitignore`: add `/public/webpack/*`. - `Gemfile`: bump `react_on_rails` and add `webpacker`. - layout views: anything bundled by Webpack will need to be requested by a `javascript_pack_tag` or `stylesheet_pack_tag`. - Search your codebase for javascript_include_tag. Use the - `config/initializers/assets.rb`: we no longer need to modify `Rails.application.config.assets.paths` or append anything to `Rails.application.config.assets.precompile`. - `config/initializers/react_on_rails.rb`: - Delete `config.generated_assets_dir`. Webpacker's config now supplies this information. - Replace `config.npm_build_(test|production)_command` with `config.build_(test|production)_command`. - `config/webpacker.yml`: start with our [example config](https://github.com/shakacode/react-on-rails-v9-rc-generator/blob/master/config/webpacker.yml) (feel free to modify it as needed). I recommend setting dev_server.hmr to false however since HMR is currently broken. - `client/package.json`: bump `react_on_rails` (I recommend bumping `webpack` as well). You'll also need `js-yaml` if you're not already using `eslint` and `webpack-manifest-plugin` regardless. ###### Client Webpack config - You'll need the following code to read data from the webpacker config: ```javascript const path = require('path'); const ManifestPlugin = require('webpack-manifest-plugin'); // we'll use this later const webpackConfigLoader = require('react-on-rails/webpackConfigLoader'); const configPath = path.resolve('..', 'config'); const { output } = webpackConfigLoader(configPath); ``` - That output variable will be used for Webpack's `output` rules: ```javascript output: { filename: '[name]-[chunkhash].js', // [chunkhash] because we've got to do our own cache-busting now path: output.path, publicPath: output.publicPath, }, ``` - ...as well as for the output of plugins like `webpack-manifest-plugin`: ```javascript new ManifestPlugin({ publicPath: output.publicPath, writeToFileEmit: true }), ``` - If you're using referencing files or images with `url-loader` & `file-loader`, their publicpaths will have to change as well: `publicPath: '/webpack/',` - If you're using `css-loader`, `webpack.optimize.CommonsChunkPlugin`, or `extract-text-webpack-plugin`, they will also need cache-busting! ...and you're finally done! ##### ...while replacing your `client` directory - Make the same changes to `config/initializers/react_on_rails.rb as described above` - Upgrade RoR & add Webpacker in the Gemfile - Upgrade RoR in the `client/package.json` - Run `bundle` - Run `rails webpacker:install` - Run `rails webpacker:install:react` - Run `rails g react_on_rails:install` - Move your entry point files to `app/javascript/packs` - Either: - Move all your source code to `app/javascript/bundles`, move your linter configs to the root directory, and then delete the `client` directory - or just delete the Webpack config and remove Webpack, its loaders, and plugins from your `client/package.json`. ...and you're done. #### From version 8 For an example of upgrading, see [react-webpack-rails-tutorial/pull/416](https://github.com/shakacode/react-webpack-rails-tutorial/pull/416). - Breaking Configuration Changes 1. Added `config.node_modules_location` which defaults to `""` if Webpacker is installed. You may want to set this to `'client'` in `config/initializers/react_on_rails.rb` to keep your `node_modules` inside the `/client` directory. 2. Renamed - config.npm_build_test_command ==> config.build_test_command - config.npm_build_production_command ==> config.build_production_command - Update the gemfile. Switch over to using the webpacker gem. ```rb gem "webpacker" ``` - Update for the renaming in the `WebpackConfigLoader` in your Webpack configuration. You will need to rename the following object properties: - webpackOutputPath ==> output.path - webpackPublicOutputDir ==> output.publicPath - hotReloadingUrl ==> output.publicPathWithHost - hotReloadingHostname ==> settings.dev_server.host - hotReloadingPort ==> settings.dev_server.port - hmr ==> settings.dev_server.hmr - manifest ==> Remove this one. We use the default for Webpack of manifest.json - env ==> Use `const { env } = require('process');` - devBuild ==> Use `const devBuild = process.env.NODE_ENV !== 'production';` - Edit your Webpack.config files: - Change your Webpack output to be like this. **Be sure to have the hash or chunkhash in the filename,** unless the bundle is server side.: ```javascript const webpackConfigLoader = require('react-on-rails/webpackConfigLoader'); const configPath = resolve('..', 'config'); const { output, settings } = webpackConfigLoader(configPath); const hmr = settings.dev_server.hmr; const devBuild = process.env.NODE_ENV !== 'production'; output: { filename: isHMR ? '[name]-[hash].js' : '[name]-[chunkhash].js', chunkFilename: '[name]-[chunkhash].chunk.js', publicPath: output.publicPath, path: output.path, }, ``` - Change your ManifestPlugin definition to something like the following ```javascript new ManifestPlugin({ publicPath: output.publicPath, writeToFileEmit: true }), ``` - Find your `webpacker_lite.yml` and rename it to `webpacker.yml` - Consider copying a default webpacker.yml setup such as https://github.com/shakacode/react-on-rails-v9-rc-generator/blob/master/config/webpacker.yml - If you are not using the webpacker Webpack setup, be sure to put in `compile: false` in the `default` section. - Alternately, if you are updating from webpacker_lite, you can manually change these: - Add a default setting ```yaml cache_manifest: false ``` - For production, set: ```yaml cache_manifest: true ``` - Add a section like this under your development env: ```yaml dev_server: host: localhost port: 3035 hmr: false ``` Set hmr to your preference. - See the example `react_on_rails/spec/dummy/config/webpacker.yml`. - Remove keys `hot_reloading_host` and `hot_reloading_enabled_by_default`. These are replaced by the `dev_server` key. - Rename `webpack_public_output_dir` to `public_output_path`. - Edit your Procfile.dev - Remove the env value WEBPACKER_DEV_SERVER as it's not used - For hot loading: - Set the `hmr` key in your `webpacker.yml` to `true`. ### Without integrating webpacker - Bump your ReactOnRails versions in `Gemfile` & `package.json` - In `/config/initializers/react_on_rails.rb`: - Rename `config.npm_build_test_command` ==> `config.build_test_command` - Rename `config.npm_build_production_command` ==> `config.build_production_command` - Add `config.node_modules_location = "client"` ...and you're done. ================================================================================ PAGE: https://reactonrails.com/docs/upgrading/release-notes SOURCE: docs/oss/upgrading/release-notes/index.md ================================================================================ # React on Rails Release Notes This archive keeps the major React on Rails OSS release notes easy to browse without listing every version directly in the sidebar. ## Recent OSS Release Notes - [16.4.0](./16.4.0.md) - [16.3.0](./16.3.0.md) - [16.2.0](./16.2.0.md) - [16.1.0](./16.1.0.md) - [16.0.0](./16.0.0.md) - [15.0.0](./15.0.0.md) ## Full Version History - [CHANGELOG.md](https://github.com/shakacode/react_on_rails/blob/main/CHANGELOG.md) ================================================================================ PAGE: https://reactonrails.com/docs/migrating/example-migrations SOURCE: docs/oss/migrating/example-migrations.md ================================================================================ # Example Migrations > **See also:** [Examples and Migration References](../getting-started/examples-and-references.md) > for the broader index of public reference repos (starters, in-repo samples, RSC demos, > and live demos). This page focuses specifically on migration references. Teams evaluating React on Rails are usually not starting from a blank Rails app. They already have one of these: - `react-rails` - `vite_rails` - a custom Rails-side React helper Some teams also arrive from Inertia-first apps. We treat those as a separate architecture case study because they are usually broader page-shell migrations, not narrow React mount migrations. If that is your starting point, begin with [Compare with alternatives](../getting-started/comparing-react-on-rails-to-alternatives.md). This page tracks practical migration references for those cases. ## What makes a useful migration example The best examples are: 1. Real Rails applications, not toy demos 2. Small PRs that convert one page, mount point, or component boundary 3. Honest about blockers such as old lockfiles, native gems, or custom frontend bridges 4. Measured with before-and-after performance or maintainability notes instead of marketing claims ## Current public references ### Published example repos These maintainer-owned references are the stable starting set. Add community examples here after they have landed or stabilized enough to inspect. 1. [react-rails example app: `react-rails-to-react-on-rails` snapshot](https://github.com/shakacode/react-rails-example-app/tree/c6b794a4b96746dbbc98a46f31119171109d70b0) — covers an older `react-rails` v3 → `react_on_rails` v13.4 migration, so treat it as a structural reference and follow current migration guides for gem and configuration specifics 2. [react-on-rails-example-migration](https://github.com/shakacode/react-on-rails-example-migration) — demonstrates a Rails 7-era `react-rails` → `react_on_rails` migration with Shakapacker client/server bundles and SSR setup, based on [ganchdev/react-rails-example](https://github.com/ganchdev/react-rails-example) 3. [react-on-rails-example-open-flights](https://github.com/shakacode/react-on-rails-example-open-flights) — larger example app that shows React on Rails replacing `react-rails` in a more realistic codebase, useful when the smaller migration above does not match the scale of your application ### In-progress migration work In-progress third-party migration PRs are tracked in the [example-migrations meta issue](https://github.com/shakacode/react_on_rails/issues/3125) instead of this docs page. That keeps the public docs focused on durable references while the meta issue can carry working notes about draft PRs, maintainer coordination, blockers, and proof artifacts that may change quickly. See the [Proof artifact template](#proof-artifact-template) for the recommended fields to capture. When a public migration becomes a stable reference, add it to the published example list above with a short proof note. ## Example categories ### `react-rails` to React on Rails This is usually the cleanest migration path: primarily a gem swap and mount registration change while the app architecture stays intact during slice-by-slice conversion. ### `vite_rails` to React on Rails This is more of an asset and entrypoint migration than a component rewrite: the route behavior should stay stable while registration moves into the React on Rails and Shakapacker flow. ### Custom Rails React bridge to React on Rails This is common in mature apps that built a thin wrapper around React mounts. Treat the wrapper as the migration boundary: preserve the Rails-side props contract, replace one helper-backed component first, and remove the wrapper later. No dedicated guide exists yet. If your app uses this pattern and you want to contribute an example, see [Contribute an example](#contribute-an-example). The [react-rails migration guide](./migrating-from-react-rails.md) covers the nearest-neighbor mechanics for helper syntax and component registration. ## What counts as proof Not every good migration example is performance-first. When the change is performance-first, compare the same route on the baseline branch and the migration branch. At minimum, record: 1. Response timing 2. HTML size 3. Route JavaScript bytes 4. Number of JS assets needed for the route 5. Hydration warnings or client boot errors If possible, also record browser load metrics such as FCP, LCP, CLS, and TBT, plus interaction metrics such as INP. TBT is captured by Lighthouse; INP requires field data or a real-user monitoring tool. When the change is maintainability-first, record: 1. The custom bridge, oversized mount, or repo-specific contract that existed before the migration 2. The standardized React on Rails helper or smaller boundary that replaced it 3. What got easier to review, test, or evolve afterward 4. The validation that supports the claim Use maintainability notes when that is the honest win. Do not force a weak benchmark onto an example whose real value is simpler ownership or a narrower integration boundary. ## Proof artifact template Use this template in the migration PR description, linked issue, or a short `docs/` note in the example repository. Fill in the fields that match the claim, mark evidence fields that were not measured as `"not claimed"`, and mark "Known blockers or caveats" as `"none"` when checked and absent. | Field | What to record | | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | Baseline ref | Commit SHA, branch, or tag before the migration | | Migration ref | Commit SHA, branch, this PR if it is the migration PR, or another PR after the migration | | Route or component | The exact Rails route, controller action, or React mount point | | Date captured | YYYY-MM-DD or release milestone when the evidence was collected | | React on Rails version | Target gem/npm package version, or a branch/PR link if targeting a pre-release | | Starting integration | `react-rails`, `vite_rails`, custom helper, older `react_on_rails` version, or other | | Migration slice | What changed and what intentionally stayed out of scope | | Performance evidence | Response timing, HTML size, JS bytes, asset count, Lighthouse/WebPageTest/RUM metrics, or "not claimed"; see [What counts as proof](#what-counts-as-proof) | | Maintainability evidence | Removed custom bridge code, smaller mount boundary, standardized helper usage, or "not claimed"; see [What counts as proof](#what-counts-as-proof) | | Validation | Test commands, build commands, browser smoke checks, screenshots, or CI links; **required** | | Known blockers or caveats | Native services, old lockfiles, auth setup, browser-only flows, environment assumptions, or "none" | | Honest summary sentence | One sentence contributors can write and maintainers can quote without overstating the result | Copy this table when opening a migration PR: ```markdown <!-- Use "not claimed" for evidence fields that do not apply. Use "none" for Known blockers when there are none. --> <!-- Validation is required; do not leave it blank. --> | Field | Value | | ------------------------- | ----------------- | | Baseline ref | | | Migration ref | | | Route or component | | | Date captured | | | React on Rails version | | | Starting integration | | | Migration slice | | | Performance evidence | | | Maintainability evidence | | | Validation | <!-- required --> | | Known blockers or caveats | | | Honest summary sentence | | ``` Example summary sentences: - "This migration is performance-first: the route ships fewer JavaScript bytes and keeps the same Rails response contract." - "This migration is maintainability-first: it replaces a custom Rails-side React bridge with a standard React on Rails helper while preserving route behavior." - "This migration is setup-only proof: it demonstrates the minimum config changes needed for a legacy stack, but does not claim route-level speedup." - "This mixed-result migration delivers both: the route ships fewer bytes (performance) and removes a custom bridge helper (maintainability)." ## Contribute an example If your migration could help other teams evaluate React on Rails, [open an issue](https://github.com/shakacode/react_on_rails/issues/new/choose) or [submit a PR](https://github.com/shakacode/react_on_rails/compare) adding it to this page, and include: 1. The integration you started from, such as `react-rails`, `vite_rails`, or a custom helper 2. The first slice you picked and why it was small enough to review 3. The proof you captured, whether that was performance, maintainability, or both 4. The validation you ran locally or in CI The most useful next examples are: 1. `react-rails` apps that migrate one Rails-owned mount at a time 2. Modern `vite_rails` apps where one Rails-owned island can move before a broader asset rewrite 3. Apps with a custom Rails-side React bridge where one helper-backed boundary can be replaced before removing the wrapper 4. Upgrades from older `react_on_rails` versions to current maintained defaults ## How to use these examples Use this page together with the specific migration guide that matches your current stack: 1. [Migrate from `react-rails`](./migrating-from-react-rails.md) 2. [Migrate from `vite_rails`](./migrating-from-vite-rails.md) Other migration paths live in the **Migration Guides** sidebar: - [Migrate from Webpack to Rspack](./migrating-from-webpack-to-rspack.md) - [Migrate from Babel to SWC](./babel-to-swc-migration.md) - [Migrate a Rails 5 API-only app](./convert-rails-5-api-only-app.md) - [Migrate from AngularJS](./angular-js-integration-migration.md) React Server Components migration content lives under **React on Rails Pro** in the sidebar: - [Migrate to React Server Components (RSC)](./migrating-to-rsc.md) The migration guides explain the mechanics. This page shows what those mechanics look like in real repos. ================================================================================ PAGE: https://reactonrails.com/docs/migrating/migrating-from-nextjs SOURCE: docs/oss/migrating/migrating-from-nextjs.md ================================================================================ # Migrate from Next.js This guide is for teams running a **Next.js frontend against a Rails backend** (or evaluating that split) who want to collapse the two apps into a single Rails application with React on Rails — keeping modern React (server components, streaming, `'use client'`) while deleting the duplicated auth, API, and deployment layers. It has two parts: 1. A [capability mapping](#capability-mapping-nextjs--react-on-rails-pro) from Next.js App Router concepts to their React on Rails (and React on Rails Pro) equivalents — restricted to what is shipped today, with a short, explicit roadmap list for the rest. 2. An [incremental migration strategy](#collapse-the-two-app-stack-incremental-migration-behind-a-reverse-proxy) for moving a Next.js app into Rails route-by-route behind a reverse proxy, with no big-bang cutover. For the architectural decision itself (one app vs. two), see [Next.js with a Separate Rails Backend: Pros and Drawbacks](../getting-started/nextjs-with-separate-rails-backend.md) and [Comparing React on Rails to Alternatives](../getting-started/comparing-react-on-rails-to-alternatives.md). ## When this migration makes sense - You run (or are about to run) **two apps** — a Next.js frontend and a Rails API — and are paying for it twice: two deploys, two runtimes to monitor and patch, duplicated session/CSRF/auth handling, and an API contract whose only consumer is your own frontend. - Your team is **Rails-strong** and the API exists mostly to feed the Next.js app, not external clients. - You want React Server Components, streaming SSR, and component caching, and would rather get them inside Rails than maintain a second framework's mental model. These are [React on Rails Pro](../../pro/react-on-rails-pro.md) features. ## When to stay on Next.js Be honest about the cases where this migration is the wrong move: - **No Rails team.** If Rails is not already a first-class part of your stack, adopting it to host React is a bigger change than this guide covers. - **Your API has many external consumers.** If mobile apps and partners consume the same API, the two-app split is carrying real architectural weight (see the [decision checklist](../getting-started/nextjs-with-separate-rails-backend.md#decision-checklist)). - **You depend on Vercel-specific edge features** (edge middleware/functions at the CDN, ISR served from Vercel's CDN). React on Rails runs on any Rack host; it does not replicate Vercel's edge network. ## Capability mapping: Next.js → React on Rails (Pro) Every row in this table maps to a feature that is **shipped and documented today**. Rows marked **[Pro]** require [React on Rails Pro](../../pro/react-on-rails-pro.md); RSC and streaming additionally require the [Node renderer](../../pro/node-renderer.md). | Next.js (App Router) | React on Rails (Pro) | Docs | | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | React Server Components (server-first pages) | **[Pro]** `registerServerComponent` to register, `RSCRoute` to embed server components inside client trees | [RSC hub](../../pro/react-server-components/index.md), [RSC inside client components](../../pro/react-server-components/inside-client-components.md) | | `'use client'` directive | Same directive, unchanged. **[Pro]** auto-bundling reads it to choose between `ReactOnRails.register` and `registerServerComponent` | [Auto-bundling with RSC](../core-concepts/auto-bundling-file-system-based-automated-bundle-generation.md#auto-bundling-with-react-server-components) | | Streaming SSR + `<Suspense>` (`loading.tsx`) | **[Pro]** `stream_react_component` and `stream_react_component_with_async_props` | [Streaming SSR](../../pro/streaming-ssr.md) | | Data fetching in server components (`fetch` to your own API) | **In-process data access** — ActiveRecord in the controller or in async-props blocks; no HTTP hop, no API layer to maintain | [RSC data fetching](./rsc-data-fetching.md), **[Pro]** [DB queries in async props](../../pro/async-props-database-queries.md) | | Form mutations (`useActionState` / `useFormStatus`) | `useRailsForm` hook — `useForm`-style `data`/`errors`/`processing`/`wasSuccessful` posting to a plain Rails controller, with automatic CSRF and `422` model-error mapping (`FormResponders` concern) | [Forms and Mutations](../building-features/forms.md) | | Full Route Cache / component caching | **[Pro]** `cached_react_component` (fragment caching) and one-line prerender caching | [Caching](../building-features/caching.md), [Fragment caching](../../pro/fragment-caching.md) | | Metadata API (`metadata` export, `generateMetadata`) | React 19 native metadata — `<title>`/`<meta>`/`<link>` rendered in components are hoisted to `<head>`; works with SSR, streaming, and RSC | [React 19 Native Metadata](../building-features/react-19-native-metadata.md) | | `next/font/local` | `react_on_rails_font_face` view helper — self-hosted `.woff2` preload, `@font-face` with `font-display`, metric-matched fallback | [Font Optimization](../building-features/fonts.md) | | `next/link` + client-side routing | React Router or TanStack Router integration (your routes, SSR-compatible) | [React Router](../building-features/react-router.md), [TanStack Router](../building-features/tanstack-router.md) | | `middleware.ts` (auth gating, redirects, headers) | Rack middleware and Rails controller filters — auth runs in the same process as the data it protects (Devise/Warden and friends) | [Rails on Rack](https://guides.rubyonrails.org/rails_on_rack.html) | | `next dev` (HMR dev server) | `bin/dev` — Rails plus webpack-dev-server with HMR by default | [HMR and dev server modes](../building-features/dev-server-and-testing.md) | | Vercel deploy / self-hosted `next start` | Any Rack host: one Rails deploy, standard Rails 7.1+ Dockerfile; **[Pro]** Node renderer ships as a sidecar container when you use SSR/RSC | [Docker deployment](../deployment/docker-deployment.md), [Node renderer container deployment](../building-features/node-renderer/container-deployment.md) | The headline row is data access. In the two-app stack, a "server component" in Next.js still fetches from your Rails API over HTTP, with auth forwarded across the boundary. After the migration the same component's data comes from ActiveRecord in-process — the API endpoints that existed only to feed the frontend get deleted, not rewritten. ### On the roadmap (not shipped yet) These Next.js capabilities do not have a first-party React on Rails equivalent today. Each is tracked in an open issue; the table lists the interim approach. | Next.js capability | Status | | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | Server Actions (`'use server'`) | Tracked in [#3867](https://github.com/shakacode/react_on_rails/issues/3867). Today: Rails controller actions receiving regular form posts | | `use cache` tags / `revalidateTag` | Tracked in [#3871](https://github.com/shakacode/react_on_rails/issues/3871). Today: key-based cache expiry via the `cache_key` option | | File-system routing, nested layouts, prefetch | Tracked in [#3873](https://github.com/shakacode/react_on_rails/issues/3873). Today: Rails routes + React Router/TanStack Router | | `next/image` optimization analog | Tracked in [#3874](https://github.com/shakacode/react_on_rails/issues/3874). Today: webpack asset pipeline ([images](../building-features/images.md)) | ## Collapse the two-app stack: incremental migration behind a reverse proxy You do not need a big-bang rewrite. Because the two-app stack already routes browser traffic through a reverse proxy (or can trivially be put behind one), you can migrate **one route group at a time**: Rails takes over a path prefix, Next.js keeps serving everything else, and users never notice the seam. ### Step 0: Prerequisites - Your Rails app (today's API backend) gets React on Rails installed: [Installation into an Existing Rails App](../getting-started/installation-into-an-existing-rails-app.md). For RSC/streaming parity with Next.js, add [React on Rails Pro](../../pro/installation.md) and the Node renderer. - Both apps must be reachable from one reverse proxy you control: nginx, Caddy, HAProxy, an ALB, or your CDN's origin routing all work. If Next.js and Rails are on separate subdomains (`app.example.com` + `api.example.com`), plan to serve the migrated routes from the main domain — same-origin is what lets you delete the cross-origin auth plumbing later. ### Step 1: One domain, one proxy Route all browser traffic through the proxy, with Next.js as the default upstream and Rails opted in per path: ```nginx upstream nextjs { server 127.0.0.1:3000; } upstream rails { server 127.0.0.1:3001; } server { listen 443 ssl; ssl_certificate /etc/ssl/certs/example.com.pem; # replace with your cert path ssl_certificate_key /etc/ssl/private/example.com.key; # replace with your key path server_name example.com; # Terminate TLS at the proxy so both upstreams speak plain HTTP internally. # nginx proxies upstream over HTTP/1.0 by default, which lacks chunked # transfer encoding (required for streaming SSR) and disables keep-alive. # Use HTTP/1.1 and clear the Connection header. proxy_http_version 1.1; proxy_set_header Connection ""; # Disabled globally because BOTH stacks stream during the migration: # Next.js (loading.tsx, async server components) and Rails # (stream_react_component, RSC async props). nginx buffers the full # response by default, defeating streaming. Alternatively, keep buffering # on and have each app send `X-Accel-Buffering: no` on streaming responses. proxy_buffering off; # Streaming SSR and RSC async-props responses can hold connections open # longer than nginx's default 60s proxy_read_timeout. Tune to match your # slowest expected stream. # proxy_read_timeout 120s; # Forward the browser-facing origin so both apps generate correct URLs # and the shared session cookie stays on example.com. proxy_set_header Host $host; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; # Migrated route groups go to Rails (grows over time). Match the exact # path plus its subpaths — a bare prefix like `location /account` would # also capture /accounting. location = /account { proxy_pass http://rails; } location /account/ { proxy_pass http://rails; } location = /settings { proxy_pass http://rails; } location /settings/ { proxy_pass http://rails; } # Rails also keeps serving the existing API for not-yet-migrated pages location /api/ { proxy_pass http://rails; } # Everything else stays on Next.js until migrated location / { proxy_pass http://nextjs; } } ``` Each migrated route group is a two-line proxy change — and a two-line rollback if something goes wrong. :::caution proxy_set_header inheritance nginx only inherits `server`-level `proxy_set_header` directives into `location` blocks that define **none** of their own. If you later add a `proxy_set_header` inside a `location`, repeat all of the headers above in that block. ::: ### Step 2: Share the session Pick the Rails session as the source of truth for authentication: - Set the Rails session cookie on the shared domain. Since the proxy serves both apps from one origin, the browser sends the same cookie to both upstreams. If the cookie was previously scoped to an API subdomain, set the domain explicitly: ```ruby # config/initializers/session_store.rb Rails.application.config.session_store :cookie_store, key: "_example_session", domain: "example.com", # the shared, browser-facing domain secure: true, # HTTPS only — TLS terminates at the proxy same_site: :lax ``` - Next.js pages that need auth state already forward cookies to the Rails API for data fetching; that keeps working unchanged. - Avoid migrating _half_ of an auth flow. Move login/logout/signup to Rails early (they are usually plain forms — the easiest pages to port), so there is exactly one place that writes the session. ### Step 3: Migrate one route group at a time Pick a self-contained route group (start with a low-risk one). For each: 1. **Add the Rails route and controller.** The controller loads data with ActiveRecord directly — this replaces the API call the Next.js page was making. 2. **Port the page component.** Your React components move largely as-is (see [porting notes](#porting-component-code) below). Render with `react_component` in the view, or `stream_react_component` / `RSCRoute` with Pro for streaming and server components. 3. **Verify behind the proxy locally**, then flip the `location` block for that path prefix from the Next.js upstream to Rails. 4. **Watch error rates and Core Web Vitals** for the migrated paths; roll back by reverting the proxy line if needed. ### Step 4: Retire redundant API endpoints After each route group moves, the API endpoints that existed only to feed those Next.js pages have no callers left. Delete them (or log access first to confirm). This is where the maintenance win compounds: every migrated route shrinks the API surface you version, document, and secure. ### Step 5: Final cutover checklist When the last route group flips to Rails: - [ ] All `location` blocks point at Rails; the Next.js upstream receives no traffic (verify with proxy access logs). - [ ] Remove the Next.js app from CI/CD and infrastructure; archive the repo or directory. - [ ] Delete frontend-only API endpoints, CORS configuration, and token-exchange/refresh plumbing that existed for the cross-app split. - [ ] Move redirects that lived in `next.config.js` / `middleware.ts` into the proxy config or Rails routes. - [ ] Re-point sitemap/robots generation, health checks, and uptime monitoring at the Rails app. - [ ] Collapse the two deploy pipelines into one. ## Porting component code Most of your React code is framework-agnostic and moves unchanged. The Next.js-specific imports are the work: - **`'use client'`** — keep it. With Pro RSC auto-bundling, the directive determines registration (client component vs. server component) exactly as it determines the boundary in Next.js. Without RSC, every component is a client component and the directive is inert but harmless. - **`next/link`, `useRouter`, `usePathname`** — replace with plain `<a>` tags (Rails-routed pages) or your client router's equivalents ([React Router](../building-features/react-router.md), [TanStack Router](../building-features/tanstack-router.md)). - **`next/head` / Metadata API** — replace with React 19 native `<title>`/`<meta>`/`<link>` tags rendered directly in components ([guide](../building-features/react-19-native-metadata.md)). - **`next/image`** — replace with `<img>` plus webpack-pipeline assets ([images](../building-features/images.md)); a first-party optimization helper is tracked in [#3874](https://github.com/shakacode/react_on_rails/issues/3874). - **`next/font`** — replace with the [`react_on_rails_font_face` helper](../building-features/fonts.md) for the `next/font/local` use case (self-hosted `.woff2`, preload, metric-matched fallback). - **`fetch` in server components** — delete the HTTP hop: pass props from the controller, or query ActiveRecord in async-props blocks ([RSC data fetching](./rsc-data-fetching.md)). - **`process.env.NEXT_PUBLIC_*`** — pass values as props from Rails, or configure them in your webpack build (e.g., `EnvironmentPlugin`/`DefinePlugin`). - **CSS Modules / global CSS** — supported via Shakapacker's webpack setup; for server components see [CSS and styling with RSC](../../pro/react-server-components/css-and-styling.md). If you are adopting server components as part of the move, the [RSC migration series](./migrating-to-rsc.md) covers component restructuring, context/state, and data-fetching patterns in depth — it applies directly to components arriving from Next.js. ## Related reading - [Next.js with a Separate Rails Backend: Pros and Drawbacks](../getting-started/nextjs-with-separate-rails-backend.md) — the architecture decision this guide assumes you've made - [Comparing React on Rails to Alternatives](../getting-started/comparing-react-on-rails-to-alternatives.md) - [React on Rails Pro](../../pro/react-on-rails-pro.md) — RSC, streaming SSR, caching, Node renderer - [RSC Migration Series](./migrating-to-rsc.md) - [Example Migrations](./example-migrations.md) ================================================================================ PAGE: https://reactonrails.com/docs/migrating/migrating-from-react-rails SOURCE: docs/oss/migrating/migrating-from-react-rails.md ================================================================================ # Migrate From react-rails This migration is easiest when the app is already on a modern Rails + Shakapacker baseline. If you want repo-shaped references before touching your own app, start with [Example Migrations](./example-migrations.md) and then come back here for the mechanics. ## Pick the right first target Not every `react-rails` app is a good candidate for a low-friction first migration. Before you start, classify what you have: - **Rails-owned island mounts on Shakapacker 6+ and Rails 6+.** This is the smoothest path. The generator + the steps below usually get you there with small, localized edits. (Note: `server_bundle_output_path` auto-detection requires Shakapacker 9.0+; on 6–8, set it explicitly in the initializer.) - **Webpacker-era apps (`gem "webpacker"`, Webpack 4).** Current React on Rails targets Shakapacker, not Webpacker, as the recommended baseline — `react_on_rails doctor` flags Webpacker as a removed breaking-change issue, and the gem requires `shakapacker >= 6.0`. Migrate off Webpacker before installing current React on Rails when you can. If you need a temporary Webpacker 5 / Webpack 4 bridge, see the [Legacy Webpacker / Webpack 4 migration shims](../building-features/rails-webpacker-react-integration-options.md#legacy-webpacker--webpack-4-migration-shims) and verify the full app locally. - **Client-routed SPA shells (Rails is mostly a shell around a React Router / TanStack Router app).** Render the top-level SPA component from one ERB view using `react_component` (or `react_component_hash` when SSR needs to return multiple regions such as `componentHtml`, `title`, and other head tags). - One `react_component` call mounts the whole app. - If you additionally want to break the SPA into several Rails-owned islands, treat that as a separate product decision rather than bundling it with the bundler/integration change. The wrong first target usually leads teams to conclude "React on Rails is broken" when the real problem is legacy bundler compatibility, or to bundle a SPA re-architecture into what should have been a bundler migration. ## Choose a first slice Pick a small first slice before you touch the whole app: 1. Prefer one Rails-owned page, island, or shell fragment over a broad page rewrite. 2. Good first wins are often maintainability-first: replacing `ReactRailsUJS` on one low-risk mount, splitting a large shell into smaller boundaries, or moving one legacy Rails page behind a documented helper path. 3. The first PR does not need to eliminate every `react_component` call. It only needs to prove that one mount can move cleanly. ## Preferred path for Webpacker-era apps If the app still uses `gem "webpacker"`, the recommended path is: 1. **Migrate to Shakapacker first, as its own PR.** Keep the bundler change separate from the React on Rails change. This makes each step reviewable and isolates any compatibility issues. See the [Shakapacker v6 upgrade guide](https://github.com/shakacode/shakapacker/blob/v6.6.0/docs/v6_upgrade.md) for the concrete Webpacker → Shakapacker steps. 2. **Then run the React on Rails install generator** against the Shakapacker-based app. The generator is not designed to bridge Webpack 4 + Webpacker to current React on Rails defaults for you — it assumes a Shakapacker baseline. If you cannot migrate off Webpacker yet and need the lowest-risk supported path, pin `react_on_rails` to `~> 14.2` (v15.0.0 is retracted; v16 is the release that removed Webpacker support). Only if pinning is not viable and you must run current React on Rails against Webpack 4 should you use the [Legacy Webpacker / Webpack 4 migration shims](../building-features/rails-webpacker-react-integration-options.md#legacy-webpacker--webpack-4-migration-shims) as a narrow, temporary, and untested bridge; verify the full app build locally before relying on it. ## Preflight Before swapping gems, check these first: 1. **Webpacker vs Shakapacker**: if the app still uses `webpacker`, see [Preferred path for Webpacker-era apps](#preferred-path-for-webpacker-era-apps) above. 2. **Bundler age**: some older `react-rails` apps still carry Bundler 1.x lockfiles. Those can fail on modern Ruby before you even reach the migration work. 3. **Rails age**: current `react_on_rails` requires Rails 5.2+. Rails 5.1 / Webpacker 3 apps are usually a staged migration, not a one-command migration. 4. **Package manager metadata**: if you have `yarn.lock`, `pnpm-lock.yaml`, or `bun.lock*`, ensure `package.json` has a matching `packageManager` field (for example `npm@10.9.2`, `yarn@1.22.22`, `pnpm@10.12.1`, or `bun@1.2.13`). 5. **Browserslist source**: use one source only. If `.browserslistrc` exists, remove `browserslist` from `package.json`. 6. **JSX-in-.js projects**: current install generator auto-switches to Babel when JSX is detected in `.js` files. If your project has custom transpiler setup, review `config/shakapacker.yml` after generation. 7. **`react_component` helper collision**: if you plan to keep `react-rails` installed during a staged migration, read [Coexistence: keeping both gems installed during a staged migration](#coexistence-keeping-both-gems-installed-during-a-staged-migration) before adding `react_on_rails`. Both gems define a `react_component` view helper with incompatible signatures; once `react_on_rails` is present, its helper takes precedence in all views regardless of gem load order. If you are already on `shakapacker` 7+ and React 18+, the migration is mostly about helper syntax, component registration, and generated defaults. If `bundle install` fails before you even start because the lockfile was generated by Bundler 1.x, refresh the lockfile with a modern Bundler first: ```bash bundle _2.3.26_ lock --update bundle _2.3.26_ install ``` If `package.json` is missing `packageManager`, set it to your project's actual manager and exact version before running install generators: ```bash # pick the one that matches your lockfile npm pkg set packageManager='npm@10.9.2' npm pkg set packageManager='yarn@1.22.22' npm pkg set packageManager='pnpm@10.12.1' npm pkg set packageManager='bun@1.2.13' ``` 1. Update Deps 1. Replace `react-rails` in `Gemfile` with `react_on_rails` and make sure `shakapacker` is present. 2. Remove `react_ujs` from `package.json`. 3. Run `bundle install` and your package manager's install command. 4. Commit changes. 2. Run `rails g react_on_rails:install` but do not commit the change. `react_on_rails` attempts to install node dependencies, creates a sample React component, Rails view/controller, and updates `config/routes.rb`. If dependency installation fails, the generator prints manual install commands. If required package-manager tooling (Node.js and npm/yarn/pnpm/bun) is unavailable, the generator stops with setup guidance. Run the suggested commands or install missing tools before continuing. 3. Adapt the project: Check the changes and carefully accept, reject, or modify them as per your project's needs. Besides changes in `config/shakapacker` or `babel.config` which are project-specific, here are the most noticeable changes to address: 1. Check Webpack config files at `config/webpack/*`. If coming from `react-rails` v3 on Shakapacker, the changes are usually localized. The most important difference is the server bundle entrypoint: `react-rails` commonly uses `server_rendering.js`, while React on Rails defaults to `server-bundle.js`. 2. In `app/javascript` directory you may notice some changes. 1. `react_on_rails` can work with manual registration or the newer auto-bundling flow. Auto-bundling is usually the cleaner target for new work. 2. `react_on_rails` uses `server-bundle.js` instead of `server_rendering.js`. If you keep your old filename, update the generated config accordingly. 3. Replace `ReactRailsUJS` mounting with explicit React on Rails registration. The generated files show the current registration pattern. 3. Check Rails views. In `react_on_rails`, `react_component` view helper works slightly differently. It takes two arguments: the component name, and options. Props is one of the options. Take a look at the following example: ```diff - <%= react_component('Post', { title: 'New Post' }, { prerender: true }) %> + <%= react_component('Post', { props: { title: 'New Post' }, prerender: true }) %> ``` 4. Validate before final cleanup: 1. Confirm that old `react_ujs` references are gone: ```bash rg -n "react_ujs|ReactRailsUJS|server_rendering\.js" app/javascript app/assets app/views config # or without ripgrep: grep -rn "react_ujs\|ReactRailsUJS\|server_rendering\.js" app/javascript app/assets app/views config ``` 2. Ensure compile succeeds: ```bash bundle exec rails shakapacker:compile ``` 3. Review `react_component` helper calls to ensure they use options-style props: ```bash rg -n "react_component\\b" app/views # or without ripgrep: grep -rEn "react_component\\b" app/views ``` These commands list candidates only. Inspect each match manually and convert any legacy positional calls (for example `react_component('Post', @props, prerender: true)`, `react_component 'Post', @props`, `react_component :Post, @props`, or `react_component component_name, @props`) to options-style props before running tests. 4. Run your test suite and fix any app-specific breakages before merging. ## Legacy compatibility fixes that often make migration one-shot Older `react-rails` apps frequently need these additional fixes after the generator run: 1. Remove old UJS mounting from legacy packs (`app/javascript/packs/application.js` and related files). Remove patterns such as: ```js var componentRequireContext = require.context('components', true); var ReactRailsUJS = require('react_ujs'); ReactRailsUJS.useContext(componentRequireContext); ``` 2. If you are switching to React on Rails `server-bundle.js`, remove stale `app/javascript/packs/server_rendering.js` usage. 3. Update existing ERB helper calls from old positional props to options-style props: ```diff - <%= react_component 'Post', @props, prerender: true %> + <%= react_component('Post', { props: @props, prerender: true }) %> ``` 4. If server bundles are not being found, verify `config/initializers/react_on_rails.rb` setup: - On Shakapacker 9.0+, React on Rails usually auto-detects the output path from `private_output_path`. Leave this unset unless you intentionally need an override. - On older setups, you may need an explicit value: ```ruby config.server_bundle_output_path = "ssr-generated" ``` 5. If `spec/rails_helper.rb` gets a malformed merge after generator updates, keep a single valid `RSpec.configure do |config| ... end` block and include: ```ruby ReactOnRails::TestHelper.configure_rspec_to_compile_assets(config) ``` Published migration references, including older and Rails 7-era `react-rails` migrations, are listed in [Example Migrations](./example-migrations.md). In-progress migration PRs are tracked in the meta issue [#3125](https://github.com/shakacode/react_on_rails/issues/3125). ## Coexistence: keeping both gems installed during a staged migration Large apps often cannot swap every `react-rails` mount in a single PR. If you need `react-rails` and `react_on_rails` installed side-by-side while you migrate views incrementally, plan for the `react_component` helper collision **before** adding the gem. ### Why it collides Both gems ship a view helper named `react_component` that ends up available in Rails views: - `react-rails` (`React::Rails::ViewHelper`) takes positional arguments: `react_component(name, props, html_options)`. - `react_on_rails` (`ReactOnRailsHelper` → `ReactOnRails::Helper#react_component`) takes `react_component(name, options = {})` where props are nested under `options[:props]`. `react-rails` includes `React::Rails::ViewHelper` directly into `ActionView::Base` from its railtie. `react_on_rails` ships `ReactOnRailsHelper` as a normal Rails helper module, and under Rails' default `include_all_helpers` behavior that helper is pulled into the controller/view helper module that sits earlier in method lookup than `ActionView::Base`. In a standard Rails app, that means `ReactOnRailsHelper#react_component` wins once the gem is present. This is a helper-precedence issue, not `app/helpers/` file order or gem-name alphabetics. If your app customizes helper loading, verify which helper owns `react_component` before relying on coexistence. Once you add `react_on_rails` to the `Gemfile`, every existing legacy call starts resolving to `ReactOnRails::Helper#react_component(name, options = {})`, which behaves differently depending on how many positional arguments you pass. As of Rails 7/8, Rails gives no boot-time warning in either case: - **Three or more positional arguments** — e.g. `react_component "command_bar/CommandBar", props, { camelize_props: false }` — raise `ArgumentError` at render time on the first request to any un-migrated view, because the new helper only takes two arguments. - **Two positional arguments** — e.g. `react_component "command_bar/CommandBar", props` — are silently accepted. The `props` hash is bound to `options`, but React on Rails reads props only from `options[:props]`, so the component renders with no props instead of failing loudly. This is the more dangerous case: un-migrated views do not error; they just lose their data. ### Detecting the collision quickly Before adding the gem, audit existing positional-style calls so you know what needs a shim or a same-PR migration. Pay particular attention to two-argument calls, which fail silently rather than raising: ```bash rg -n "react_component\\b" app/views app/components app/mailers app/helpers # or without ripgrep: grep -rEn "react_component\\b" app/views app/components app/mailers app/helpers ``` `app/helpers` catches view-helper wrappers that call `react_component` from Ruby rather than a template. Expand the path list further if you mount React from other locations (Phlex views, gem engines, etc.), or drop the path argument entirely to search the whole project and filter out false positives manually. Any call that passes props as the second positional argument (rather than `{ props: ... }`) will break as soon as `react_on_rails` is loaded — either by raising `ArgumentError` (3+ args) or by silently dropping props (2 args). ### Option A: migrate all call sites in the same PR (recommended) The cleanest path is to update every `react_component` call to the options-hash form in the same PR that adds the gem. See the syntax change under [Legacy compatibility fixes](#legacy-compatibility-fixes-that-often-make-migration-one-shot). After this, there is no collision to manage — the new helper is the only helper. ### Option B: preserve the legacy helper and use an explicit alias If a single-PR migration is impractical, you can keep `react-rails`'s `react_component` semantics for un-migrated views and introduce a separate helper name for migrated mounts. Define the shim module directly in an initializer so it lives outside Zeitwerk's autoload paths. The module: 1. Prepends an override so legacy `react_component(...)` calls keep delegating to `React::Rails::ViewHelper`. 2. Exposes an explicit `react_on_rails_component(...)` alias for migrated mounts. > **Note:** this initializer was contributed by a community member migrating a production app. It is not covered by the `react_on_rails` test suite. Verify it works in a staging environment before relying on it in production. ```ruby # config/initializers/react_on_rails_coexistence.rb module ReactOnRailsCoexistence # Legacy react-rails semantics for un-migrated views. # Delegates to React::Rails::ViewHelper#react_component. Accepts and # forwards a block, which react-rails uses for mount-tag content. module LegacyReactComponent def react_component(name, props = {}, options = {}, &block) # Standard Rails views have the react-rails helper support methods. # Engines, ViewComponent, mailers, and other restricted contexts may not. # See Known Limitations below. React::Rails::ViewHelper.instance_method(:react_component) .bind_call(self, name, props, options, &block) end end # Explicit alias for migrated mounts. # Uses the React on Rails options-hash shape: (name, options = {}). # Fetches from ReactOnRails::Helper directly (not ReactOnRailsHelper) so # migrated mounts always call the React on Rails implementation rather than # the prepended LegacyReactComponent override. def react_on_rails_component(name, options = {}) ReactOnRails::Helper.instance_method(:react_component) .bind_call(self, name, options) end end Rails.application.config.to_prepare do # Safe to re-run on every reload: Ruby skips the insertion when the module # is already in the ancestor chain, so duplicates never accumulate. ReactOnRailsHelper.prepend(ReactOnRailsCoexistence::LegacyReactComponent) ActionView::Base.include(ReactOnRailsCoexistence) end ``` Defining the module inline in the initializer avoids a subtle issue: files under `app/helpers/` are on Zeitwerk's autoload paths, and `require`-ing such a file from an initializer can confuse Zeitwerk's bookkeeping in production eager-load mode. Keeping the module in `config/initializers/` sidesteps that entirely. Use `react_on_rails_component(...)` in new or migrated views: ```erb <%= react_on_rails_component("CommandBar", props: { title: "Hi" }, prerender: true) %> ``` Leave existing `react_component(...)` calls untouched until you are ready to migrate them. When every call site has been converted, update each migrated call site from `react_on_rails_component(...)` back to `react_component(...)` and delete `config/initializers/react_on_rails_coexistence.rb`. A project-wide find-and-replace over `react_on_rails_component` makes the final pass quick. See [Known limitations of Option B](#known-limitations-of-option-b) below for the full cost of this approach. ### Known limitations of Option B - **Two project-wide renames.** Every migrated call site is renamed twice: `react_component` → `react_on_rails_component` while the shim is active, then `react_on_rails_component` → `react_component` once the shim is removed. On a large app this can equal or exceed the effort of migrating call sites in a single PR (Option A). Factor this in before choosing Option B. - This is a migration-only pattern. Carry the shim only as long as legacy calls remain, then remove it. - Edits to `config/initializers/react_on_rails_coexistence.rb` require a server restart in development, like any initializer. - **The shim is app-level and can hard-fail in restricted view contexts.** In gem-provided engines, Rails engines, ViewComponent, or Action Mailer views, the receiver may be missing helper methods used by `react-rails` or React on Rails. That means legacy `react_component(...)` calls and migrated `react_on_rails_component(...)` calls can both fail at render time even though the method name is visible. Explicitly include the needed helper module or add a context-local wrapper before using either helper in those contexts. - **Remove the initializer before (or at the same time as) removing `react-rails` from the `Gemfile`.** The shim's method body references `React::Rails::ViewHelper`, so once the gem is gone any request that still routes through the legacy delegate raises `NameError: uninitialized constant React::Rails::ViewHelper` at render time. Delete `config/initializers/react_on_rails_coexistence.rb` in the same commit that drops the gem. - Server rendering, Pro features, and auto-bundling all work through the explicit `react_on_rails_component` alias — the shim only forwards the default helper name back to `react-rails`. ## Practical checklist for Webpacker-era apps See [Preferred path for Webpacker-era apps](#preferred-path-for-webpacker-era-apps) above for the recommended staging. The concrete checklist follows. If your app looks like this: - `gem "webpacker"` in `Gemfile` - `react_ujs` in `package.json` - `app/javascript/packs/application.js` - `app/javascript/packs/server_rendering.js` then treat the migration as: 1. Move from `webpacker` to `shakapacker` in its own PR. 2. If the app is still on Rails 5.1, upgrade Rails to 5.2+ before adding current `react_on_rails`. 3. Remove `react_ujs`. 4. Run the React on Rails install generator. 5. Replace helper syntax and component registration. 6. Review `bin/dev`, `config/shakapacker.yml`, and webpack config diffs before committing. Current React on Rails does not support `gem "webpacker"`; Shakapacker is the recommended baseline. The install generator adds Shakapacker rather than enforcing a hard install-time block, and `react_on_rails doctor` flags Webpacker as a removed/breaking-change issue when it detects `config/webpacker.yml` or `bin/webpacker`. Migrate to Shakapacker first (step 1 above) when you can; use the [Legacy Webpacker / Webpack 4 migration shims](../building-features/rails-webpacker-react-integration-options.md#legacy-webpacker--webpack-4-migration-shims) only as a narrow temporary bridge when the bundler migration cannot happen first. ================================================================================ PAGE: https://reactonrails.com/docs/migrating/migrating-from-inertia-rails SOURCE: docs/oss/migrating/migrating-from-inertia-rails.md ================================================================================ # Migrate from Inertia Rails This guide is for Rails apps that currently use [Inertia Rails](https://inertia-rails.dev/) with React and are evaluating a move to React on Rails. It covers three things: 1. A concept-mapping table from Inertia idioms to their React on Rails equivalents. 2. A **verified** coexistence setup: both gems in one app, so you can migrate route by route instead of all at once. 3. An honest "when to stay on Inertia" section. For the "why" comparison (architecture, SSR, streaming, RSC tradeoffs), see [Comparing React on Rails to Alternatives](../getting-started/comparing-react-on-rails-to-alternatives.md#react-on-rails-vs-inertia-rails). This page is the "how." > **Scope note:** This is the v1 of the migration guide. A full step-by-step playbook (forms, shared state, SSR cutover, removing Inertia) is tracked in [#3899](https://github.com/shakacode/react_on_rails/issues/3899). Publishing a standalone worked-example repo for that playbook is tracked in [reactonrails.com#140](https://github.com/shakacode/reactonrails.com/issues/140). One mapping-table parity feature, the first-class `useForm`-style helper ([#3872](https://github.com/shakacode/react_on_rails/issues/3872)), **has shipped** as [`useRailsForm`](../building-features/forms.md). The opinionated routing/prefetch starter ([#3873](https://github.com/shakacode/react_on_rails/issues/3873)) is **not shipped yet** — check that issue for current status. The table gives you the current answer for each. ## Concept mapping | Inertia concept | React on Rails equivalent | Notes | | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `render inertia: 'Page', props: {...}` in a controller | A normal Rails view that calls [`react_component("Page", props: {...})`](../api-reference/view-helpers-api.md#react_component) (or [`react_component_hash`](../api-reference/view-helpers-api.md#react_component_hash) when SSR returns multiple regions — though for head tags on React 19, prefer [native metadata hoisting](../building-features/react-19-native-metadata.md) over `react_component_hash`) | Your controller stays a conventional Rails action rendering a view. Props are any JSON-serializable Ruby hash, same as Inertia page props. | | Page components resolved by name (`resolve:` in `createInertiaApp`) | Components registered with `ReactOnRails.register({ Page })`, or discovered automatically with [auto-bundling](../core-concepts/auto-bundling-file-system-based-automated-bundle-generation.md) | With auto-bundling you skip both manual registration and manual pack tags. | | `useForm` (form state, submit, errors, processing) | [`useRailsForm`](../building-features/forms.md) — a first-class `useForm`-style hook (`data`/`setData`, per-field `errors`, `processing`, `wasSuccessful`, submit verbs) that posts to a plain Rails controller, with automatic CSRF and `422` model-error mapping via the `ReactOnRails::Controller::FormResponders` concern. (Interim, still supported: `fetch` + [`ReactOnRails.authenticityHeaders()`](../api-reference/javascript-api.md).) | A near-direct port of Inertia's `useForm`. Shipped via [#3872](https://github.com/shakacode/react_on_rails/issues/3872); v1 is `fetch`-based. See [Forms and Mutations](../building-features/forms.md). | | `<Link>` (SPA navigation), `prefetch` | **Interim:** plain `<a>` full-page navigation between Rails routes, or client-side routing within a section via [React Router](../building-features/react-router.md) or [TanStack Router](../building-features/tanstack-router.md). **Planned:** an opinionated SSR-friendly routing + prefetch starter is tracked in [#3873](https://github.com/shakacode/react_on_rails/issues/3873) | React on Rails does not impose a router. Full-page navigation is also how you cross the Inertia↔React on Rails boundary during an incremental migration (verified below). | | Shared data (`inertia_share`) | [`railsContext`](../core-concepts/render-functions-and-railscontext.md) for request/app-wide context (extend it via [`config.rendering_extension`](../configuration/README.md#rendering_extension)), plus per-page props from your view | `railsContext` is only passed to [render functions](../core-concepts/render-functions-and-railscontext.md) — a plain registered component receives just its props, so register the page as a render function (or copy shared values into per-page props). There is no `usePage()` equivalent for nested components: pass shared values down via props/React Context from the render function, or use the Redux store. For shared _client state_ across multiple components on one page, there is also the [Redux store API](../api-reference/redux-store-api.md). | | Deferred / lazy / merge props | **OSS:** fetch from the component after mount (standard React data fetching). **Pro:** [async props with streaming SSR](../../pro/streaming-ssr.md) (`stream_react_component_with_async_props`) stream slow data into a server-rendered page; [RSC](../../pro/react-server-components/index.md) moves data fetching into server components | Inertia's deferred props resolve client-side after the page visit. Pro streaming starts HTML immediately and streams the slow parts — same goal, stronger SSR story. | | Partial reloads | Component-local data refetching (the component owns its data refresh; no protocol-level partial visit needed). With Pro RSC, navigation can refetch only the [RSC payload](../../pro/react-server-components/inside-client-components.md#client-side-navigation) instead of a full page | There is no direct protocol equivalent in React on Rails; data refresh is ordinary React, not a framework visit. | | SSR via the Inertia/Vite SSR server (sidecar Node process) | **OSS:** `react_component(..., prerender: true)` using [ExecJS server rendering](../core-concepts/react-server-rendering.md) — no separate process to deploy. **Pro:** the [Node renderer](../../pro/node-renderer.md) (dedicated Node process) and [streaming SSR](../../pro/streaming-ssr.md) | Inertia SSR is a single `renderToString` pass. ExecJS rendering (pooled JS contexts inside the Ruby process) is typically slower than a dedicated Node SSR process for large pages — measure before relying on it; the Pro Node renderer is the performance path. Pro can also stream (`renderToPipeableStream`) and supports RSC; see the comparison page for details. | | Persistent layouts (`Page.layout = ...`) | Ordinary React composition inside your registered component; the Rails layout (ERB) owns the document shell | During coexistence, both stacks share the same Rails layout conventions (see below). | | CSRF handling (Inertia's automatic XSRF cookie/axios integration) | Rails `csrf_meta_tags` + [`ReactOnRails.authenticityHeaders()`](../api-reference/javascript-api.md) on mutating requests | Standard Rails forms (`form_with`) also keep working — Rails owns the page. | ## Coexistence: run both gems during the migration (verified) The migration-enabling claim is that `inertia_rails` and `react_on_rails` can live in the same app while you move route by route. We verified this in a minimal scratch app (2026-06-11), with one page rendered by each stack and full-page navigation across the boundary in a real browser. **Verified versions:** | Component | Version | | ------------------------------------------- | ----------------------------------------- | | Ruby / Rails | 3.4.6 / 8.1.3 | | `react_on_rails` gem / `react-on-rails` npm | 16.6.0 / 16.6.0 | | `inertia_rails` gem | 3.21.2 | | `@inertiajs/react` npm | 2.3.26 (see version-pairing gotcha below) | | `shakapacker` gem / npm | 9.7.0 / 9.7.0 | | React / ReactDOM | 19.2.7 | **The setup:** - One Gemfile with both gems: `gem "react_on_rails"`, `gem "inertia_rails"`, `gem "shakapacker"`. - One Shakapacker install compiles packs for both stacks. The Inertia entry point is just another pack (`createInertiaApp` bootstrapping `@inertiajs/react`); the React on Rails entry point registers components with `ReactOnRails.register`. - An Inertia route: a controller action with `render inertia: "InertiaPage", props: {...}`, using a Rails layout that loads the Inertia pack. - A React on Rails route: a conventional controller action whose ERB view calls `react_component("HelloFromReactOnRails", props: {...}, prerender: false)`, using a layout that loads the React on Rails pack. - Each page contains a plain `<a>` link to the other. **What was verified (in a real browser, via Playwright):** - Both gems boot together; no initializer or engine conflicts. - The React on Rails page mounts client-side with the props passed from the view helper. - The Inertia page mounts client-side from the `data-page` payload emitted by `inertia_rails`, with the props passed from the controller. - Full-page navigation across the boundary works in both directions (React on Rails page → Inertia page → back). - Both layouts emit `csrf_meta_tags` from the same Rails session — the two stacks share Rails session and CSRF infrastructure. **Gotchas found during verification:** - **Pin `@inertiajs/react` to the major version your `inertia_rails` gem supports.** With `inertia_rails` 3.21.2, `@inertiajs/react` 3.4.0 failed to boot (`TypeError: Cannot read properties of null (reading 'component')` inside `createInertiaApp`); pinning to `@inertiajs/react` ^2 (2.3.26) worked. If your existing app already runs, keep its existing client version during the migration. - This was verified with full-page (`<a>`) navigation across the boundary. Inertia's `<Link>` SPA visits only work between Inertia pages; links that leave the Inertia section of the app should be regular anchors. - The scratch app used webpack-bundled Inertia via Shakapacker. If your Inertia app uses Vite, you can run Vite and Shakapacker side by side during the migration, but that combination was **not** part of this verification. **The resulting migration strategy** is route-by-route: keep `render inertia:` actions as they are, and convert one low-risk route at a time to a conventional Rails view + `react_component`. Page components are plain React in both stacks, so most component code moves unchanged — what changes is how props arrive (view helper instead of the Inertia page object) and how navigation/forms talk to Rails (see the mapping table). ## Estimate the migration before coding Use the coexistence setup above as the default sizing model. A big-bang rewrite is usually harder to estimate because it mixes framework migration with product and routing changes. First count the routes and app surfaces that must move, then apply the rubric below. | App surface to count | Typical effort after dependencies install cleanly | What changes the estimate | | ------------------------------------------ | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Initial React on Rails + Shakapacker setup | 0.5-1 engineer-day | Older Ruby/Node locks, a custom package root, or a non-standard asset pipeline can push this higher. | | Simple display page | 0.25-0.5 day per route | Mostly moving `render inertia:` props into an ERB view that calls `react_component`. | | Form page with validation | 0.5-1 day per basic form; more for Inertia helpers | Basic forms map to [`useRailsForm`](../building-features/forms.md). Budget separate replacement work for uploads, progress bars, transforms, `recentlySuccessful`, or other Inertia-specific `useForm` conveniences. | | Shared data / `usePage()` surface | 0.5-1.5 days per shared surface | App-wide user, flash, locale, or permissions data needs a render-function boundary, props, React Context, or Redux instead of an implicit page object. | | Inertia navigation polish | 1-3 days per app area | `<Link>`, prefetch, scroll restoration, redirect flash conventions, and visit lifecycle hooks need explicit routing or full-page navigation decisions. | | Deferred, lazy, merged, or partial props | 0.5-2 days per data surface | Simple cases become component-local fetches. Complex cases may justify Pro streaming SSR or RSC instead of rebuilding Inertia's protocol behavior one-for-one. | | SSR cutover | 1-3 days for the first representative page, then less | ExecJS may be fine for small pages; performance-sensitive SSR should be measured and may require the Pro Node renderer, streaming SSR, or a targeted RSC design. | Examples: - **Small CRUD app:** 5 simple pages, 2 ordinary forms, no SSR, no heavy `usePage()` usage: roughly 3-6 engineer-days. - **Moderate Inertia app:** 20 pages, 5 forms, one shared user/flash surface, no deferred props: roughly 9-18 engineer-days with route-by-route coexistence. - **SEO/SSR migration:** 10 important pages plus SSR parity and performance validation: roughly 5-10 engineer-days before visual QA, depending on whether ExecJS is enough or the Pro Node renderer is required. These are planning ranges, not promises. Add separate time for visual QA, product copy changes, route redesign, or any cleanup you choose to do while touching the pages. ## Migration decision table | Current app signal | Prefer staying on Inertia when... | Prefer moving to React on Rails when... | | ----------------------------------------- | ----------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Mostly CRUD pages, no SEO or SSR pressure | Client-rendered pages are already acceptable and the migration would only change integration style. | You need Rails-owned views or incremental React islands inside existing ERB pages. | | Forms are the main interaction surface | Your app depends on Inertia form niceties not yet covered by `useRailsForm`, such as upload progress. | Basic model validation, `422` handling, and CSRF-aware `fetch` semantics cover most flows. | | Navigation depends on Inertia visits | `<Link>`, prefetch, scroll restoration, and visit lifecycle behavior are central to the product. | Full-page route boundaries are acceptable, or you want to choose React Router / TanStack Router explicitly for client-routed sections. | | Shared data relies heavily on `usePage()` | Replacing implicit page context would touch too many nested components for the expected benefit. | You already want explicit props, React Context, Redux, or request-aware `railsContext` boundaries. | | SEO or basic SSR performance | These are not priorities for the app. | OSS SSR/SEO needs justify a React on Rails migration. If streaming SSR, RSC, fragment caching, or the Pro Node renderer are the drivers, confirm the required Pro feature set and size that slice separately before committing the whole app. | ## When to stay on Inertia React on Rails is not the right answer for every Inertia app. Staying put is reasonable when: - **You're a small CRUD app with no SSR, SEO, or streaming needs.** Inertia's client-rendered model with controller-provided props is a great fit there, and the migration buys you little. - **Inertia-specific form features beyond v1.** React on Rails now ships [`useRailsForm`](../building-features/forms.md), a close `useForm` equivalent, so basic form ergonomics are no longer a reason to stay. But v1 is `fetch`-based and defers a few Inertia niceties (file-upload `progress`, `transform`, `recentlySuccessful`); if your app leans on those, check the [Forms and Mutations](../building-features/forms.md) guide for current coverage first. - **You rely heavily on Inertia's navigation conveniences** — `<Link>` visits, prefetching, scroll restoration, and flash-message-over-redirect conventions. React on Rails leaves routing choices to you; until [#3873](https://github.com/shakacode/react_on_rails/issues/3873) ships an opinionated starter, replicating that polish is your code. - **You use Inertia's multi-framework support** (Vue or Svelte pages). React on Rails is React-only. The reasons to move are the ones Inertia architecturally can't offer: streaming SSR, React Server Components, component-level code splitting with SSR, fragment caching, and incremental React adoption inside existing ERB views — see the [comparison page](../getting-started/comparing-react-on-rails-to-alternatives.md#react-on-rails-vs-inertia-rails) for that side of the decision. ================================================================================ PAGE: https://reactonrails.com/docs/migrating/migrating-from-vite-rails SOURCE: docs/oss/migrating/migrating-from-vite-rails.md ================================================================================ # Migrate from `vite_rails` This guide is for Rails apps that currently use `vite_rails` with React and want to move to React on Rails. If you want repo-shaped references before touching your own app, start with [Example Migrations](./example-migrations.md) and then come back here for the mechanics. A public worked example repo is planned as a separate follow-up in [reactonrails.com#140](https://github.com/shakacode/reactonrails.com/issues/140); use the existing example-migration guide until that repo exists. ## When this migration makes sense React on Rails is a better fit when you want one or more of these: - Rails view helpers like `react_component` - server-side rendering from Rails - a tighter Rails-to-React integration story - React on Rails Pro features like streaming SSR or React Server Components If your app is already happy with a Vite-only client-rendered setup, this migration is optional. ## Two different starting points Not all `vite_rails` + React apps are the same shape, and the migration effort differs for each: - **Rails-owned island mounts.** Rails renders real ERB views and mounts one or more React components inside them. The migration is incremental: you can cut over one page (or one mount) at a time. - **Client-routed SPA shells.** Rails serves a minimal layout and a single `<div id="app">`, and a client-side router (React Router / TanStack Router) owns everything after the first render. You have two reasonable migration shapes here: 1. **Keep the SPA shape.** Render the top-level SPA component from a single ERB view using `react_component` (or `react_component_hash` when you need SSR that returns multiple regions such as `componentHtml`, `title`, and other head tags). One React on Rails call mounts the whole app — this is the pattern used by the largest React on Rails Pro deployment in production, Popmenu (for example, [110grill.com](https://www.110grill.com/) and other Popmenu-powered restaurant sites), where the entire app is a single top-level component call. 2. **Break the SPA into island mounts** by moving Rails back to being the view-owner. This is a real product decision and should not be bundled with the bundler/integration change. For most teams, the **Keep the SPA shape** path is the fastest first step: you're swapping Vite's build integration for Shakapacker, not re-architecting the app. The main friction is usually not the Rails-side `react_component` call — it's the Vite-specific runtime behavior (`import.meta.env`, `import.meta.glob`, Vite plugins with no direct Shakapacker analogue) that the client code may depend on. See [Replace Vite-specific asset and env usage](#5-replace-vite-specific-asset-and-env-usage) for the concrete replacements. ## Estimate the migration before coding Use the smallest shape that proves parity. For Rails-owned island apps, that usually means one page or mount at a time. For SPA-shell apps, it often means one top-level `react_component` call first, with any island split treated as a later product decision. | App surface to count | Typical effort after dependencies install cleanly | What changes the estimate | | ------------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Initial React on Rails + Shakapacker setup | 0.5-1 engineer-day | Older lockfiles, custom `client/` package roots, or existing webpack config can add setup time. | | Rails-owned island mount | 0.25-0.5 day per mount | Most work is moving the mount call from a Vite entrypoint into an ERB `react_component` call and checking props/hydration. | | Top-level client-routed SPA shell | 1-3 days | Keep the SPA shape first. Add time if the shell depends on Vite-only env handling, asset paths, or plugin behavior during boot. | | Vite layout/helper cleanup | 0.5-1 day per layout family | More layouts, engines, or custom helper wrappers increase search-and-replace plus QA time. | | `import.meta.env` / `vite_asset_path` usage | 0.25-1 day per usage pattern | Rails-passed props are usually simple. Treat client env injection as a security review: only publish values that are safe in browser bundles, and keep server-only secrets out of webpack definitions. | | `import.meta.glob` or route auto-discovery | 0.5-2 days per pattern | `require.context` differs in key shape and sync/lazy behavior, so route/module registries need focused tests. | | Vite plugins with no Shakapacker equivalent | 1-3 days per plugin | Spike these before committing the full migration; a plugin replacement can be the real schedule driver. | | SSR or Pro feature adoption | 2-5 days for the first representative page | Add renderer setup, asset/CSS parity checks, and performance validation for ExecJS vs the Pro Node renderer; size streaming SSR/RSC separately from the bundler migration. | Examples: - **Rails-owned island app:** 8 mounts, two layouts, no Vite-only plugins: roughly 4-7 engineer-days. - **SPA shell with light Vite usage:** one top-level app, `import.meta.env`, a few asset-path replacements: roughly 3-7 engineer-days. - **Vite-heavy app:** custom plugins plus `import.meta.glob` route discovery: run a 1-2 day spike first, then estimate from the plugin and module-discovery replacements. These ranges exclude visual QA, product redesign, and optional work to split a SPA into islands. Keep those as separate line items so the bundler/integration migration stays measurable. ## Migration decision table | App signal | Stay on `vite_rails` when... | Move to React on Rails when... | | ----------------------- | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | App shape | The app is a Vite-powered SPA and Rails only serves the shell. | Rails should own page rendering, route-level props, or several React islands inside existing ERB views. | | Rendering requirements | Client-side rendering already meets SEO and performance needs. | You need SSR from Rails, a path to streaming SSR, or React Server Components. | | Build workflow | Vite plugins, `import.meta.glob`, or Vite's dev server are central to your workflow. | You want to consolidate on Shakapacker / webpack semantics or remove a separate Vite build path from Rails deployment. | | Framework feature needs | The current app has no bundler pain and no React on Rails Pro feature needs. | You need React on Rails helpers, Rails request context, Pro Node rendering, streaming SSR, or RSC as app requirements. | | Product scope | The migration would also require a product rewrite or router redesign you do not want. | You can keep the current product shape and migrate route-by-route or as one top-level SPA mount first. | ## Preflight Before you start, make sure the current app still installs cleanly on the Ruby and Node versions you plan to use for the migration. - If `bundle install` fails on older native gems such as `pg`, `nio4r`, or `msgpack`, refresh those gems or use the Ruby version already pinned by the app before introducing React on Rails. - If the app has an older Bundler-era lockfile, refresh that lockfile first. - Commit or stash your current work so the generator diff is easier to review. Then inventory the Vite-specific pieces in your app: - layout helpers like `vite_client_tag`, `vite_react_refresh_tag`, `vite_stylesheet_tag`, `vite_typescript_tag`, and `vite_asset_path` - `app/frontend/entrypoints/*` - `vite.config.ts` - `config/vite.rb` and `config/vite.json` - dev scripts like `bin/vite`, `bin/live`, or a `Procfile.dev` entry that runs Vite - JavaScript that depends on `import.meta.env` Expect this migration to touch both Ruby and JavaScript entrypoints. ## Recommended migration strategy Do the migration in a branch and keep the Vite setup working until the new React on Rails path is rendering the same screens. For anything beyond a tiny app, prefer a route-by-route cutover instead of a big-bang rewrite. If the app uses `vite_rails` plus a custom Rails-side React wrapper, the first credible PR may be maintainability-first rather than a full Vite removal. In that case: 1. Replace one helper-backed component or boundary with React on Rails first. 2. Keep Vite in place for the rest of the app until the narrow slice has parity. 3. Treat Vite removal as a later step, not as the proof point itself. ## 1. Add React on Rails and Shakapacker ```bash bundle add shakapacker --strict bundle add react_on_rails --strict bundle exec rails generate react_on_rails:install ``` The generator adds the React on Rails initializer, `bin/dev`, Shakapacker config, example routes, and the server bundle entrypoint. ### Nested `client/` package roots Some legacy Rails apps keep `package.json`, lockfiles, `node_modules`, and the webpack config under `client/`. You can keep that layout during an incremental migration instead of moving every JavaScript file to the Rails root in the first PR. First, point React on Rails diagnostics at the real package root: ```ruby # config/initializers/react_on_rails.rb config.node_modules_location = "client" ``` Then keep root-level binstubs and config files as thin wrappers so Rails, Shakapacker, and CI still have the paths they expect: ```bash #!/usr/bin/env bash # bin/shakapacker - create this file, then make it executable: # chmod +x bin/shakapacker # set -eu: exit immediately on any error (-e) or reference to an unset variable (-u). # exec then propagates shakapacker's exit code directly to the caller. set -eu cd "$(dirname "$0")/.." JS_PACKAGE_ROOT=client # Match config.node_modules_location; change this if you use frontend/, app/javascript/, etc. exec "./${JS_PACKAGE_ROOT}/node_modules/.bin/shakapacker" "$@" ``` ```js // config/webpack/webpack.config.js // "../../" goes from config/webpack/ back to the Rails root, then into client/. module.exports = require('../../client/config/webpack/webpack.config.js'); ``` ```text # Procfile.dev web: bin/rails server js: bin/shakapacker --watch --mode development ``` Use the same pattern for any static-assets Procfile or custom `bin/dev` launcher: keep the Rails-facing command at the repo root, but delegate the actual JavaScript executable to the configured package root's `node_modules/.bin`. Once the migration is stable, you can decide separately whether moving the package root to the Rails root is worth the churn. ## 2. Replace Vite layout tags A typical Vite layout looks like this: ```erb <%= vite_client_tag %> <%= vite_react_refresh_tag %> <%= vite_stylesheet_tag "styles.scss" %> <%= vite_typescript_tag "application" %> ``` React on Rails + Shakapacker layouts use pack tags instead: ```erb <%= stylesheet_pack_tag %> <%= javascript_pack_tag %> ``` These empty pack tags are the default for React on Rails auto-bundling — React on Rails injects component-specific bundles per page. If you use a manual entrypoint instead (non-auto-bundling), pass the pack name explicitly, e.g. `javascript_pack_tag "application"`. ## 3. Move frontend code into the React on Rails structure A common Vite layout is: ```text app/frontend/ components/ entrypoints/ styles/ ``` For React on Rails, move the code into `app/javascript/`. A good target is: ```text app/javascript/ packs/ src/ ``` For auto-bundling, move page-level components into a `ror_components` directory, for example: ```text app/javascript/src/Hero/ror_components/Hero.client.jsx ``` ## 4. Replace client bootstraps with Rails view rendering Vite apps often mount React manually from an entrypoint: ```js createRoot(document.getElementById('hero')).render(<Hero />); ``` With React on Rails, render the component from the Rails view instead: ```erb <%= react_component("Hero", props: { title: "Welcome" }, auto_load_bundle: true) %> ``` This is the key mental model shift: Rails decides where the component mounts, and React on Rails handles registration and hydration. ## 5. Replace Vite-specific asset and env usage ### `vite_asset_path` If your ERB templates use `vite_asset_path`, convert those assets to one of these patterns: - keep them as normal Rails static assets - import them from JavaScript so Shakapacker bundles them - move them into a component-level asset flow that React on Rails already understands ### `import.meta.env` Vite-specific `import.meta.env` usage needs to be replaced. In a React on Rails app, prefer: - Rails-passed props (most reliable for both client and server rendering) - `railsContext` for request-aware values - `process.env` in server-rendered bundles (available natively in Node); for client bundles, values must be injected via webpack's `DefinePlugin` or `EnvironmentPlugin` ### `import.meta.glob` `import.meta.glob` has no direct Webpack equivalent. Replace it with [`require.context`](https://webpack.js.org/guides/dependency-management/#requirecontext): - the glob-pattern syntax differs (Webpack uses a regex argument, not a glob string) - lazy/eager behavior is selected via a `mode` argument (`'sync'`, `'lazy'`, `'lazy-once'`, `'eager'`, `'weak'`) rather than the per-call options `import.meta.glob` exposes - the returned context function requires explicit `.keys()` + key lookup, not the object-map shape `import.meta.glob` returns A minimal before/after — note two semantic mismatches that bite during migration: 1. **Key paths differ.** Vite returns paths relative to the _calling module_ (`'./dir/foo.js'`); `require.context` returns paths relative to the _context directory_ (`'./foo.js'`). Code that derives names from keys (routing, registration, etc.) needs to account for this. 2. **Sync vs async.** `import.meta.glob` is lazy by default — values are `() => import(...)` returning a Promise. The default `require.context(dir, recursive, regex)` (no 4th argument) is synchronous, so `ctx(key)` returns the module directly. For the lazy case, pass `'lazy'` as the 4th argument so `ctx(key)` returns a `Promise<Module>` (see the lazy example below). Eager / synchronous case: ```js // Vite (eager) const modules = import.meta.glob('./dir/**/*.js', { eager: true }); // { './dir/foo.js': <module>, ... } ← keys relative to current file // Webpack (Shakapacker) — synchronous equivalent const ctx = require.context('./dir', true, /\.js$/); // ctx.keys() → ['./foo.js', ...] ← keys relative to context dir, NOT './dir/foo.js' // ctx('./foo.js') → the module (synchronous) ``` Lazy (default Vite) case — pass `'lazy'` as the 4th `require.context` argument so `ctx(key)` returns a `Promise<Module>`: ```js // Vite (lazy, the default) const modules = import.meta.glob('./dir/**/*.js'); // { './dir/foo.js': () => import('./dir/foo.js'), ... } // Webpack (Shakapacker) — lazy equivalent const ctx = require.context('./dir', true, /\.js$/, 'lazy'); // ctx.keys() → ['./foo.js', ...] ← keys relative to context dir, NOT './dir/foo.js' // ctx(key) now returns Promise<Module>, matching Vite's lazy semantics const lazyModules = Object.fromEntries(ctx.keys().map((key) => [key, () => ctx(key)])); ``` ## 6. Replace the development workflow Vite apps usually have a dev command like: ```text vite: bin/vite dev web: bin/rails s ``` React on Rails uses the generated `bin/dev` flow with Rails plus the Shakapacker watcher. After migration: ```bash bin/rails db:prepare bin/dev ``` ## 7. Remove Vite once parity is confirmed After the new React on Rails entrypoints are working, remove: - `vite_rails` and related Vite gems - `vite.config.ts` - `config/vite.rb` - `config/vite.json` - `bin/vite` and Vite-only Procfile entries - unused `app/frontend/entrypoints/*` Do this only after the Rails views are using React on Rails helpers and the app no longer depends on Vite-specific helpers. ## Practical example mapping For a Vite app with: - `app/frontend/components/Hero.jsx` - `app/frontend/entrypoints/application.ts` - `<div id="hero"></div>` in ERB one reasonable React on Rails target is: - `app/javascript/src/Hero/ror_components/Hero.client.jsx` - `app/views/...` uses `<%= react_component("Hero", ..., auto_load_bundle: true) %>` - generated `server-bundle.js` remains available if you later add SSR ## What usually stays the same - your React components - most of your CSS - Rails controllers and routes - Turbo usage, if your app already uses it The migration is mostly about asset/build integration, mounting strategy, and optional SSR capability. For additional real-world migration references and active public PRs, see [Example Migrations](./example-migrations.md). ================================================================================ PAGE: https://reactonrails.com/docs/migrating/migrating-from-webpack-to-rspack SOURCE: docs/oss/migrating/migrating-from-webpack-to-rspack.md ================================================================================ # Migrating from Webpack to Rspack This guide documents the process of migrating from Webpack to Rspack using Shakapacker 9+. Rspack is a high-performance bundler written in Rust that provides significantly faster builds (~20x improvement) while maintaining Webpack API compatibility. ## Prerequisites - Shakapacker 9.0+ (Rspack support was added in 9.0) - Node.js 20+ - React on Rails 13+ ## Quick Start For new projects or simple migrations, the generator handles most of the setup: ```bash # Generate with Rspack from scratch rails generate react_on_rails:install --rspack # Or switch an existing app bin/switch-bundler rspack ``` For complex projects with SSR, CSS Modules, or custom configurations, continue reading for important considerations. ## Breaking Changes in Shakapacker 9 ### CSS Modules: Named vs Default Exports **This is the most critical breaking change.** Shakapacker 9 changed the default CSS Modules configuration from default exports to named exports (`namedExport: true`). **Symptoms:** - CSS modules returning `undefined` - SSR errors: `Cannot read properties of undefined (reading 'className')` - Build warnings: `export 'default' (imported as 'css') was not found` **Affected code pattern:** ```javascript // This pattern breaks with Shakapacker 9 defaults import css from './Component.module.scss'; console.log(css.myClass); // undefined! ``` **Solution:** Configure CSS loader to use default exports in your webpack configuration: ```javascript // config/webpack/commonWebpackConfig.js const { generateWebpackConfig, merge } = require('shakapacker'); const commonWebpackConfig = () => { const baseWebpackConfig = generateWebpackConfig(); // Fix CSS modules to use default exports for backward compatibility baseWebpackConfig.module.rules.forEach((rule) => { if (rule.use && Array.isArray(rule.use)) { const cssLoader = rule.use.find((loader) => { const loaderName = typeof loader === 'string' ? loader : loader?.loader; return loaderName?.includes('css-loader'); }); if (cssLoader?.options?.modules) { cssLoader.options.modules.namedExport = false; cssLoader.options.modules.exportLocalsConvention = 'camelCase'; } } }); return baseWebpackConfig; }; module.exports = commonWebpackConfig; ``` **Key insight:** This configuration must be inside the function so it applies to a fresh config each time. ## Rspack-Specific Configuration ### Bundler Auto-Detection Pattern Use conditional logic to support both Webpack and Rspack in the same configuration files: ```javascript // config/webpack/commonWebpackConfig.js const { config } = require('shakapacker'); // Auto-detect bundler from shakapacker config const bundler = config.assets_bundler === 'rspack' ? require('@rspack/core') : require('webpack'); // Use for plugins that need the bundler reference clientConfig.plugins.push( new bundler.ProvidePlugin({ /* ... */ }), ); serverConfig.plugins.unshift(new bundler.optimize.LimitChunkCountPlugin({ maxChunks: 1 })); ``` **Benefits:** - Single codebase for both bundlers - Easy to compare configurations - Clear visibility of bundler-specific differences ### Server Bundle: CSS Extract Plugin Filtering Rspack uses a different CSS extract loader path than Webpack. Server-side rendering configs that filter out CSS extraction must handle both: ```javascript // config/webpack/serverWebpackConfig.js const configureServer = (serverWebpackConfig) => { serverWebpackConfig.module.rules.forEach((rule) => { if (rule.use && Array.isArray(rule.use)) { // Filter out CSS extraction loaders for SSR rule.use = rule.use.filter((item) => { let testValue; if (typeof item === 'string') { testValue = item; } else if (typeof item.loader === 'string') { testValue = item.loader; } // Handle both Webpack and Rspack CSS extract loaders return !( testValue?.match(/mini-css-extract-plugin/) || testValue?.includes('cssExtractLoader') || // Rspack uses this path testValue === 'style-loader' ); }); } }); }; ``` **Why this matters:** Rspack uses `@rspack/core/dist/cssExtractLoader.js` instead of Webpack's `mini-css-extract-plugin`. Without this fix, CSS extraction remains in the server bundle, causing intermittent SSR failures. ### CSS Modules with SSR: Stable Class Names **If you use `[contenthash]` in your `localIdentName` for CSS modules, class names can silently diverge between client and server builds with Rspack.** Pages load but all CSS module styles are broken. This only affects production builds — development with HMR works fine because `style-loader` injects CSS inline. The root cause is that `[contenthash]` is computed from processed CSS content, which differs between client and server builds due to different loader chains (`exportOnlyLocals: true` on server), different plugins (`CssExtractRspackPlugin` on client only), and different optimization passes. **Solution:** Replace `[contenthash]` with a custom `getLocalIdent` function that derives class names from stable inputs (file path, query string, and class name): ```javascript // config/webpack/getLocalIdent.js const crypto = require('crypto'); const path = require('path'); const getLocalIdent = (context, _localIdentName, localName) => { const resourcePath = context.resourcePath; const resourceQuery = context.resourceQuery || ''; // needed for CSS-in-JS virtual modules; safe no-op otherwise // Prefer process.cwd() so this stays correct across custom/monorepo layouts. const projectRoot = process.cwd(); // Alternative if process.cwd() isn't reliable in your setup: // const projectRoot = path.resolve(__dirname, '../..'); // adjust depth as needed const relativePath = path.relative(projectRoot, resourcePath); const hash = crypto .createHash('sha256') .update(relativePath + '\0' + resourceQuery + '\0' + localName) .digest('base64url') .slice(0, 8); const basename = path.basename(resourcePath); const name = basename .replace(/\.(module\.)?(scss|sass|css|less|styl|tsx?|jsx?)$/, '') .replace(/-styles$/, ''); return `${name}-${localName}_${hash}`; }; module.exports = getLocalIdent; ``` For third-party CSS modules, `relativePath` may include `node_modules/` segments in the hash input. That's expected and stable; the visible class name prefix still comes from `path.basename(resourcePath)`. Then use it in your `commonWebpackConfig.js` where you configure CSS modules: ```javascript const getLocalIdent = require('./getLocalIdent'); // In the CSS modules configuration loop: if (cssLoader?.options?.modules) { cssLoader.options.modules.namedExport = false; cssLoader.options.modules.exportLocalsConvention = 'camelCase'; cssLoader.options.modules.getLocalIdent = getLocalIdent; // Stable class names across builds } ``` Because `getLocalIdent` uses stable inputs (file path, query string, and class name) rather than processed CSS content, the same class name is produced in both client and server builds regardless of bundler internals. The same function must be used in both builds so server-rendered HTML class names match client CSS selectors. > **Note — CSS-in-JS virtual modules (astroturf, etc.):** The `resourceQuery` line in `getLocalIdent` above is a no-op for regular `.module.scss` files. It exists for CSS-in-JS tools that create virtual CSS modules via webpack's `!=!` matchResource syntax. In rspack, `context.resourcePath` points to the source file rather than the virtual path, so without `resourceQuery` in the hash, all virtual modules from the same file would collide. See the [troubleshooting entry](#css-in-js-styled-components-all-share-the-same-class-name) for details. ### Server Bundle: Preserve CSS Modules Configuration When configuring SSR, merge CSS modules options instead of replacing them: ```javascript // ❌ Wrong - overwrites namedExport setting if (cssLoader && cssLoader.options) { cssLoader.options.modules = { exportOnlyLocals: true }; } // ✅ Correct - preserves existing settings if (cssLoader && cssLoader.options && cssLoader.options.modules) { cssLoader.options.modules = { ...cssLoader.options.modules, // Preserve namedExport: false exportOnlyLocals: true, }; } ``` ## React Runtime Configuration ### SWC React Runtime for SSR If using SWC (common with Rspack), you may need to use the classic React runtime for SSR compatibility: ```javascript // config/swc.config.js const customConfig = { options: { jsc: { transform: { react: { runtime: 'classic', // Use 'classic' instead of 'automatic' for SSR refresh: env.isDevelopment && env.runningWebpackDevServer, }, }, }, }, }; ``` **Symptom:** SSR error about invalid `renderToString` call or function signature detection issues. ## Additional Configuration ### ReScript Support If using ReScript, add `.bs.js` to resolve extensions: ```javascript // config/webpack/commonWebpackConfig.js const commonOptions = { resolve: { extensions: ['.css', '.ts', '.tsx', '.bs.js'], }, }; ``` ### Development Hot Reloading Different plugins are required for hot reloading: ```javascript // config/webpack/development.js const { config } = require('shakapacker'); if (config.assets_bundler === 'rspack') { const ReactRefreshPlugin = require('@rspack/plugin-react-refresh'); clientWebpackConfig.plugins.push(new ReactRefreshPlugin()); } else { const ReactRefreshWebpackPlugin = require('@pmmmwh/react-refresh-webpack-plugin'); clientWebpackConfig.plugins.push(new ReactRefreshWebpackPlugin()); } ``` ## Shakapacker Configuration Enable Rspack in `config/shakapacker.yml`: ```yaml default: &default assets_bundler: 'rspack' # or 'webpack' webpack_loader: 'swc' # Rspack works best with SWC ``` ## Troubleshooting ### CSS Modules Return `undefined` **Symptoms:** - `css.className` is `undefined` - SSR crashes with property access errors - Works in development but fails in SSR **Solutions:** 1. Configure `namedExport: false` (see Breaking Changes section) 2. Ensure server config preserves CSS modules settings 3. Filter Rspack's `cssExtractLoader` from server bundle ### CSS Module Styles Broken in Production (SSR) **Symptoms:** - All CSS module styles missing in production - Class names in server-rendered HTML don't match CSS selectors - Works in development but breaks in production builds - No errors — just silently broken styles **Cause:** `[contenthash]` in `localIdentName` produces different hashes in client and server builds with Rspack. **Solution:** Use a custom `getLocalIdent` function instead of `[contenthash]`. See the [CSS Modules with SSR](#css-modules-with-ssr-stable-class-names) section above. ### CSS-in-JS Styled Components All Share the Same Class Name **Symptoms:** - Multiple astroturf (or similar CSS-in-JS) styled components in the same file all get identical CSS class names - Styles look correct in development but are broken in production - Only one component's styles survive; others are overwritten **Cause:** Rspack sets `context.resourcePath` to the actual source file instead of the virtual matchResource path. All virtual CSS modules from the same source file produce the same hash. **Solution:** Include `context.resourceQuery` in the `getLocalIdent` hash. See the [`getLocalIdent` implementation](#css-modules-with-ssr-stable-class-names) above, which already includes `resourceQuery` for this reason. ### Intermittent SSR Failures **Cause:** Incomplete CSS extraction filtering in server config. **Solution:** Update the CSS extract loader filter to include `cssExtractLoader` for Rspack (see Server Bundle section). ### Module Resolution Errors **Symptom:** `Module not found: Can't resolve './file.bs.js'` **Solution:** Add the file extension to webpack's resolve.extensions configuration. ### UMD Libraries Behave Differently Under Rspack's Module Interop **Symptoms:** - `noConflict()` or other methods called on an import result return `undefined` or throw - Libraries that coexist via `noConflict()` (e.g., lodash + underscore) interfere with each other **Cause:** Rspack's ES module interop wraps CommonJS exports differently than Webpack, so the import result may not have the methods you expect. Switching to `window.*` access can also be wrong if loaders like `imports-loader?define=>false` prevent the library from setting globals in the first place. **Solution:** Audit any `noConflict()` calls or UMD workarounds. Check whether your loader chain already prevents the conflict, and remove the workaround if so. Verify behavior by testing in both bundlers. ### Modern Entry Points Crash on Missing Globals **Symptoms:** - `Cannot use 'in' operator to search for 'X' in undefined` - `Could not find component registered with name ...` (ReactOnRails registration fails) - Works in development but crashes on specific pages in production **Cause:** Code in a modern entry point references a global (e.g., `window._`) that is only exposed via `expose-loader` in legacy bundles. The crash kills the script before `registerForRails()` executes, so ReactOnRails reports the component as missing. This bug can be latent under Webpack if legacy bundles happen to load first. **Solution:** Audit all entry points for code that assumes sitewide globals exist. Remove or guard any such references, especially orphaned polyfills for removed features. ### `cache: false` Disables Rspack's In-Memory Cache **Symptoms:** - Subtle compilation issues after adding a "disable cache" environment variable - Slower rebuilds than expected even with in-memory caching supposedly enabled **Cause:** Rspack's top-level `cache` option is boolean-only (`true`/`false`), unlike Webpack's `cache: { type: 'filesystem', buildDependencies: ... }`. Setting `cache: false` to disable disk persistence actually disables rspack's **in-memory cache** entirely. Persistent (disk) caching is controlled separately via `experiments.cache`. **Solution:** Always set `cache: true` for rspack. Control disk persistence exclusively through `experiments.cache`: ```javascript cache: isRspack ? true // always enable in-memory cache; disk persistence via experiments.cache : { type: 'filesystem', buildDependencies: { config: [__filename] } }, // Persistent cache (disk) — opt-in for rspack ...(isRspack && !process.env.DISABLE_FILESYS_CACHE && { experiments: { cache: { type: 'persistent', buildDependencies: [__filename] }, }, }), ``` ### Lazy Compilation Breaks Two-Server Dev Setup **Symptoms:** - Dynamic imports fail silently in development - Network tab shows 404s for `/lazy-compilation-using-__<N>` paths hitting your Rails server - Entry points fail to load with no obvious error **Cause:** Rspack's CLI [auto-enables lazy compilation](https://github.com/web-infra-dev/rspack/blob/main/packages/rspack-cli/src/commands/serve.ts#L130-L133) for web targets when using `rspack serve`. The lazy-compilation proxy uses relative URLs, so the browser resolves them against the page origin (your Rails server) instead of the dev server where the middleware lives. Webpack doesn't auto-enable this, so it's an invisible behavior change. **Solution:** Explicitly disable lazy compilation: ```javascript ...(isRspack && { lazyCompilation: false }), ``` Alternatively, configure `lazyCompilation.backend.listen` to match your dev server setup. ### Third-Party Package Issues Some packages may not ship compiled files. Use `patch-package` to fix: ```bash pnpm add --save-dev patch-package postinstall-postinstall ``` Add to package.json: ```json { "scripts": { "postinstall": "patch-package" } } ``` ## Performance Benefits After migration, expect: - **Build times:** ~53-270ms with Rspack (vs seconds with Webpack) - **~20x faster transpilation** with SWC - **Faster CI runs** and development iteration ## Reference Implementation For a complete working example, see the [react-webpack-rails-tutorial Rspack migration PR](https://github.com/shakacode/react-webpack-rails-tutorial/pull/680). ## Related Documentation - [Webpack Configuration](../core-concepts/webpack-configuration.md) - Rspack vs Webpack overview - [Server-Side Rendering](../core-concepts/react-server-rendering.md) - SSR configuration - [Troubleshooting Guide](../deployment/troubleshooting.md) - General troubleshooting ================================================================================ PAGE: https://reactonrails.com/docs/migrating/babel-to-swc-migration SOURCE: docs/oss/migrating/babel-to-swc-migration.md ================================================================================ # SWC Migration Guide ## Overview This document describes the migration from Babel to SWC for JavaScript/TypeScript transpilation in React on Rails projects using Shakapacker 9.0+. ## What is SWC? SWC (Speedy Web Compiler) is a Rust-based JavaScript/TypeScript compiler that is approximately 20x faster than Babel. Shakapacker 9.0+ uses SWC as the default transpiler. ## Prerequisites - **Shakapacker 9.0+** - SWC support requires Shakapacker version 9.0 or higher - **Node.js 18+** - Recommended for best compatibility - **Yarn or npm** - For package management This guide assumes you're already using Shakapacker 9.0+. If you need to upgrade from an earlier version, see the [Shakapacker upgrade guide](https://github.com/shakacode/shakapacker/blob/main/docs/v9_upgrade.md). ## Migration Steps **Note**: This migration has been successfully implemented in the React on Rails standard dummy app (`react_on_rails/spec/dummy`). The Pro dummy app (`react_on_rails_pro/spec/dummy`) continues using Babel for RSC stability. ### 1. Install Required Dependencies ```bash yarn add -D @swc/core swc-loader ``` ### 2. Update shakapacker.yml Change the `javascript_transpiler` setting from `babel` to `swc`: ```yaml default: &default # Using SWC for faster JavaScript transpilation (20x faster than Babel) javascript_transpiler: swc ``` ### 3. Create SWC Configuration File Create `config/swc.config.js` in your Rails application root with the following content: ```javascript let env; try { ({ env } = require('shakapacker')); } catch (error) { console.error('Failed to load shakapacker:', error.message); console.error('Make sure shakapacker is installed: yarn add shakapacker'); process.exit(1); } const customConfig = { options: { jsc: { transform: { react: { runtime: 'automatic', development: env.isDevelopment, refresh: env.isDevelopment && env.runningWebpackDevServer, useBuiltins: true, }, }, // Keep class names for better debugging and compatibility keepClassNames: true, }, env: { targets: '> 0.25%, not dead', }, }, }; module.exports = customConfig; ``` ### 4. Test the Migration After configuring SWC, test your build process: ```bash # Compile assets bundle exec rake shakapacker:compile # Run tests bundle exec rspec ``` ## React Server Components (RSC) Compatibility ### Current Status (2026) Based on research and testing, here are the key findings regarding SWC and React Server Components compatibility: #### ⚠️ SWC and RSC: Babel is the tested path - **Babel is the tested, reference transpiler for RSC in React on Rails.** The React on Rails Pro dummy app builds RSC with Babel, so it has the most coverage. - The **`'use client'` / `'use server'` boundary transform is performed by the `react-on-rails-rsc` WebpackLoader**, which runs _before_ babel/swc in the loader chain. RSC directive handling does not depend on your transpiler choice — SWC (or Babel) only does ordinary JS/TS transpilation of the RSC, server, and client bundles. - Using `swc-loader` to build an RSC app is wired to work (the generated `rscWebpackConfig.js` extracts and chains either `babel-loader` or `swc-loader`) but is not yet verified end-to-end in React on Rails. - The **React Compiler's SWC plugin is still experimental**, and SWC plugins in general do not follow semver for compatibility. (React Compiler is optional and independent of RSC.) - Next.js recommends version 15.3.1+ for optimal SWC-based build performance with RSC. #### Known Issues 1. **Plugin Instability**: All SWC plugins, including React-related ones, are considered experimental and may have breaking changes without semver guarantees 2. **Framework Dependencies**: React Server Components work best with frameworks that have explicit RSC support (like Next.js), as they require build-time infrastructure 3. **Hydration Challenges**: When using RSC with SWC, hydration mismatches can occur and are difficult to debug 4. **Library Compatibility**: Many popular React libraries are client-centric and may throw hydration errors when used in server components ### Recommendations #### For Standard React Applications - ✅ **SWC is fully compatible** with standard React applications (client-side only) - ✅ All 305 React on Rails tests pass with SWC transpilation - ✅ Significant performance improvements (20x faster than Babel) #### For React Server Components - ⚠️ **Use with caution** - SWC-based RSC builds are not yet the verified path in React on Rails - 📝 **Document your configuration** carefully if using RSC with SWC - 🧪 **Extensive testing required** before production deployment - 🔄 **Monitor updates** to SWC and React Compiler for stability improvements ### Alternative: Continue Using Babel for RSC If you need stable React Server Components support today: 1. Keep `javascript_transpiler: babel` in shakapacker.yml 2. Use the existing Babel configuration with RSC-specific plugins 3. Wait for SWC RSC support to stabilize before migrating ## Migration from Babel to SWC: Feature Comparison ### Features Migrated Successfully | Babel Feature | SWC Equivalent | Notes | | ------------------ | ------------------------------ | --------------------------- | | JSX Transform | `jsc.transform.react` | Automatic runtime supported | | React Fast Refresh | `jsc.transform.react.refresh` | Works in development mode | | Dynamic Imports | Shakapacker SWC parser default | Fully supported | | Class Properties | Built-in | No config needed | | TypeScript | Shakapacker SWC parser default | Native support | ### Features Requiring Different Approach | Babel Feature | SWC Approach | Migration Notes | | ------------------------------------------------ | ------------------------------ | ----------------------------------- | | `babel-plugin-transform-react-remove-prop-types` | Built-in optimization | Handled automatically in production | | `@babel/plugin-proposal-export-default-from` | `jsc.parser.exportDefaultFrom` | Parser option instead of plugin | | Babel macros | Not supported | Requires alternative implementation | | `@loadable/babel-plugin` | Manual code splitting | Use React.lazy() instead | ### Features Not Supported by SWC 1. **Babel Macros** - No equivalent, requires code refactoring 2. **Some Babel Plugins** - Custom Babel plugins won't work, need alternatives 3. **`.swcrc` files** - Not recommended with webpack; use `config/swc.config.js` instead ## Performance Benefits Based on testing with React on Rails: - **Compilation Speed**: ~20x faster than Babel - **Development Experience**: Significantly faster HMR (Hot Module Replacement) - **Build Times**: Reduced from minutes to seconds for large applications - **Memory Usage**: Lower memory footprint during builds ## Troubleshooting ### Issue: PropTypes Not Being Stripped **Solution**: SWC automatically strips PropTypes in production mode. Ensure `NODE_ENV=production` is set. ### Issue: CSS Modules Not Working **Solution**: CSS Modules handling is done by webpack, not by the transpiler. This should work the same with both Babel and SWC. ### Issue: Decorators Not Working **Solution**: Enable decorators in SWC config: ```javascript jsc: { parser: { decorators: true; } } ``` ### Issue: Class Names Being Mangled (Stimulus) **Solution**: Already configured with `keepClassNames: true` in our SWC config. ### Issue: Build Fails with "Cannot find module '@swc/core'" **Solution**: Clear node_modules and reinstall: ```bash rm -rf node_modules yarn.lock yarn install ``` ### Issue: Fast Refresh Not Working **Solution**: Ensure webpack-dev-server is running and check that: - `env.runningWebpackDevServer` is true in development - No syntax errors in components - Components follow Fast Refresh rules (no anonymous exports, must export React components) ### Issue: Syntax Errors Not Being Caught **Solution**: SWC parser is more permissive than Babel. Add TypeScript or stricter ESLint configuration for better error catching: ```bash yarn add -D @typescript-eslint/parser @typescript-eslint/eslint-plugin ``` ### Issue: TypeScript Files Not Transpiling **Solution**: Do not hardcode `jsc.parser` in `config/swc.config.js`. Shakapacker selects the SWC parser per file extension, using TypeScript mode for `.ts` and `.tsx` files. Keep custom settings under `jsc.transform`, `jsc.keepClassNames`, and other non-parser options unless the app has a specific parser feature to enable. ## Testing Results All 305 RSpec tests pass successfully with SWC configuration: ```text 305 examples, 0 failures ``` Test coverage includes: - Client-side rendering - Server-side rendering - Redux integration - React Router - CSS Modules - Image loading - Manual rendering - Shared stores ## Conclusion **For React on Rails projects without React Server Components**: ✅ **Migration to SWC is recommended** The standard React on Rails dummy app (`react_on_rails/spec/dummy`) successfully uses SWC, demonstrating its compatibility with core React on Rails features. **For projects using React Server Components**: ⚠️ **Stay with Babel for now** - The React on Rails Pro dummy app builds RSC with Babel, which is the tested transpiler path. SWC-based RSC builds are wired to work but are not yet verified end-to-end, and the React Compiler's SWC plugin remains experimental. Stay with Babel, or conduct extensive testing before production deployment. ## References - [Shakapacker SWC Documentation](https://github.com/shakacode/shakapacker/blob/main/docs/using_swc_loader.md) - [SWC Official Documentation](https://swc.rs/) - [React Compiler Documentation](https://react.dev/learn/react-compiler) - [React Server Components RFC](https://github.com/reactjs/rfcs/blob/main/text/0188-server-components.md) ================================================================================ PAGE: https://reactonrails.com/docs/migrating/convert-rails-5-api-only-app SOURCE: docs/oss/migrating/convert-rails-5-api-only-app.md ================================================================================ # Convert Rails 5 API only app to a Rails app 1. Go to the directory where you created your app ```bash $ rails new your-current-app-name ``` Rails will start creating the app and will skip the files you have already created. If there is some conflict then it will stop and you need to resolve it manually. be careful at this step as it might replace you current code in conflicted files. 2. Resolve conflicts ```text 1. Press "d" to see the difference 2. If it is only adding lines then press "y" to continue 3. If it is removeing some of your code then press "n" and add all additions manually ``` 3. Run `bundle install` and follow [the instructions for installing into an existing Rails app](../getting-started/installation-into-an-existing-rails-app.md) ================================================================================ PAGE: https://reactonrails.com/docs/migrating/angular-js-integration-migration SOURCE: docs/oss/migrating/angular-js-integration-migration.md ================================================================================ # AngularJS Integration and Migration to React on Rails [React on Rails](https://github.com/shakacode/react_on_rails) offers a smooth transition to migrating your existing [AngularJS](https://angularjs.org/) + Rails application to use React with Webpack on top of Rails. Here are a few highlights and tips. ## Assets Handling Ideally, you should have your JavaScript libraries packaged by `webpack` and gathered by `yarn`. If you have not already done this, then you can set up the `ReactOnRails` default JS code directory of `/client` to load the JS libraries related to AngularJS, etc. You can configure Webpack to globally export these libraries, so inclusion this way will be no different from using the Rails asset pipeline. However, so long as you _understand_ how your JavaScript will eventually make its way onto your main layout, you will be OK. ## Styling and CSS Modules Once you move to Webpack, you can start using CSS modules. However, you'll need to carefully consider if your styling needs to apply to legacy AngularJS components in your app. ## ngReact Package Check out the [ngReact](https://github.com/ngReact/ngReact) package. This package allows your AngularJS components to contain React components, including support for passing props from AngularJS to React. The [ShakaCode team](http://www.shakacode.com/about/) is using this library on a commercial project. However, we're doing this with some limitations: 1. We're only having the data flow in one direction, from AngularJS to React and never back up to the Angular components. 2. When we get to a case where the React components will affect the Angular layout, we try to convert the components up the tree to React. 3. Thus, the React components within AngularJS components will tend to be React "dumb" components, or totally self-contained chunks of React that have no side effects on the Angular code. ## StoryBook We love using [Storybook](https://storybook.js.org/) to create a simple testing and inspection area of new React components as we migrate them over from AngularJS Components. ## Overall Approach? The big question when doing the migration from AngularJS to React is whether you should replace leaf level components first, to minimize the changes before you can deploy your hybrid AngularJS and React app. The alternative is to try to replace larger chunks at once. Both approaches have pros and cons. 1. Frequent deploys with incremental parts of AngularJS replaced by React allows smaller incremental deploys and easier regression analysis should something break. On the negative side, any ping-pong of data between AngularJS and React can result in a complicated and convoluted architecture. 2. Larger deploys of a full screen can yield efficiencies such as converting the whole screen to use one Redux store. However, this can be a large chunk of code to test and deploy. ================================================================================ PAGE: https://reactonrails.com/docs/migrating/migrating-to-rsc SOURCE: docs/oss/migrating/migrating-to-rsc.md ================================================================================ # Migrating Your React App to React Server Components This guide covers the React-side challenges of migrating an existing React on Rails application to React Server Components (RSC). It focuses on how to restructure your component tree, handle Context and state management, migrate data fetching patterns, deal with third-party library compatibility, and avoid common pitfalls. > [!NOTE] > **Summary for AI agents:** Use this page when the user has an existing React on Rails app and wants to adopt RSC. This covers the React-side migration (component restructuring, state, data fetching). For the initial RSC setup, see the [RSC tutorial](../../pro/react-server-components/tutorial.md). RSC requires Pro with the Node renderer. > **React on Rails Pro required:** RSC support requires [React on Rails Pro](../../pro/react-on-rails-pro.md) 4+ with the node renderer. The Pro gem provides the streaming view helpers (`stream_react_component`, `stream_react_component_with_async_props`, `rsc_payload_react_component`, and `rsc_payload_react_component_with_async_props`), the RSC webpack plugin and loader, and the `registerServerComponent` API. For setup, see the [RSC tutorial](../../pro/react-server-components/tutorial.md). For upgrade steps, see the [performance breakthroughs guide](../../pro/major-performance-breakthroughs-upgrade-guide.md). ## Why Migrate? React Server Components offer significant performance benefits when used correctly: - Significant reductions in client-side bundle size reported across RSC adoption case studies - Improvements in Google Speed Index and Total Blocking Time - Server-only dependencies (date-fns, marked, sanitize-html) never ship to the client Real-world results from teams that have adopted server-first rendering (RSC in production, plus DoorDash's pre-RSC SSR baseline): - **Frigade** — 62% reduction in client-side bundle size ([source](../../pro/react-server-components/success-stories.md#frigade--62-smaller-client-bundle)) - **BlogHunch** — 30% server cost reduction ([source](../../pro/react-server-components/success-stories.md#bloghunch--30-lower-server-costs-in-one-month)) - **Mux** — incremental migration of ~50,000 lines to RSC ([source](../../pro/react-server-components/success-stories.md#mux--migrating-50000-lines-of-react-to-rsc)) - **DoorDash** — 65% LCP improvement (Next.js SSR baseline, pre-RSC) ([source](../../pro/react-server-components/success-stories.md#doordash--core-web-vitals-transformation-ssr-baseline-pre-rsc)) Full case studies with context and caveats: [Migration Success Stories](../../pro/react-server-components/success-stories.md). However, these benefits require intentional architecture changes. Simply adding `'use client'` everywhere preserves the status quo -- `'use client'` is a [boundary marker, not a component annotation](rsc-component-patterns.md#use-client-marks-a-boundary-not-a-component-type). The guides below walk you through the restructuring needed to capture real gains. ## Article Series This migration guide is organized as a series of focused articles. We recommend reading them in order, but each is self-contained: ### 1. [Preparing Your App](rsc-preparing-app.md) How to set up the RSC infrastructure before migrating any components. Covers: - Installing dependencies and configuring Rails for RSC - Creating the RSC webpack bundle and adding the RSC plugin to existing bundles - Adding `'use client'` to all existing component entry points (so nothing changes yet) - Switching to streaming view helpers and controllers - After this step, the app works identically -- you're just ready for migration ### 2. [Component Tree Restructuring Patterns](rsc-component-patterns.md) How to restructure your component tree for RSC. Covers: - The top-down migration strategy (start at layouts, push `'use client'` to leaves) - The "donut pattern" for wrapping server content in client interactivity - Splitting mixed components into server and client parts - Passing Server Components as children to Client Components - Before/after examples of common restructuring patterns ### 3. [Context, Providers, and State Management](rsc-context-and-state.md) How to handle React Context and global state in an RSC world. Covers: - Why Context doesn't work in Server Components and what to do about it - The provider wrapper pattern (creating `'use client'` provider components) - Composing multiple providers without "provider hell" - Migrating Redux to work alongside RSC - Using `React.cache()` as a server-side alternative to Context - Theme, auth, and i18n provider patterns ### 4. [Data Fetching Migration](rsc-data-fetching.md) How to migrate from client-side data fetching to server component patterns. Covers: - Replacing `useEffect` + `fetch` with async Server Components - Migrating from React Query / TanStack Query (prefetch + hydrate pattern) - Migrating from SWR (fallback data pattern) - Avoiding server-side waterfalls with parallel fetching - Streaming data with the `use()` hook and Suspense - When to keep client-side data fetching ### 5. [HTTP Response Ownership](rsc-http-response-patterns.md) How to keep HTTP response semantics in Rails while rendering the UI with RSC. Covers: - Preflight patterns for controller/service decisions before streaming - Route-level `404` and not-found UI patterns - Redirect ownership and why it should stay in Rails - Cache header strategy for public and personalized RSC responses - Passing response policy into the RSC tree as serializable props ### 6. [Third-Party Library Compatibility](rsc-third-party-libs.md) How to handle libraries that aren't RSC-compatible. Covers: - Creating thin `'use client'` wrapper files - CSS-in-JS migration (styled-components, Emotion alternatives) - UI library compatibility (MUI, Chakra, Radix, shadcn/ui) - Form, animation, charting, and date library status - The barrel file problem and direct imports - Using `server-only` and `client-only` packages ### 7. [Troubleshooting and Common Pitfalls](rsc-troubleshooting.md) How to debug and avoid common problems. Covers: - Serialization boundary issues (what can cross server-to-client) - Import chain contamination and accidental client components - Hydration mismatch debugging - Error boundary limitations with RSC - Testing strategies (unit, integration, E2E) - TypeScript considerations - Performance monitoring and bundle analysis tools - Common error messages and their solutions ### 8. [Flight Payload Optimization](rsc-flight-payload.md) How to optimize RSC Flight payload size for better performance. Covers: - What's in the Flight payload and why it can be surprisingly large - Why "all display-only = server" is an oversimplification - The counterintuitive pattern: when presentational Client Components outperform Server Components - How to measure and analyze your Flight payload - Compression effectiveness and the LCP tradeoff - React on Rails double JSON.stringify overhead ### 9. [RSC Performance Validation](rsc-performance-validation.md) How to prove that an RSC conversion improved the page users actually see. Covers: - Local control/experiment setup on the same machine - Warm cached SSR baselines for pages that already use React on Rails Pro caching - Visual regression checks paired with Lighthouse and resource metrics - Package-stack discipline for published, canary, RC, and diagnostic builds - Required PR metrics and the public-page case study ### 10. [Mostly Static RSC Shell With a Tiny Sidecar](rsc-static-shell-sidecar.md) How to render public/static-ish pages as mostly static RSC HTML while preserving a few browser behaviors without loading the full global application pack. Covers: - Rails layout opt-out for selected global JavaScript packs - Inert JSON props/context handoff to a sidecar - Intent hydration with keyboard, accessibility, and no-JS fallback checks - CSS parity and behavior audit checklists - Bundler and `clientReferences` caveats ## How RSC Maps to React on Rails Before diving into the React patterns, understand how RSC maps to React on Rails' architecture. **Multiple component roots.** Unlike single-page apps with one `App.jsx` root, React on Rails renders independent component trees from ERB views. Each `react_component`, `stream_react_component`, or `stream_react_component_with_async_props` call is a separate root. You migrate **per-component**, not per-app. **Three API changes per component.** Each component you migrate touches three layers: | Layer | Before | After | | --------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ERB view helper | `react_component("Product", ...)` | `stream_react_component("Product", ...)` or `stream_react_component_with_async_props("Product", ...)` when Rails emits async props | | JS registration | `ReactOnRails.register({ Product })` | `registerServerComponent` (signature varies per bundle — see [details](../core-concepts/auto-bundling-file-system-based-automated-bundle-generation.md#the-two-registerservercomponent-signatures)) | | Controller | Standard Rails controller | Add `include ReactOnRailsPro::Stream` | **Three webpack bundles.** RSC requires separate client, server, and RSC bundles. The `registerServerComponent` API behaves differently in each: - **RSC bundle** -- registers the actual Server Component for RSC payload generation - **Server bundle** -- wraps the component for streaming SSR - **Client bundle** -- registers a placeholder that fetches the RSC payload from the server > **Setup instructions:** For webpack configuration, bundle structure, route setup, and step-by-step instructions, see the [React on Rails Pro RSC tutorial](../../pro/react-server-components/tutorial.md). This guide focuses on the **React-side patterns** you'll need after setup is complete. ## Quick-Start Migration Strategy Tailored for React on Rails' multi-root architecture: 1. **[Prepare your app](rsc-preparing-app.md)** -- set up the RSC infrastructure, add `'use client'` to all component entry points, and switch to streaming rendering. The app works identically -- nothing changes yet. 2. **Pick a component and push the boundary down** -- move `'use client'` from the root component to its interactive children, letting parent components become Server Components. 3. **Adopt advanced patterns** -- add Suspense boundaries, [`stream_react_component`](rsc-data-fetching.md#data-fetching-in-react-on-rails-pro) for streaming SSR, `stream_react_component_with_async_props` for progressively emitted Rails data, and server-side data fetching. 4. **[Keep route policy in Rails](rsc-http-response-patterns.md)** -- for each route, decide redirects, status codes, and cache headers before streaming commits the response. 5. **Repeat for each registered component** -- migrate components one at a time, in any order. This approach lets you migrate incrementally, one component at a time, without ever breaking your app. ## Component Audit Checklist Before you start, audit your components using this classification: | Category | Criteria | Action | | ------------------------- | ---------------------------------------------------------- | --------------------------------------------------------------------- | | **Server-ready** (green) | No hooks, no browser APIs, no event handlers | Remove `'use client'` -- these are Server Components by default | | **Refactorable** (yellow) | Mix of data fetching and interactivity | Split into a Server Component (data) + Client Component (interaction) | | **Client-only** (red) | Uses `useState`, `useEffect`, event handlers, browser APIs | Keep `'use client'` -- these remain Client Components | ## Migration Readiness Checklist Before starting any component migration, verify these items. Skipping them is the most common source of wasted debugging time: ### Infrastructure - [ ] **React 19 installed** -- both `react` and `react-dom` at 19.x, with matching versions (`yarn why react` shows no duplicates) - [ ] **Node renderer configured** -- RSC requires `NodeRenderer`, not ExecJS. If `config.server_renderer` is not set to `"NodeRenderer"`, migrate first - [ ] **`react-on-rails-rsc` 19.0.4+** -- earlier versions vendored stale React builds. Check with `yarn why react-on-rails-rsc` - [ ] **Three webpack bundles building** -- client, server, and RSC bundles all compile without errors - [ ] **RSC manifests generated** -- `react-client-manifest.json` and `react-server-client-manifest.json` exist in your webpack output directory - [ ] **RSC payload route mounted** -- `rsc_payload_route` in `config/routes.rb` - [ ] **Procfile.dev updated** -- separate watcher process for the RSC bundle (`HMR=true RSC_BUNDLE_ONLY=true bin/shakapacker --watch`) ### Common Pre-Migration Mistakes These mistakes account for the majority of setup failures: | Mistake | Symptom | Fix | | --------------------------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | Missing `rsc_payload_route` in routes | 404 on RSC payload requests | Add `rsc_payload_route` to `config/routes.rb` | | Only 2 webpack bundles (forgot RSC) | Components remain Client Components after removing `'use client'` | Create `rscWebpackConfig.js` and add to build pipeline ([Step 4](rsc-preparing-app.md#step-4-set-up-the-rsc-webpack-bundle)) | | `'use client'` on bundle entry files instead of component files | Can't migrate components individually | Move `'use client'` to each component source file ([Step 5](rsc-preparing-app.md#step-5-add-use-client-to-all-registered-component-entry-points)) | | Missing `'use client'` on `.server.jsx` files | Auto-bundled components break after enabling RSC | `.server.jsx` is a bundle convention, not an RSC designation -- add `'use client'` to both `.client.jsx` and `.server.jsx` | | React version duplicates in `node_modules` | Cryptic hook errors, "Invalid hook call" | Deduplicate with `yarn why react` and webpack aliases | | Not switching to `stream_react_component` | No streaming benefits, components render synchronously | Replace `react_component` with `stream_react_component` in views | | Missing `include ReactOnRailsPro::Stream` in controller | `stream_view_containing_react_components` undefined | Add the concern to controllers that render React components | ## Prerequisites - React 19+ - [React on Rails Pro](../../pro/react-on-rails-pro.md) 4+ with React on Rails 15+ - Node renderer configured (RSC requires server-side JavaScript execution) - RSC webpack bundle configured (see [RSC tutorial](../../pro/react-server-components/tutorial.md)) - Node.js 20+ - Understanding of the [server vs client component mental model](https://react.dev/reference/rsc/server-components) ## Related Guides - [Upgrading an Existing Pro App to RSC](../../pro/react-server-components/upgrading-existing-pro-app.md) — generator-based runbook for adding RSC to an existing Pro app, including legacy webpack compatibility and verification checklist - [React 19 Native Metadata](../building-features/react-19-native-metadata.md) — replace react-helmet and `react_component_hash` with React 19's built-in `<title>`, `<meta>`, and `<link>` hoisting. Native metadata works with streaming and RSC out of the box. - [HTTP Response Ownership](rsc-http-response-patterns.md) — keep `404`, redirects, and cache policy in Rails while rendering route UI with RSC. - [RSC Performance Validation](rsc-performance-validation.md) — build the visual plus performance evidence package before claiming an RSC win. - [Mostly Static RSC Shell With a Tiny Sidecar](rsc-static-shell-sidecar.md) — keep public RSC shells static while moving small browser behaviors into an explicit sidecar. ## References - [React Server Components RFC](https://react.dev/reference/rsc/server-components) - [React `'use client'` directive](https://react.dev/reference/rsc/use-client) - [React on Rails Pro RSC tutorial](../../pro/react-server-components/tutorial.md) - [React on Rails Pro RSC purpose and benefits](../../pro/react-server-components/purpose-and-benefits.md) - [RSC migration success stories](../../pro/react-server-components/success-stories.md) ================================================================================ PAGE: https://reactonrails.com/docs/migrating/rsc-preparing-app SOURCE: docs/oss/migrating/rsc-preparing-app.md ================================================================================ # RSC Migration: Preparing Your App This guide walks you through the infrastructure changes needed to prepare an existing React on Rails application for React Server Components (RSC). After completing these steps, your app works exactly as before -- no component behavior changes -- but the RSC pipeline is in place so you can begin migrating components to Server Components. > **Part 1 of the [RSC Migration Series](migrating-to-rsc.md)** | Next: [Component Tree Restructuring](rsc-component-patterns.md) ## What This Guide Covers You will: 1. Install the RSC npm package 2. Enable RSC support in the Rails configuration 3. Mount the RSC payload route 4. Create the RSC webpack bundle and add the RSC plugin to existing bundles 5. Add `'use client'` to all your registered component entry points 6. Switch views and controllers to streaming rendering After these steps, every component is still a Client Component (because of the `'use client'` directives), so the app behaves identically to before. The subsequent guides in this series cover how to progressively remove `'use client'` and convert components to Server Components. ## Prerequisites Before starting, ensure you have: - **React on Rails Pro 4+** with **React on Rails 15+** - **React 19** (`react` and `react-dom` both at 19.x) - **Node renderer** configured and running (RSC requires server-side JavaScript execution via the node renderer, not ExecJS). If you're still using ExecJS, migrate to the node renderer first -- see [Node Renderer Basics](../building-features/node-renderer/basics.md). - **Shakapacker** (or webpack configured via Shakapacker) - **Node.js 20+** ## Step 1: Install the RSC Package Install `react-on-rails-rsc`, which provides the webpack loader, webpack plugin, and RSC client/server runtime: ```bash yarn add react-on-rails-rsc # or: npm install react-on-rails-rsc # or: pnpm add react-on-rails-rsc ``` Verify that `react` and `react-dom` are at version 19 and that the versions match: ```bash yarn why react # Should show 19.x yarn why react-on-rails-rsc # Check the package's README or changelog for React version compatibility ``` If you're on React 18 or earlier, upgrade first -- RSC requires React 19. > **Version requirements:** Use `react-on-rails-rsc` **19.0.4 or later** -- earlier versions (19.0.0 through 19.0.3) vendored older builds of `react-server-dom-webpack` that were updated in 19.0.4. Check the `react-on-rails-rsc` README or changelog for the supported React version range. ## Step 2: Configure Rails for RSC Update your React on Rails Pro initializer: ```ruby # config/initializers/react_on_rails_pro.rb ReactOnRailsPro.configure do |config| # --- Required changes --- # Enable the RSC pipeline (default: false) config.enable_rsc_support = true # Enable promise-based rendering for streaming support (default: false) # Only takes effect when server_renderer is "NodeRenderer" config.rendering_returns_promises = true # --- Already correct defaults (shown for visibility) --- # RSC bundle filename -- must match your webpack output filename # Default: "rsc-bundle.js" -- no change needed if you follow the standard setup config.rsc_bundle_js_file = "rsc-bundle.js" # URL path for RSC payload requests from the browser # Default: "rsc_payload/" -- no change needed config.rsc_payload_generation_url_path = "rsc_payload/" # Manifest files generated by RSCWebpackPlugin # Defaults match the plugin's output filenames -- no change needed config.react_client_manifest_file = "react-client-manifest.json" config.react_server_client_manifest_file = "react-server-client-manifest.json" # ... your existing config (server_renderer, renderer_url, etc.) end ``` The base gem's configuration (`ReactOnRails.configure`) does not require RSC-specific changes. If you're using Shakapacker >= 8.2.0 with Pro, `generated_component_packs_loading_strategy` already defaults to `:async`, which is optimal for streaming. ## Step 3: Mount the RSC Payload Route The RSC payload route serves the RSC payload when the browser navigates to a page with Server Components. Add it to your routes: ```ruby # config/routes.rb Rails.application.routes.draw do rsc_payload_route # ... your existing routes end ``` This mounts a `GET /rsc_payload/:component_name` endpoint that React on Rails Pro uses internally. The default path (`rsc_payload/`) matches the `rsc_payload_generation_url_path` config. If your app has a route conflict at that path, you can customize both: ```ruby # Custom path (use the same value in both places, with trailing slash) rsc_payload_route path: "flight-payload/" ``` ```ruby # config/initializers/react_on_rails_pro.rb config.rsc_payload_generation_url_path = "flight-payload/" ``` ## Step 4: Set Up the RSC Webpack Bundle RSC requires a **third webpack bundle** alongside your existing client and server bundles. This RSC bundle contains only Server Component code -- the webpack loader strips out `'use client'` files and replaces them with client references. > **Custom webpack configs:** The examples below assume you're using the default webpack configs generated by the React on Rails installer. If your webpack setup is substantially different (custom Webpack configs, different file structure, different loaders), read the **"What this does"** callouts in each subsection -- they explain the underlying intent of each change so you can apply the same logic to your own config. ### 4a. Create the RSC webpack config **What this does (for custom configs):** You need a third webpack config that produces an `rsc-bundle.js` file. This RSC bundle is essentially a copy of your server bundle with three modifications: 1. **Add `react-on-rails-rsc/WebpackLoader`** to the JavaScript loader chain (after babel-loader or swc-loader). This loader intercepts files containing `'use client'` and replaces their exports with lightweight client reference stubs instead of actual component code. This is what keeps client code out of the RSC bundle. 2. **Add `react-server` to `resolve.conditionNames`**. This tells webpack to use the `react-server` export condition from `package.json` when resolving modules -- React itself ships different entry points for the RSC environment vs the normal server environment. 3. **Canonicalize React server imports to one package instance**. Every import of `react`, `react/jsx-runtime`, and `react/jsx-dev-runtime` inside the RSC bundle must resolve to the same React server files. This keeps React's request-local cache dispatcher shared between the RSC renderer and app Server Components, so `React.cache()` works correctly. 4. **Alias `react-dom/server` to `false`**. The RSC bundle generates RSC payloads (a serialization format), not HTML. Importing `react-dom/server` in the RSC environment causes a runtime error, so it must be excluded. The entry point should be the **same file** as your server bundle (typically `server-bundle.js`), just with a different output filename (`rsc-bundle.js`). Do **not** add `RSCWebpackPlugin` to this config -- only the client and server bundles need it. Create `config/webpack/rscWebpackConfig.js`: ```js // React Server Components webpack configuration // Creates the RSC bundle based on the server webpack config // See: ../../pro/react-server-components/how-react-server-components-work.md const { existsSync } = require('fs'); const { dirname, resolve } = require('path'); const serverWebpackModule = require('./serverWebpackConfig'); // Backward compatibility: // - New Pro config exports: { default: configureServer, extractLoader } // - Legacy config exports: module.exports = configureServer const serverWebpackConfig = serverWebpackModule.default || serverWebpackModule; const reactPackageRoot = dirname(require.resolve('react/package.json')); // React 19+ ships these react-server entry files alongside the standard entries. const resolveReactServerEntry = (entryFilename) => { const entryPath = resolve(reactPackageRoot, entryFilename); if (!existsSync(entryPath)) { throw new Error( `Expected React server entry "${entryFilename}" at "${entryPath}". ` + 'React package layout changed; update the RSC webpack aliases.', ); } return entryPath; }; const extractLoader = serverWebpackModule.extractLoader || ((rule, loaderName) => { if (!Array.isArray(rule.use)) return null; return rule.use.find((item) => { const testValue = typeof item === 'string' ? item : item.loader; return testValue && testValue.includes(loaderName); }); }); const configureRsc = () => { // Pass true to skip RSCWebpackPlugin - RSC bundle doesn't need it const rscConfig = serverWebpackConfig(true); // Rename the entry from `server-bundle` to `rsc-bundle` so webpack // produces a different output filename, while keeping the same entry // point file used by the server bundle. const rscEntry = { 'rsc-bundle': rscConfig.entry['server-bundle'], }; rscConfig.entry = rscEntry; // Add the RSC WebpackLoader to the JS rule's loader chain. // This loader replaces 'use client' files with registerClientReference // proxies in the RSC bundle. // Webpack loaders execute right-to-left, so appending makes the RSC // loader run first (before babel/swc). const { rules } = rscConfig.module; rules.forEach((rule) => { if (typeof rule.use === 'function') { // SWC transpiler: rule.use is a function const originalUse = rule.use; rule.use = function rscLoaderWrapper(data) { const result = originalUse.call(this, data); const resultArray = Array.isArray(result) ? result : result ? [result] : []; const resolvedRule = { use: resultArray }; const jsLoader = extractLoader(resolvedRule, 'babel-loader') || extractLoader(resolvedRule, 'swc-loader'); if (jsLoader) { return [...resultArray, { loader: 'react-on-rails-rsc/WebpackLoader' }]; } return result; }; } else if (Array.isArray(rule.use)) { // Babel transpiler: rule.use is a static array const jsLoader = extractLoader(rule, 'babel-loader') || extractLoader(rule, 'swc-loader'); if (jsLoader) { rule.use = [...rule.use, { loader: 'react-on-rails-rsc/WebpackLoader' }]; } } }); // Add the `react-server` condition to the resolve config. // This tells webpack (and React) that this bundle targets the RSC environment. // The `...` retains default conditions (e.g., `node` for server target). const rscAliases = { ...(rscConfig.resolve?.alias || {}) }; delete rscAliases.react; delete rscAliases['react$']; delete rscAliases['react/jsx-runtime']; delete rscAliases['react/jsx-runtime$']; delete rscAliases['react/jsx-dev-runtime']; delete rscAliases['react/jsx-dev-runtime$']; delete rscAliases['react-dom/server']; delete rscAliases['react-dom/server$']; rscConfig.resolve = { ...rscConfig.resolve, conditionNames: ['react-server', '...'], alias: { ...rscAliases, // Keep the RSC renderer and app Server Components on the same React // server package instance so React.cache() sees the active dispatcher. react$: resolveReactServerEntry('react.react-server.js'), 'react/jsx-runtime$': resolveReactServerEntry('jsx-runtime.react-server.js'), 'react/jsx-dev-runtime$': resolveReactServerEntry('jsx-dev-runtime.react-server.js'), // Ignore react-dom/server in RSC bundle -- it's not needed for // RSC payload generation and importing it causes a runtime error // Prefix-match false covers both exact and subpath imports; no $-variant is needed. 'react-dom/server': false, }, }; // Update the output filename rscConfig.output.filename = 'rsc-bundle.js'; return rscConfig; }; module.exports = configureRsc; ``` > **Mutation safety note:** This example assumes `serverWebpackConfig(true)` returns a fresh config object per call. If your setup reuses shared config objects, clone `module.rules` / `rule.use` before mutating them in `configureRsc`. > > **React aliases note:** Do not alias `react` to a package directory in the RSC bundle. Directory aliases can bypass the `react-server` condition or create duplicate React server modules. The exact file aliases in the example above keep `React.cache()` request-local memoization connected to the RSC renderer dispatcher. > Before applying those aliases, remove any inherited `react`, `react$`, `react/jsx-runtime`, `react/jsx-runtime$`, `react/jsx-dev-runtime`, `react/jsx-dev-runtime$`, `react-dom/server`, and `react-dom/server$` aliases from the server config, matching the cleanup block shown above. ### 4b. Add RSCWebpackPlugin to the server webpack config **What this does (for custom configs):** The server bundle needs to know which components are Client Components so it can generate proper references during SSR. `RSCWebpackPlugin` with `isServer: true` scans your source files for `'use client'` directives and produces a **`react-server-client-manifest.json`** -- a mapping of client component module IDs to their chunk locations. If your server webpack config is completely custom, add `new RSCWebpackPlugin({ isServer: true, clientReferences: [...] })` to its `plugins` array. The `clientReferences` array tells the plugin which directories to scan for `'use client'` files -- point it at your app's source directory. Also, modify your server config function to accept a parameter so the RSC config (step 4a) can reuse it without the plugin. The server bundle needs `RSCWebpackPlugin` to generate the `react-server-client-manifest.json`. Update your `serverWebpackConfig.js` to accept an `rscBundle` parameter and conditionally add the plugin: ```js // config/webpack/serverWebpackConfig.js const { RSCWebpackPlugin } = require('react-on-rails-rsc/WebpackPlugin'); const configureServer = (rscBundle = false) => { // ... your existing server config setup ... // Add RSCWebpackPlugin only for the server bundle (not the RSC bundle) if (!rscBundle) { serverWebpackConfig.plugins.push( new RSCWebpackPlugin({ isServer: true, clientReferences: [{ directory: './client/app', recursive: true, include: /\.(js|ts|jsx|tsx)$/ }], }), ); } // ... rest of your server config ... return serverWebpackConfig; }; module.exports = { default: configureServer, extractLoader, // Export if you have this utility function }; ``` > **`clientReferences`**: Always point this at your application source directory. If omitted, the plugin defaults to scanning the entire project root recursively (`{ directory: ".", recursive: true, include: /\.(js|ts|jsx|tsx)$/ }`). That can accidentally discover vendored gem templates under paths such as `vendor/bundle` in CI and make webpack compile files that are not part of your app. Setting `directory` to your app's source directory (e.g., `'./client/app'`) limits the scan to only the files that could contain `'use client'` directives. > **Do not use `clientReferences: []` as a global performance setting.** This option is not only > a scan-cost knob: it controls which `'use client'` modules the RSC plugin can discover and emit > into `react-client-manifest.json` and `react-server-client-manifest.json`. An empty or very narrow > list may be acceptable for a static-only build that never renders RSC client islands, but a mixed > app needs its client boundaries discoverable so future buttons, menus, forms, and search boxes can > hydrate. Prefer scoping to the app source directory now, and follow the route/page/entry-scoped > manifest work tracked in > [react_on_rails_rsc#134](https://github.com/shakacode/react_on_rails_rsc/issues/134). See > [Client Reference Scope and Empty `clientReferences`](rsc-troubleshooting.md#client-reference-scope-and-empty-clientreferences) > for the decision guide. > **Generator note (CommonJS only):** The `rails generate react_on_rails:rsc` migration only rewrites webpack configs that use CommonJS (`require`-style) imports. If your config has been converted to ESM (`import`/`export`) syntax, the generator emits an "expected webpack import anchor was not found" warning and you must add `clientReferences` manually as shown above. > **Upgrade note for apps already on RSC:** `verify_rsc_webpack_transforms` (and the `rails generate react_on_rails:rsc` doctor check) now requires that `RSCWebpackPlugin` be invoked with `clientReferences: rscClientReferences` pointing at `resolve(config.source_path)`. Existing apps that have the plugin without a scoped `clientReferences` option were previously passing verification and will now report `"generated scoped clientReferences in {client,server}WebpackConfig.js"` as a missing transform. To remediate, either (a) re-run `rails generate react_on_rails:rsc` and accept the in-place migration, or (b) manually add the helper and option as shown above — declare `const rscClientReferences = { directory: resolve(config.source_path), recursive: true, include: /\.(js|mjs|cjs|ts|mts|cts|jsx|tsx)$/ };` at module scope and pass `clientReferences: rscClientReferences` into every `RSCWebpackPlugin` invocation. ### 4c. Add RSCWebpackPlugin to the client webpack config **What this does (for custom configs):** The client bundle needs its own manifest so React on Rails Pro can map client component references (from the RSC payload) to the actual client-side chunks the browser should load. `RSCWebpackPlugin` with `isServer: false` produces a **`react-client-manifest.json`**. If your client webpack config is completely custom, add `new RSCWebpackPlugin({ isServer: false, clientReferences: [...] })` to its `plugins` array. Use the same `clientReferences` as the server config -- both must scan the same source directory. The client bundle needs `RSCWebpackPlugin` to generate the `react-client-manifest.json`: ```js // config/webpack/clientWebpackConfig.js const { RSCWebpackPlugin } = require('react-on-rails-rsc/WebpackPlugin'); const configureClient = () => { // ... your existing client config ... clientConfig.plugins.push( new RSCWebpackPlugin({ isServer: false, clientReferences: [{ directory: './client/app', recursive: true, include: /\.(js|ts|jsx|tsx)$/ }], }), ); return clientConfig; }; ``` ### 4d. Update the build pipeline **What this does (for custom configs):** Before RSC, you built 2 webpack bundles (client + server). Now you need to build 3 (client + server + RSC). However your build is orchestrated -- a multi-compiler config array, separate webpack commands, a CI script, or a tool like `ServerClientOrBoth.js` -- add the RSC config as a third entry. You also need a **separate watcher process** in development for the RSC bundle (similar to how you already watch the server bundle separately). Add an environment variable guard (e.g., `RSC_BUNDLE_ONLY`) so you can build each bundle independently in dev, and build all three together in production. Update `ServerClientOrBoth.js` (or your equivalent webpack entry point) to include the RSC bundle: ```js // config/webpack/ServerClientOrBoth.js const clientWebpackConfig = require('./clientWebpackConfig'); const { default: serverWebpackConfig } = require('./serverWebpackConfig'); const rscWebpackConfig = require('./rscWebpackConfig'); const webpackConfig = (envSpecific) => { const clientConfig = clientWebpackConfig(); const serverConfig = serverWebpackConfig(); const rscConfig = rscWebpackConfig(); if (envSpecific) { envSpecific(clientConfig, serverConfig); } let result; if (process.env.WEBPACK_SERVE || process.env.CLIENT_BUNDLE_ONLY) { result = clientConfig; } else if (process.env.SERVER_BUNDLE_ONLY) { result = serverConfig; } else if (process.env.RSC_BUNDLE_ONLY) { result = rscConfig; } else { // Build all three bundles result = [clientConfig, serverConfig, rscConfig]; } return result; }; module.exports = webpackConfig; ``` Add the RSC bundle watcher to your `Procfile.dev`: [Diagram: Static diagram showing the RSC build pipeline with three parallel webpack bundle processes (client, server, RSC) plus the Node renderer, as defined in Procfile.dev. Each bundle targets different environments and entry points.] > **For full webpack configuration details**, including the technical background on how the RSC loader, plugin, and manifests work together, see [How React Server Components Work](../../pro/react-server-components/how-react-server-components-work.md). ## Step 5: Add `'use client'` to All Registered Component Entry Points This is the critical step that preserves your app's existing behavior. By adding `'use client'` to every component entry point, you tell the RSC infrastructure: "all these components are Client Components." The app works exactly as before -- nothing renders on the server differently. Later, when you're ready to migrate a component to a Server Component, you'll remove its `'use client'` directive. That's covered in [Component Tree Restructuring Patterns](rsc-component-patterns.md). ### Where to add `'use client'` The directive goes on **the component source files** that are registered with React on Rails -- not on the bundle entry files (`client-bundle.js`, `server-bundle.js`). ### Pattern A: Manual registration (component imported into bundle) If your bundle file imports components and registers them: ```js // client-bundle.js -- do NOT add 'use client' here import ReactOnRails from 'react-on-rails/client'; import ProductPage from '../components/ProductPage'; import CartPage from '../components/CartPage'; ReactOnRails.register({ ProductPage, CartPage }); ``` Add `'use client'` to each **component file**: ```jsx // components/ProductPage.jsx 'use client'; import React, { useState } from 'react'; // ... rest of your component ``` ```jsx // components/CartPage.jsx 'use client'; import React from 'react'; // ... rest of your component ``` Do the same for any component files imported in your `server-bundle.js`. ### Pattern B: Auto-bundling (single file per component) If you use `auto_load_bundle` with a `components_subdirectory`, each component has a file in that directory. Once you start migrating components to Server Components, auto-bundling will automatically switch each component's registration between `ReactOnRails.register` and `registerServerComponent` based on whether the file starts with `'use client'`. For the complete reference, see [Auto-Bundling with React Server Components](../core-concepts/auto-bundling-file-system-based-automated-bundle-generation.md#auto-bundling-with-react-server-components). ```text app/javascript/src/ └── ProductPage/ └── ror_components/ # your components_subdirectory └── ProductPage.jsx # ← add 'use client' here └── CartPage/ └── ror_components/ └── CartPage.jsx # ← add 'use client' here ``` ```jsx // app/javascript/src/ProductPage/ror_components/ProductPage.jsx 'use client'; import ProductPage from '../components/ProductPage'; export default ProductPage; ``` ### Pattern C: Auto-bundling with `.client` / `.server` file pairs If you use separate files for client and server rendering: ```text app/javascript/src/ └── ReduxApp/ └── ror_components/ ├── ReduxApp.client.jsx # ← add 'use client' here └── ReduxApp.server.jsx # ← add 'use client' here too ``` **Add `'use client'` to both the `.client` AND `.server` files:** ```jsx // ReduxApp.client.jsx 'use client'; import React from 'react'; import { Provider } from 'react-redux'; // ... client-side rendering logic (hydrateRoot, etc.) ``` ```jsx // ReduxApp.server.jsx 'use client'; import React from 'react'; import { Provider } from 'react-redux'; // ... server-side rendering logic (returns JSX) ``` > **Why both?** The `.client` and `.server` suffixes control **which webpack bundle** includes the file -- `.client.jsx` goes into the client bundle, `.server.jsx` goes into the server bundle (and RSC bundle). This is a **React on Rails auto-bundling concept** that predates React Server Components. > > The `'use client'` directive controls **RSC classification** -- whether the RSC infrastructure treats the component as a Client Component or a Server Component. These are two independent systems. > > A `.server.jsx` file is **not** a React Server Component. It's a file included in the server bundle. Without `'use client'`, the RSC infrastructure would try to treat it as a Server Component, which would break your existing rendering logic. > > For more on this distinction, see [File Suffixes vs. RSC Directive](https://github.com/shakacode/react_on_rails/pull/2406). ### Transpiled languages (ReScript, Reason, etc.) If you use ReScript or other transpiled languages, the compiled `.bs.js` files don't preserve directives. Add `'use client'` to the **wrapper `.jsx` files** in `ror_components/`, not to the `.res` source files. For example, with `.client.jsx` / `.server.jsx` pairs: ```jsx // ListingsShow.client.jsx — add 'use client' here 'use client'; import ListingsShow from '../ListingsShow'; export default ListingsShow; ``` ```jsx // ListingsShow.server.jsx — add 'use client' here too 'use client'; import ListingsShow from '../ListingsShow'; export default ListingsShow; ``` > **Common mistake:** Developers often add `'use client'` to JS/JSX entry points but forget the ReScript ones. The pack generator will **silently** register components without `'use client'` as server components via `registerServerComponent`. There is no warning — the component just breaks at runtime. After adding the directive, verify with `bin/rails react_on_rails:generate_packs` and check that the output shows all components as "Client components." ### What about the bundle entry files? Adding `'use client'` to `client-bundle.js` or `server-bundle.js` would technically work -- it would make all imported components Client Components, achieving the same immediate effect. However, we recommend placing the directive on **individual component files** instead. The reason is forward-looking: when you later want to convert a specific component to a Server Component (by removing `'use client'`), you need granular control per component. If the directive is only on the bundle entry file, you'd have to move it to every individual component file at that point anyway. ### Verification After adding `'use client'` to all entry points, rebuild all three bundles and verify the app works as before. If you're using auto-bundling, the generated packs should still use `ReactOnRails.register` (not `registerServerComponent`) for every component. ## Step 6: Switch to Streaming Rendering Replace synchronous view helpers and controller rendering with their streaming equivalents. > **Warning: Compression middleware callbacks.** Default `Rack::Deflater`, `Rack::Brotli`, and similar compression middleware work with streaming responses, but a custom `:if` condition that calls `body.each` to check response size will deadlock on `ActionController::Live::Buffer`. See the Pro guide [Compression for Streamed RSC Responses](../../pro/streaming-ssr.md#compression-middleware-compatibility) for the safe pattern. ### 6a. Update controllers For each controller that renders React components, include the `ReactOnRailsPro::Stream` concern and replace `render` with `stream_view_containing_react_components`: **Before:** ```ruby class ProductsController < ApplicationController def show @product = Product.find(params[:id]) # Implicit render of products/show template end end ``` **After:** ```ruby class ProductsController < ApplicationController include ReactOnRailsPro::Stream def show @product = Product.find(params[:id]) stream_view_containing_react_components(template: "products/show") end end ``` `ReactOnRailsPro::Stream` automatically includes `ActionController::Live`, which enables HTTP streaming. The `stream_view_containing_react_components` method renders the template and streams the response progressively as React components resolve. > **Which actions need this?** Only actions whose views use `stream_react_component`. If an action's view only uses `react_component` (and you haven't migrated it yet in the step below), it can keep the standard `render`. ### 6b. Update view helpers (optional now) This step can be done now for all components at once, or deferred and done per-component as you migrate each one to a Server Component. Either way works — `react_component` continues to function alongside the RSC pipeline. In each view, replace `react_component` with `stream_react_component`: **Before:** ```erb <%# app/views/products/show.html.erb %> <h1><%= @product.name %></h1> <%= react_component("ProductPage", props: { product: @product.as_json( include: { specs: { only: [:id, :label, :value] }, reviews: { only: [:id, :text, :rating] } }) }, prerender: true) %> ``` **After:** ```erb <%# app/views/products/show.html.erb %> <h1><%= @product.name %></h1> <%= stream_react_component("ProductPage", props: { product: @product.as_json( include: { specs: { only: [:id, :label, :value] }, reviews: { only: [:id, :text, :rating] } }) }) %> ``` `stream_react_component` automatically sets `prerender: true`. The component renders identically — the difference is that the response is now streamed, which will matter when you start adding Suspense boundaries and async Server Components. React on Rails Pro automatically hydrates components early (before `DOMContentLoaded`), so selective hydration works out of the box. When the view uses React on Rails Pro async props, use the async-props helper variant instead. Keep synchronous values in `props:` and emit slower values from the block: ```erb <%= stream_react_component_with_async_props("ProductPage", props: { name: @product.name, price: @product.price }) do |emit| emit.call("reviews", @product.reviews.as_json(only: [:id, :text, :rating])) emit.call("recommendations", @product.recommended_products.as_json(only: [:id, :name, :price])) end %> ``` The Server Component receives `getReactOnRailsAsyncProp` and reads those emitted values behind Suspense boundaries. See [Data Fetching in React on Rails Pro](./rsc-data-fetching.md#data-fetching-in-react-on-rails-pro) for the complete async-props pattern. > [!IMPORTANT] > The block runs normal Ruby code sequentially, so `emit.call` does **not** parallelize slow queries by itself. For independent slow data sources, start the work concurrently before emitting values; see [Avoiding Server-Side Waterfalls](./rsc-data-fetching.md#avoiding-server-side-waterfalls). ### 6c. Update script loading in layouts (recommended) For streaming to deliver its full performance benefit, script tags should use `async` loading so the browser can hydrate components as they arrive: ```erb <%# app/views/layouts/application.html.erb %> <%= javascript_pack_tag('client-bundle', 'data-turbo-track': 'reload', async: true) %> ``` The `async: true` attribute enables React 18's Selective Hydration -- each component becomes interactive as soon as its code loads, without waiting for the entire page to finish streaming. If you use `auto_load_bundle` with Shakapacker >= 8.2.0 and React on Rails Pro, the `generated_component_packs_loading_strategy` already defaults to `:async`, so auto-generated pack tags are already configured correctly. ## Common Setup Mistakes These are the most frequent mistakes encountered during RSC infrastructure setup. Check this section if something isn't working after completing the steps above. ### Mistake 1: Wrong `react-on-rails-rsc` version Versions 19.0.0 through 19.0.3 vendored older builds of `react-server-dom-webpack` that are incompatible with React 19. Symptoms include cryptic rendering errors or RSC payloads that fail to deserialize on the client. **Fix:** Upgrade to `react-on-rails-rsc` 19.0.4 or later: ```bash yarn add react-on-rails-rsc@latest ``` ### Mistake 2: Forgetting the RSC bundle watcher in development After adding the RSC webpack config, you must also add a watcher process in `Procfile.dev`. Without it, the RSC bundle won't rebuild on file changes, and you'll see stale component output or errors about missing modules. **Symptom:** Changes to Server Components don't appear until you manually rebuild. Or, after removing `'use client'` from a component, it still behaves as a Client Component. **Fix:** Add the watcher line to `Procfile.dev`: ```text rails-rsc-assets: HMR=true RSC_BUNDLE_ONLY=true bin/shakapacker --watch ``` ### Mistake 3: Confusing `.server.jsx` with Server Components The `.server.jsx` file suffix is a **React on Rails auto-bundling convention** -- it means "include this file in the server bundle." It has nothing to do with React Server Components. **Symptom:** After enabling RSC, auto-bundled components with `.server.jsx` files break because the RSC infrastructure treats them as Server Components (they lack `'use client'`). **Fix:** Add `'use client'` to both `.client.jsx` and `.server.jsx` files during the initial setup (Step 5). Only remove it when you're ready to actually migrate that component to a Server Component. ### Mistake 4: Treating `clientReferences` as a static-page toggle Emptying `clientReferences` can make a purely static RSC page appear faster because there are no RSC client islands to hydrate. That workaround is unsafe as a shared app default: the same build may later render a `'use client'` component, but the manifest will not contain the reference needed to load its browser chunks. **Symptom:** Static RSC pages render, but a page with a client island fails with a missing-module manifest error, or the client island never hydrates after `clientReferences` was narrowed. **Fix:** Scope `clientReferences` to your app source directory instead of emptying it globally. If a temporary static-only build is required, document the affected routes and add a smoke test that renders at least one RSC client island for any build that is expected to support islands. See [Client Reference Scope and Empty `clientReferences`](rsc-troubleshooting.md#client-reference-scope-and-empty-clientreferences). ### Mistake 5: Mutating shared webpack config objects If your `serverWebpackConfig()` function returns the same object reference on repeated calls, `configureRsc()` will mutate the server config when modifying rules and resolve settings. **Symptom:** The server bundle behaves unexpectedly after adding the RSC bundle -- for example, it starts resolving `react-server` conditions or has the RSC loader in its chain. **Fix:** Ensure `serverWebpackConfig()` returns a fresh config object per call. If it doesn't, clone `module.rules` and `resolve` before mutating them in `configureRsc`. ### Mistake 6: Missing `react-server` condition in RSC bundle If you're writing a custom RSC webpack config (not following Step 4a exactly), forgetting to add `react-server` to `resolve.conditionNames` means React will use its standard server entry points instead of the RSC-specific ones. **Symptom:** Runtime errors in the RSC bundle, or Server Components that behave like Client Components. **Fix:** Add `conditionNames: ['react-server', '...']` to the RSC bundle's `resolve` config. ## Verification Checklist After completing all steps, verify everything works: - [ ] All three webpack bundles build without errors (client, server, RSC) - [ ] `react-client-manifest.json` and `react-server-client-manifest.json` are generated in your webpack output directory - [ ] `rsc-bundle.js` is generated in your `server_bundle_output_path` directory - [ ] The app starts without errors (`bin/dev` or equivalent) - [ ] Pages render identically to before the migration - [ ] If you narrowed `clientReferences`, at least one RSC route with a real Client Component still hydrates - [ ] The browser Network tab shows chunked transfer encoding on pages with `stream_react_component` - [ ] The `/rsc_payload/` route is accessible (returns an error like "component not found" for unknown components -- that's expected) If everything passes, your app is ready for RSC migration. The infrastructure is in place -- you can now begin converting components to Server Components by removing their `'use client'` directives and restructuring them, as described in the next guide. ## Next Steps - [Component Tree Restructuring Patterns](rsc-component-patterns.md) -- how to restructure your component tree for RSC, starting with the top-down migration strategy - [Context, Providers, and State Management](rsc-context-and-state.md) -- how to handle Context and global state - [Data Fetching Migration](rsc-data-fetching.md) -- migrating from useEffect to server-side fetching ================================================================================ PAGE: https://reactonrails.com/docs/migrating/rsc-component-patterns SOURCE: docs/oss/migrating/rsc-component-patterns.md ================================================================================ # RSC Migration: Component Tree Restructuring Patterns This guide covers how to restructure your React component tree when migrating to React Server Components. The core challenge: your existing components likely mix data fetching, state management, and rendering in ways that prevent them from being Server Components. This guide shows you how to untangle them. > **Part 2 of the [RSC Migration Series](migrating-to-rsc.md)** | Previous: [Preparing Your App](rsc-preparing-app.md) | Next: [Context and State Management](rsc-context-and-state.md) ## The Mental Model Shift In the RSC world, components are **Server Components by default**. You opt into client-side execution by adding `'use client'` at the top of a file. The key rule: > **`'use client'` operates at the module level, not the component level.** Once a file is marked `'use client'`, all its imports become part of the client bundle -- even if those imported components don't need client-side features. This means the placement of `'use client'` directly determines your bundle size. The goal of restructuring is to push `'use client'` as far down the component tree as possible, to leaf-level interactive elements. Keep this boundary separate from React on Rails file suffixes and RSC manifest discovery: - `.client.` and `.server.` suffixes decide which React on Rails bundle imports a file. - `'use client'` decides whether React treats that module as a Client Component boundary. - `clientReferences` decides which `'use client'` modules the RSC plugin can discover and emit into the client-reference manifests. Those three controls need to stay aligned. A `.server.jsx` file is not automatically a React Server Component, and an empty `clientReferences` list can hide a real Client Component from the manifest even when its `'use client'` boundary is placed correctly. For the setup details, see [Preparing Your App](rsc-preparing-app.md) and [Client Reference Scope and Empty `clientReferences`](rsc-troubleshooting.md#client-reference-scope-and-empty-clientreferences). ### `'use client'` Marks a Boundary, Not a Component Type A common misconception is that every component using hooks or browser APIs needs `'use client'`. It doesn't. You only need the directive at the **boundary** — the file where code transitions from server to client. Everything imported below that boundary is automatically client code: [Diagram: Static diagram showing how the 'use client' directive works at the module (file) level. Once a file has the directive, all its imports automatically become client code — no additional directive needed in child modules.] `SearchInput` and `SearchResults` use hooks and event handlers, but they don't need `'use client'` because `SearchBar` already established the boundary. Adding it would be redundant. ## The Top-Down Migration Strategy Start from the top of each component tree and work downward: [Diagram: Animated three-phase diagram showing RSC migration strategy: Phase 1 marks the root as 'use client' (100% client bundle), Phase 2 pushes the boundary down to child components (~40% client), Phase 3 splits mixed components into server+client leaves (~15% client). Each phase reveals progressively with staggered animation.] > **React on Rails multi-root note:** Unlike single-page apps with one root component, React on Rails renders multiple independent component trees on a page -- each `stream_react_component` call in your view is a separate root. This is actually an advantage for migration: you can migrate **one registered component at a time**, leaving the rest untouched. ### Phase 1: Mark All Entry Points as Client (already done) If you followed [Preparing Your App](rsc-preparing-app.md), this phase is already complete. Every registered component entry point has `'use client'`, so the RSC pipeline is active but all components are still Client Components. Ensure that your bundle root files (`client-bundle.js`, `server-bundle.js`) do **not** have a `'use client'` directive -- only the individual component files should. ### Phase 2: Pick a Component and Push the Boundary Down Choose one registered component to migrate. The ideal first candidate is a component that is mostly presentational -- heavy on layout and display, light on interactivity. **Step 1: Remove `'use client'` from the component entry point.** This makes it a Server Component. **Step 2: Update the registration.** When a component loses its `'use client'` directive, its registration must change: - **With `auto_load_bundle`:** This happens automatically. The generated pack switches from `ReactOnRails.register` to `registerServerComponent` based on whether the file has `'use client'`. For the full details on how auto-bundling classifies and registers RSC components, see [Auto-Bundling with React Server Components](../core-concepts/auto-bundling-file-system-based-automated-bundle-generation.md#auto-bundling-with-react-server-components). - **With manual registration:** The `registerServerComponent` API uses different import paths per bundle (`/server` vs `/client`). How you update registration depends on your current setup: **If you have a single bundle file** (e.g., `server-bundle.js` that imports and registers all components): ```js // server-bundle.js import registerServerComponent from 'react-on-rails-pro/registerServerComponent/server'; // Migrated component -- now a Server Component import ProductPage from '../components/ProductPage'; registerServerComponent({ ProductPage }); // Not yet migrated -- still Client Components import ReactOnRails from 'react-on-rails'; import CartPage from '../components/CartPage'; ReactOnRails.register({ CartPage }); ``` On the client side, create a separate entry point for each migrated component: ```js // ProductPage.client.js -- client entry point for the migrated component import registerServerComponent from 'react-on-rails-pro/registerServerComponent/client'; registerServerComponent('ProductPage'); ``` Add `ProductPage.client.js` as a client bundle entry point in your webpack config. **If each component has its own entry file** (e.g., `ProductPage.jsx` contains `ReactOnRails.register` and is used as a client bundle entry point): 1. **Remove** the `ReactOnRails.register` call from `ProductPage.jsx`. 2. **Create** `ProductPage.client.jsx` with the client-side registration: ```js // ProductPage.client.jsx -- replaces ProductPage.jsx as the client entry point import registerServerComponent from 'react-on-rails-pro/registerServerComponent/client'; registerServerComponent('ProductPage'); ``` 3. **In the server bundle**, import the component and register it: ```js // server-bundle.js (or a dedicated server entry file) import registerServerComponent from 'react-on-rails-pro/registerServerComponent/server'; import ProductPage from '../components/ProductPage'; registerServerComponent({ ProductPage }); ``` 4. **Update your client webpack config** to use `ProductPage.client.jsx` as the entry point instead of `ProductPage.jsx`. This preserves per-component chunking on the client side. **Step 3: Push `'use client'` down to interactive children.** Identify child components that don't use hooks or browser APIs. Those can stay as server-rendered. Add `'use client'` only to the children that need interactivity. [Diagram: Static before-and-after diagram showing how to migrate a React component tree by pushing the 'use client' directive from the root down to only the leaf components that truly need interactivity. Before: the entire tree is client code. After: only interactive leaves are client components.] Repeat for each registered component you want to migrate. ### Phase 3: Split Mixed Components Components that mix data fetching with interactivity need to be split into two parts. ## Pattern 1: Pushing State to Leaf Components The most common restructuring pattern. When a parent component has state that only a small part of the tree needs, extract the stateful part into a dedicated Client Component. ### Before: State at the top blocks everything ```jsx 'use client'; export default function ProductPage({ productId }) { const [product, setProduct] = useState(null); const [quantity, setQuantity] = useState(1); useEffect(() => { fetch(`/api/products/${productId}`) .then((res) => res.json()) .then(setProduct); }, [productId]); if (!product) return <Loading />; return ( <div> <h1>{product.name}</h1> <p>{product.description}</p> <ProductSpecs specs={product.specs} /> <ReviewList reviews={product.reviews} /> <div> <input type="number" value={quantity} onChange={(e) => setQuantity(Number(e.target.value))} /> <button onClick={() => addToCart(product.id, quantity)}>Add to Cart</button> </div> </div> ); } ``` ### After: State pushed to a leaf, data from Rails props ```erb <%# ERB view — Rails passes the data as props %> <%= stream_react_component("ProductPage", props: { product: @product.as_json( include: { specs: { only: [:id, :label, :value] }, reviews: { only: [:id, :text, :rating] } }) }) %> ``` ```jsx // ProductPage.jsx -- Server Component (no directive) export default function ProductPage({ product }) { return ( <div> <h1>{product.name}</h1> <p>{product.description}</p> <ProductSpecs specs={product.specs} /> <ReviewList reviews={product.reviews} /> <AddToCartButton productId={product.id} /> </div> ); } ``` ```jsx // AddToCartButton.jsx -- Client Component (interactive leaf) 'use client'; import { useState } from 'react'; import { addToCart } from '../api'; // Calls a Rails controller endpoint export default function AddToCartButton({ productId }) { const [quantity, setQuantity] = useState(1); return ( <div> <input type="number" value={quantity} onChange={(e) => setQuantity(Number(e.target.value))} /> <button onClick={() => addToCart(productId, quantity)}>Add to Cart</button> </div> ); } ``` **Result:** `ProductSpecs`, `ReviewList`, and all the product data rendering stay on the server. Only the add-to-cart interaction ships JavaScript to the client. ## Pattern 2: The Donut Pattern (Children as Props) When a Client Component needs to wrap Server Component content, use the `children` prop to create a "hole" in the client boundary. The Server Component content passes through without becoming client code. ### The Problem A modal needs client-side state to toggle visibility, but its content should be server-rendered: ```jsx // This would make Cart a Client Component (wrong!) 'use client'; import Cart from './Cart'; // Cart becomes client code via import chain export default function Modal() { const [isOpen, setIsOpen] = useState(false); return ( <div> <button onClick={() => setIsOpen(true)}>Open</button> {isOpen && <Cart />} </div> ); } ``` ### The Solution Use `children` to pass the Server Component through without importing it: ```jsx // Modal.jsx -- Client Component 'use client'; import { useState } from 'react'; export default function Modal({ children }) { const [isOpen, setIsOpen] = useState(false); return ( <div> <button onClick={() => setIsOpen(true)}>Open Cart</button> {isOpen && children} </div> ); } ``` ```jsx // Page.jsx -- Server Component (composes both) import Modal from './Modal'; import Cart from './Cart'; // Cart stays a Server Component export default function Page() { return ( <Modal> <Cart /> {/* Rendered on the server, passed through */} </Modal> ); } ``` **Why this works:** The Server Component (`Page`) is the "owner" -- it decides what `Cart` receives as props and renders it on the server. `Modal` receives pre-rendered content as `children`, not the component definition. ## Pattern 3: Extracting State into a Wrapper Component When a feature (like theme switching) requires state high in the tree, extract the stateful logic into a dedicated wrapper component so the rest of the tree stays server-rendered. ### Before: Theme state forces everything client-side ```jsx 'use client'; export default function Homepage() { const [theme, setTheme] = useState('light'); const colors = theme === 'light' ? LIGHT_COLORS : DARK_COLORS; return ( <body style={colors}> <Header /> <MainContent /> <Footer /> </body> ); } ``` ### After: Theme wrapper isolates state ```jsx // ColorProvider.jsx -- Client Component (state only) 'use client'; import { useState } from 'react'; export default function ColorProvider({ children }) { const [theme, setTheme] = useState('light'); const colors = theme === 'light' ? LIGHT_COLORS : DARK_COLORS; return <body style={colors}>{children}</body>; } ``` ```jsx // Homepage.jsx -- Server Component (owns the tree) import ColorProvider from './ColorProvider'; import Header from './Header'; import MainContent from './MainContent'; import Footer from './Footer'; export default function Homepage() { return ( <ColorProvider> <Header /> {/* Stays a Server Component */} <MainContent /> {/* Stays a Server Component */} <Footer /> {/* Stays a Server Component */} </ColorProvider> ); } ``` **Key insight:** `Homepage` (a Server Component) is the component that imports and renders `Header`, `MainContent`, and `Footer`. Since `Homepage` owns these children, they remain Server Components -- even though they're visually nested inside the Client Component `ColorProvider`. ## Pattern 4: Streaming with `stream_react_component` In React on Rails, `stream_react_component` uses React's `renderToPipeableStream` to stream rendered HTML to the browser as React processes the component tree. Rails loads all data synchronously and passes it as props: ```erb <%# ERB view — Rails passes all data as props %> <%= stream_react_component("Dashboard", props: { title: "Dashboard", stats: DashboardStats.compute.as_json, revenue: RevenueChart.data.as_json, orders: Order.recent.as_json }) %> ``` ```jsx // Dashboard.jsx -- Server Component export default function Dashboard({ title, stats, revenue, orders }) { return ( <div> <h1>{title}</h1> <Stats stats={stats} /> <RevenueChart revenue={revenue} /> <RecentOrders orders={orders} /> </div> ); } // Stats.jsx -- Server Component (renders directly from props) export default function Stats({ stats }) { return ( <div> <span>Revenue: {stats.revenue}</span> <span>Users: {stats.users}</span> </div> ); } ``` Rails loads all data as props before rendering begins. `stream_react_component` then streams the rendered HTML to the browser as React processes the component tree — no client-side fetching or loading states needed. For slow Rails data that should not block the initial shell, use `stream_react_component_with_async_props`; see [Data Fetching in React on Rails Pro](rsc-data-fetching.md#data-fetching-in-react-on-rails-pro). ## Pattern 5: Server Data to Interactive Client Components Pass server-fetched data from Rails to a Client Component that adds interactivity. The Server Component receives the data as props and passes it to the Client Component: ```erb <%# ERB view — Rails passes all data as props %> <%= stream_react_component("PostPage", props: { title: post.title, body: post.body, comments: post.comments.includes(:author).as_json }) %> ``` ```jsx // PostPage.jsx -- Server Component import Comments from './Comments'; export default function PostPage({ title, body, comments }) { return ( <article> <h1>{title}</h1> <p>{body}</p> <Comments comments={comments} /> </article> ); } ``` ```jsx // Comments.jsx -- Client Component (adds interactivity like reply buttons) 'use client'; import { useState } from 'react'; export default function Comments({ comments }) { const [expanded, setExpanded] = useState({}); return ( <ul> {comments.map((c) => ( <li key={c.id}> {c.text} <button onClick={() => setExpanded((prev) => ({ ...prev, [c.id]: !prev[c.id] }))}> {expanded[c.id] ? 'Collapse' : 'Reply'} </button> </li> ))} </ul> ); } ``` **Benefits:** The Server Component handles data display with zero JavaScript cost. The Client Component receives pre-fetched data as props and adds only the interactivity it needs (reply buttons, expand/collapse). ## Decision Guide: Server or Client Component? | Feature Needed | Component Type | Reason | | ------------------------------------------------- | -------------- | ------------------------------------- | | `useState`, `useReducer` | Client | State requires re-rendering | | `useEffect`, `useLayoutEffect` | Client | Lifecycle effects run in browser | | `onClick`, `onChange`, event handlers | Client | Events are browser-only | | `window`, `document`, `localStorage` | Client | Browser APIs | | Custom hooks using the above | Client | Transitively client | | Data fetching (database, API) | Server | Direct backend access, no bundle cost | | Rendering static/display-only content | Server\* | No JavaScript shipped | | Using server-only secrets (API keys) | Server | Never exposed to client | | Heavy dependencies (Markdown parsers, formatters) | Server | Dependencies stay off client bundle | _\*For components repeated many times with verbose markup (e.g., Tailwind utility classes), Server Component rendering can inflate the Flight payload. In those cases, a Client Component may produce a smaller page. See [Flight Payload Optimization](rsc-flight-payload.md) for details._ ## Common Mistakes ### Mistake 1: Adding `'use client'` too high ```jsx // BAD: Makes the entire layout client-side 'use client'; export default function Layout({ children }) { return ( <div> <nav> <Logo /> <SearchBar /> </nav> <main>{children}</main> <footer>...</footer> </div> ); } ``` ```jsx // GOOD: Only SearchBar is client-side export default function Layout({ children }) { return ( <div> <nav><Logo /><SearchBar /></nav> <main>{children}</main> <footer>...</footer> </div> ); } // SearchBar.jsx 'use client'; export default function SearchBar() { /* interactive logic */ } ``` ### Mistake 2: Importing Server Components in Client Components ```jsx // BAD: ServerComponent becomes a client component via import 'use client'; import ServerComponent from './ServerComponent'; export function ClientWrapper() { return <ServerComponent />; // This is now client code! } ``` ```jsx // GOOD: Pass Server Components as children 'use client'; export function ClientWrapper({ children }) { return <div>{children}</div>; } // In a Server Component parent: <ClientWrapper> <ServerComponent /> {/* Stays a Server Component */} </ClientWrapper>; ``` ### Mistake 3: Chunk contamination from shared `'use client'` files If your RSC page downloads unexpectedly large chunks, a shared `'use client'` component may accumulate chunks from multiple entry paths (including heavy SSR/client paths with unrelated dependencies). This can cause the browser to download hundreds of kilobytes of JavaScript it doesn't need. See [Chunk Contamination](rsc-troubleshooting.md#chunk-contamination) for wrapper and prop-injection fixes. ### Mistake 4: Emptying `clientReferences` for a mixed RSC app A static RSC route with no client islands may still render when `clientReferences` is empty, but a mixed app can fail later when another route adds a real Client Component. Treat an empty list as a static-only build constraint, not a general restructuring pattern. Browser sidecars do not change this rule. A sidecar is plain browser JavaScript outside the RSC payload; its success does not prove the RSC client-reference manifest can hydrate future client islands. Keep sidecar behavior separate from RSC client boundaries, and smoke-test at least one RSC route with a real Client Component whenever `clientReferences` is narrowed. See [Client Reference Scope and Empty `clientReferences`](rsc-troubleshooting.md#client-reference-scope-and-empty-clientreferences) for the decision table and detection steps. ### Mistake 5: Confusing `'use client'` with `'use server'` - `'use client'` marks a file's components as **Client Components** - `'use server'` marks **Server Actions** (functions callable from the client) -- NOT Server Components - Server Components are the **default** and need no directive > **React on Rails note:** Server Actions (`'use server'`) are **not supported** in React on Rails. Server Actions run on the Node renderer, which has no access to Rails models, sessions, cookies, or CSRF protection. Use Rails controllers for all mutations. See [Mutations: Rails Controllers, Not Server Actions](rsc-data-fetching.md#mutations-rails-controllers-not-server-actions). ## Next Steps - [Context, Providers, and State Management](rsc-context-and-state.md) -- how to handle Context and global state - [Data Fetching Migration](rsc-data-fetching.md) -- migrating from useEffect to server-side fetching - [Third-Party Library Compatibility](rsc-third-party-libs.md) -- dealing with incompatible libraries - [Troubleshooting and Common Pitfalls](rsc-troubleshooting.md) -- debugging and avoiding problems ================================================================================ PAGE: https://reactonrails.com/docs/migrating/rsc-context-and-state SOURCE: docs/oss/migrating/rsc-context-and-state.md ================================================================================ # RSC Migration: Context, Providers, and State Management React Context is one of the biggest migration challenges when adopting RSC. Server Components cannot create or consume Context -- they have no access to `createContext`, `useContext`, or any Context provider. This guide covers the patterns for handling Context, providers, and global state in an RSC world. > **Part 3 of the [RSC Migration Series](migrating-to-rsc.md)** | Previous: [Component Tree Restructuring](rsc-component-patterns.md) | Next: [Data Fetching Migration](rsc-data-fetching.md) ## Why Context Doesn't Work in Server Components Context relies on React's re-rendering mechanism. When a Context value changes, all consumers re-render. Server Components render once on the server and produce static output -- they never re-render. This makes Context fundamentally incompatible with Server Components. **What happens if you try:** ```jsx // This will throw an error import { useContext } from 'react'; import { ThemeContext } from './theme'; export default function ServerComponent() { const theme = useContext(ThemeContext); // ERROR: Cannot use useContext in Server Component return <div className={theme}>...</div>; } ``` ## Pattern 1: Client Component Provider Wrapper The most important pattern for Context migration. Create a `'use client'` wrapper component that provides context, and use `children` to pass Server Component content through it. ### Theme Provider Example ```jsx // theme-provider.jsx 'use client'; import { createContext, useState, useContext } from 'react'; const ThemeContext = createContext({ theme: 'light', setTheme: () => {} }); export function useTheme() { return useContext(ThemeContext); } export default function ThemeProvider({ children }) { const [theme, setTheme] = useState('light'); // React 19: <Context value={...}> replaces <Context.Provider value={...}> return <ThemeContext value={{ theme, setTheme }}>{children}</ThemeContext>; } ``` ```jsx // ProductPage.jsx -- Server Component (registered with registerServerComponent) import ThemeProvider from './theme-provider'; import ProductDetails from './ProductDetails'; export default function ProductPage(props) { return ( <ThemeProvider> <ProductDetails product={props.product} /> {/* Server Component passes through unchanged */} </ThemeProvider> ); } ``` **Why this works:** The Server Component (`ProductPage`) renders `ThemeProvider` as a Client Component, passing Server Component children through it. The children are rendered on the server and passed as pre-rendered content -- they don't become Client Components. **Best practice:** Render providers as deep as possible in the tree. Keep components that don't need context outside the provider wrapper. ## Pattern 2: Composing Multiple Providers Real applications need many providers (theme, auth, i18n, query client). Create a single composed provider to avoid "provider hell": ```jsx // providers.jsx 'use client'; import { QueryClient, QueryClientProvider } from '@tanstack/react-query'; import { useState } from 'react'; import AuthProvider from './auth-provider'; import ThemeProvider from './theme-provider'; export default function Providers({ children, user }) { const [queryClient] = useState(() => new QueryClient()); return ( <AuthProvider user={user}> <QueryClientProvider client={queryClient}> <ThemeProvider>{children}</ThemeProvider> </QueryClientProvider> </AuthProvider> ); } ``` ```erb <%# ERB view — Rails passes the data as props %> <%= stream_react_component("ProductPage", props: { user: current_user.as_json(only: [:id, :name]), product: @product.as_json( include: { specs: { only: [:id, :label, :value] }, reviews: { only: [:id, :text, :rating] } }) }) %> ``` ```jsx // ProductPage.jsx -- Server Component (registered with registerServerComponent) import Providers from './providers'; import Header from './components/Header'; import Footer from './components/Footer'; import ProductDetails from './components/ProductDetails'; export default function ProductPage({ user, product }) { return ( <div> <Header /> {/* Server Component -- outside providers */} <Providers user={user}> <ProductDetails product={product} /> </Providers> <Footer /> {/* Server Component -- outside providers */} </div> ); } ``` **Key insight:** Components that don't need context (static header, footer) stay **outside** the provider wrapper, keeping them as Server Components with zero JavaScript cost. ## Pattern 3: Streaming HTML Delivery > **Note:** This section covers a cross-cutting concern (data fetching via `stream_react_component`) that affects how you structure context and state. For the full treatment of data fetching patterns, see [Data Fetching Migration](rsc-data-fetching.md). In React on Rails, data comes from Rails as props. Rails loads all data synchronously in the controller and passes it to `stream_react_component`, which streams the rendered HTML to the browser as React processes the component tree. ```erb <%= stream_react_component("ProductPage", props: { name: product.name, price: product.price, reviews: product.reviews .as_json(only: [:id, :text, :rating]), recommendations: RecommendationService.for(product) .as_json(only: [:id, :name, :price]) }) %> ``` The component renders with all data available as props. `stream_react_component` streams the HTML to the browser as React processes the component tree: ```jsx // ProductPage.jsx -- Server Component export default function ProductPage({ name, price, reviews, recommendations }) { return ( <div> <h1>{name}</h1> <p>${price}</p> <ReviewList reviews={reviews} /> <RecommendationList items={recommendations} /> </div> ); } function ReviewList({ reviews }) { return ( <ul> {reviews.map((r) => ( <li key={r.id}>{r.text}</li> ))} </ul> ); } ``` All data is loaded in Rails before rendering begins. `stream_react_component` then streams the rendered HTML to the browser via React's `renderToPipeableStream`. For slow Rails data that should not block the initial shell, use `stream_react_component_with_async_props` instead; see [Data Fetching in React on Rails Pro](rsc-data-fetching.md#data-fetching-in-react-on-rails-pro). > **Note:** `React.cache()` is only available in React Server Component environments. It is not available in client components or non-RSC server rendering (e.g., `renderToString`). > For more streaming patterns and examples, see [Data Fetching in React on Rails Pro](rsc-data-fetching.md#data-fetching-in-react-on-rails-pro). ## Migrating Global State Libraries ### Redux Toolkit The key rule for RSC: **Server Components must NOT read or write the Redux store.** Only Client Components interact with Redux. This is straightforward in React on Rails because your component's client/server split is explicit. React on Rails provides two Redux patterns. Both continue to work with RSC as long as Redux access stays in Client Components: **Pattern 1: Shared store (`registerStore` + `redux_store` helper)** If you use `ReactOnRails.registerStore()` with the `redux_store` view helper, no changes are needed for Client Components. The framework already creates a fresh store per request (store generators receive `(props, railsContext)` and return a new store instance). Client Components continue using `ReactOnRails.getStore()` and `<Provider>` as before. ```jsx // ReduxApp.client.jsx -- Client Component (unchanged) 'use client'; import { Provider } from 'react-redux'; import ReactOnRails from 'react-on-rails/client'; import MyComponent from './MyComponent'; export default () => { const store = ReactOnRails.getStore('MyStore'); return ( <Provider store={store}> <MyComponent /> </Provider> ); }; ``` When you migrate a component to a Server Component, use the donut pattern -- a Client Component `<Provider>` at the root with Server Components passed as `children`: ```jsx // ReduxProvider.jsx -- Client Component (the "donut") 'use client'; import { Provider } from 'react-redux'; import ReactOnRails from 'react-on-rails/client'; export default function ReduxProvider({ children }) { const store = ReactOnRails.getStore('MyStore'); return <Provider store={store}>{children}</Provider>; } ``` ```jsx // ProductPage.jsx -- Server Component (migrated, receives product as Rails prop) import ReduxProvider from './ReduxProvider'; import ProductSpecs from './ProductSpecs'; import AddToCartButton from './AddToCartButton'; export default function ProductPage({ product }) { return ( <ReduxProvider> <h1>{product.name}</h1> {/* Server-rendered */} <ProductSpecs product={product} /> {/* Server Component */} <AddToCartButton product={product} /> {/* Client Component -- uses useDispatch */} </ReduxProvider> ); } ``` Server Components pass through the `<Provider>` unchanged (they don't consume the store). Client Components deeper in the tree (like `AddToCartButton`) can use `useSelector` and `useDispatch` as usual. **Pattern 2: Per-component store (render function with `useMemo`)** If your component creates its own store from props (the pattern used by the React on Rails generator), it already works -- the component is a Client Component with `'use client'`: ```jsx // HelloWorldApp.client.jsx 'use client'; import { useState } from 'react'; import { Provider } from 'react-redux'; import configureStore from '../store/helloWorldStore'; import HelloWorldContainer from '../containers/HelloWorldContainer'; export default function HelloWorldApp(props) { // useState ensures the store is only created once (on mount), even though // props is a new object reference on every render. const [store] = useState(() => configureStore(props)); return ( <Provider store={store}> <HelloWorldContainer /> </Provider> ); } ``` **What RSC changes for Redux:** With Server Components, only the props that Client Components actually need get serialized into the HTML. Previously, all props passed via `react_component` were encoded in the page for hydration -- even data only used for display. Now, Server Components consume display-only data on the server (it never reaches the client), so you should pass only the interactive state your Client Components need into the `<ReduxProvider>`. This reduces the HTML page size and the amount of data the browser must parse. ### Zustand and Jotai Zustand and Jotai follow the same pattern as Redux: keep all store access in Client Components. Both are lighter-weight alternatives that work well with RSC because they don't require a `<Provider>` wrapper (Zustand) or use a minimal one (Jotai). Wrap store-consuming components with `'use client'` and pass server-fetched data as initial values via props. See the [compatibility matrix](rsc-third-party-libs.md#library-compatibility-decision-matrix) for version requirements. ### General State Management Guidance RSC reduces the need for global state libraries because data fetching moves to the server: | Use Case | Recommended Approach | | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | Server data (read-only display) | Rails controller props → Server Component renders directly | | Server data (slow, shouldn't block the shell) | [Async props](rsc-data-fetching.md#data-fetching-in-react-on-rails-pro) with `stream_react_component_with_async_props` | | Server data (with client cache/revalidation) | TanStack Query with prefetch + hydrate | | Client UI state (modals, forms, selections) | `useState` / Context in Client Components | | Complex client state (undo/redo, shared across many components) | Redux Toolkit in Client Components | ## Specific Provider Patterns ### Auth Provider In React on Rails, auth data typically comes from the Rails controller as props. The controller has access to the session, cookies, and your authentication system (Devise, etc.) -- pass the current user to the component: ```ruby # app/controllers/dashboard_controller.rb class DashboardController < ApplicationController include ReactOnRailsPro::Stream def show stream_view_containing_react_components(template: "dashboard/show") end helper_method :dashboard_props def dashboard_props { user: current_user&.as_json(only: [:id, :name, :email, :role]) } end end ``` ```erb <%# app/views/dashboard/show.html.erb %> <%= stream_react_component("Dashboard", props: dashboard_props, prerender: true) %> ``` ```jsx // Dashboard.jsx -- Server Component (registered with registerServerComponent) import AuthProvider from './auth-provider'; export default function Dashboard({ user }) { return ( <AuthProvider user={user}> <DashboardContent /> </AuthProvider> ); } ``` **Key advantage over client-side auth:** The Rails controller handles authentication and authorization before the component ever renders. `HttpOnly` session cookies never touch JavaScript. The component receives only the serialized user data it needs. ### Theme Provider (No Flash of Wrong Theme) For server-side theme rendering without flicker, read the theme preference in the Rails controller and pass it as a prop: ```ruby # app/controllers/application_controller.rb def theme_preference cookies[:theme] || current_user&.theme_preference || 'light' end ``` ```erb <%# app/views/layouts/application.html.erb %> <html class="<%= theme_preference %>"> <body> <%= yield %> </body> </html> ``` The correct CSS class is applied during the initial HTML response from Rails -- no flash of the wrong theme on initial load. A Client Component can update the cookie (via a `fetch` call or form submission) when the user toggles themes. If your React components also need the theme value, pass it as a prop: ```erb <%= stream_react_component("App", props: { theme: theme_preference, ... }) %> ``` ### i18n Provider Internationalization in React on Rails typically uses Rails I18n on the server side and `react-intl` for Client Components. The challenge with RSC is that `react-intl`'s `useIntl()` hook and `<FormattedMessage>` component require React Context, which is unavailable in Server Components. > **Two i18n systems:** React on Rails has a [build-time locale system](../building-features/i18n.md) (`config.i18n_dir`) that compiles Rails YAML translations into JSON/JS files with flat dot-separated keys (e.g., `"product.title"`). The controller-props approach below passes translations at request time with whatever key structure you choose. Both are valid — see the comparison below. #### Passing translations from Rails ```ruby # app/controllers/application_controller.rb helper_method :i18n_props def i18n_props { locale: I18n.locale.to_s, # IMPORTANT: I18n.t('.') returns the ENTIRE translation tree for the locale, # which can be thousands of keys. For production, pass only the subset needed: messages: I18n.t('product_page').deep_stringify_keys, } end ``` #### Server Components: plain string lookup (limited) The simplest approach is to read translation values directly from the messages object: ```jsx // ProductPage.jsx -- Server Component export default function ProductPage({ locale, messages, ...props }) { const title = messages['title']; return <h1>{title}</h1>; } ``` > **Limitation:** This only works for **plain strings** — text with no interpolation, pluralization, or number/date formatting. React on Rails' build-time locale system converts Rails `%{variable}` placeholders to ICU `{variable}` syntax, so `messages['greeting']` would render the literal text `{name}` instead of a substituted value. For anything beyond plain strings, use `createIntl` from `react-intl/server` (described below). #### Server Components: `createIntl` from `react-intl/server` (recommended) Import `createIntl` from `react-intl/server` — the official server-safe subpath export (added in react-intl v8.2.0) that provides full interpolation, pluralization, and date/number formatting without the `'use client'` directive. This is the recommended approach for i18n in Server Components. > [!TIP] > When multiple Server Components need the same intl instance, wrap `createIntl` in `React.cache()` to avoid recreating it in every component. See [Sharing Per-Request Data in Server Components](../../pro/react-server-components/per-request-data.md) for the complete pattern with `React.cache()`, including i18n, auth, feature flags, and other per-request scenarios. ```jsx // ProductPage.jsx -- Server Component import { createIntl, createIntlCache } from 'react-intl/server'; import I18nProvider from './I18nProvider'; // Module-level cache — safe because it only caches Intl constructors, not request data const cache = createIntlCache(); export default function ProductPage({ locale, messages, ...props }) { const intl = createIntl({ locale, messages }, cache); return ( <div> {/* Full formatting works in Server Components */} <h1>{intl.formatMessage({ id: 'greeting' }, { name: props.userName })}</h1> <p>{intl.formatNumber(props.price, { style: 'currency', currency: 'USD' })}</p> <p>{intl.formatMessage({ id: 'items_count' }, { count: props.itemCount })}</p> <I18nProvider locale={locale} messages={messages}> <InteractiveFilters /> {/* Client Component can use useIntl() */} </I18nProvider> </div> ); } ``` > **Note:** `createIntl` is a plain function call — no hooks, no Context, no `'use client'` needed. The `createIntlCache()` call avoids recreating expensive `Intl.NumberFormat` / `Intl.DateTimeFormat` instances on every request. The cache stores only `Intl` constructor instances keyed by format options — no locale data, messages, or user-specific information — so it is safe to share at module scope across all concurrent requests for the lifetime of the Node.js process. #### Client Components: `IntlProvider` + `useIntl()` Client Components use the standard `react-intl` Context pattern: ```jsx // I18nProvider.jsx 'use client'; import { IntlProvider } from 'react-intl'; export default function I18nProvider({ locale, messages, children }) { return ( <IntlProvider locale={locale} messages={messages}> {children} </IntlProvider> ); } ``` ```jsx // InteractiveFilters.jsx -- Client Component 'use client'; import { useIntl } from 'react-intl'; export default function InteractiveFilters() { const intl = useIntl(); return <button>{intl.formatMessage({ id: 'filters.apply' })}</button>; } ``` #### Build-time vs controller-props: when to use each | Approach | Source | Key format | Best for | | ------------------------------ | -------------------------- | ------------------------------- | --------------------------------------------------------------------------------------- | | Build-time (`config.i18n_dir`) | YAML → compiled JSON/JS | Flat: `"product.title"` | Static translations shared across pages; client-side `react-intl` with `defineMessages` | | Controller-props (`I18n.t`) | Rails I18n at request time | Flat (required by `createIntl`) | Page-specific translations; RSC `createIntl` with `React.cache()` | Both can be used together — for example, build-time translations for the client bundle and controller-props for Server Component content. See the [Internationalization guide](../building-features/i18n.md) for build-time setup details. ## Common Mistakes ### Mistake 1: Wrapping the entire tree in providers unnecessarily Wrapping the entire component tree in a `'use client'` provider works correctly -- children passed from a Server Component remain Server Components (this is the "children as props" pattern). However, wrapping more than necessary has real costs: - Every child that **consumes** the context (via `useContext`) must be a Client Component - Provider scope is broader than needed, making refactoring harder - Context value changes trigger re-renders across a wider subtree Narrow the provider scope to only the subtree that actually needs the context: ```jsx // WIDER THAN NEEDED: Header and Footer don't use this context, // but they're inside the provider scope unnecessarily export default function ProductPage({ user, product }) { return ( <Providers user={user}> <Header /> <ProductDetails product={product} /> <Footer /> </Providers> ); } ``` ```jsx // BETTER: Only wrap components that actually need context export default function ProductPage({ user, product }) { return ( <div> <Header /> {/* Server Component -- outside provider scope */} <Providers user={user}> <ProductDetails product={product} /> </Providers> <Footer /> {/* Server Component -- outside provider scope */} </div> ); } ``` ### Mistake 2: Passing the entire I18n translation tree `I18n.t('.')` returns every translation key for the locale, which can be thousands of entries. Serializing this into props bloats the HTML page and the RSC payload: ```ruby # BAD: Sends the entire translation tree (potentially hundreds of KB) messages: I18n.t('.').deep_stringify_keys # GOOD: Send only the subset this page needs messages: I18n.t('product_page').deep_stringify_keys ``` ### Mistake 3: Using `messages['key']` for translations with placeholders The build-time locale system converts Rails `%{variable}` placeholders to ICU `{variable}` syntax. Reading these directly from the messages object renders the literal placeholder text: ```jsx // BAD: Renders "Hello, {name}" as literal text const greeting = messages['greeting']; ``` ```jsx // GOOD: Use createIntl to format with variable substitution import { createIntl, createIntlCache } from 'react-intl/server'; const cache = createIntlCache(); const intl = createIntl({ locale, messages }, cache); const greeting = intl.formatMessage({ id: 'greeting' }, { name: 'John' }); ``` ### Mistake 4: Reading Redux store in Server Components Server Components render once on the server and never re-render. They cannot subscribe to store changes: ```jsx // BAD: useSelector is a hook -- breaks in Server Components export default function Dashboard({ user }) { const theme = useSelector((state) => state.theme); // ERROR return <div className={theme}>...</div>; } ``` **Fix:** Keep the component as a Client Component (add `'use client'`), or pass the value from Rails as a prop to a Server Component that doesn't need the Redux store. ### Mistake 5: Creating new QueryClient on every render If the `QueryClient` is created without `useState`, React creates a new instance on every render, losing the cache: ```jsx // BAD: New QueryClient on every render -- cache is lost 'use client'; export default function QueryProvider({ children }) { const queryClient = new QueryClient(); // Re-created each render! return <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>; } // GOOD: useState ensures single instance 'use client'; import { useState } from 'react'; export default function QueryProvider({ children }) { const [queryClient] = useState(() => new QueryClient()); return <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>; } ``` ## Migration Checklist ### Phase 1: Audit 1. List all Context providers in your app 2. Categorize each by type: - **Client-only state** (UI state, modals, form state): Keep as Context in Client Components - **Server data** (user profile, config, feature flags): Move to server-side fetching - **Hybrid** (auth session, locale): Fetch on server, provide via Client Component ### Phase 2: Extract Providers 3. Create a `providers.jsx` file marked with `'use client'` 4. Move all context providers into this file 5. Import the composed provider into each registered Server Component that needs it 6. Pass server-fetched data (from Rails controller props) into the provider ### Phase 3: Replace Server-Side Context Usage 7. Replace `useContext` in data-fetching components with Rails controller props 8. For data shared between Server and Client Components, pass data directly as props (no Context needed) 9. Remove Context providers that only existed to pass server data down the tree ### Phase 4: State Management Libraries 10. Remove store reads/writes from Server Components 11. Move `<Provider>` wrapping into Client Component children when the parent becomes a Server Component 12. Consider reducing state library usage -- data previously fetched client-side and stored in Redux can now come directly from Rails controller props ## Next Steps - [Data Fetching Migration](rsc-data-fetching.md) -- migrating from useEffect to server-side fetching - [Third-Party Library Compatibility](rsc-third-party-libs.md) -- dealing with incompatible libraries - [Troubleshooting and Common Pitfalls](rsc-troubleshooting.md) -- debugging and avoiding problems ================================================================================ PAGE: https://reactonrails.com/docs/migrating/rsc-data-fetching SOURCE: docs/oss/migrating/rsc-data-fetching.md ================================================================================ # RSC Migration: Data Fetching Patterns This guide covers how to migrate your data fetching from client-side patterns (`useEffect` + `fetch`, React Query, SWR) to Server Component patterns. In React on Rails, data flows from Rails to your components as props — eliminating the need for loading states, error handling boilerplate, and client-side caching in many cases. > **Part 4 of the [RSC Migration Series](migrating-to-rsc.md)** | Previous: [Context and State Management](rsc-context-and-state.md) | Next: [HTTP Response Ownership](rsc-http-response-patterns.md) ## The Core Shift: From Client-Side Fetching to Server-Side Data In the traditional React model, components fetch data on the client after mounting. In the RSC model, data arrives from the server as props — the component simply renders it. ### Before: Client-Side Fetching ```jsx 'use client'; import { useState, useEffect } from 'react'; export default function UserProfile({ userId }) { const [user, setUser] = useState(null); const [loading, setLoading] = useState(true); const [error, setError] = useState(null); useEffect(() => { fetch(`/api/users/${userId}`) .then((res) => res.json()) .then((data) => { setUser(data); setLoading(false); }) .catch((err) => { setError(err); setLoading(false); }); }, [userId]); if (loading) return <Spinner />; if (error) return <ErrorMessage error={error} />; return <div>{user.name}</div>; } ``` ### After: Server Component with Async Props ```jsx // UserPage.jsx -- Server Component (no directive needed) import { Suspense } from 'react'; export default function UserPage({ getReactOnRailsAsyncProp }) { return ( <Suspense fallback={<Spinner />}> <UserProfile userPromise={getReactOnRailsAsyncProp('user')} /> </Suspense> ); } async function UserProfile({ userPromise }) { const user = await userPromise; return <div>{user.name}</div>; } ``` Rails streams the data through async props using `stream_react_component_with_async_props`. The component uses `getReactOnRailsAsyncProp` to obtain data as a Promise, and `<Suspense>` handles loading states — no client-side fetching, no `useState`, no `useEffect`. **What changed:** - No `useState` for data, loading, or error - No `useEffect` lifecycle management - No `'use client'` directive - Data comes from Rails via async props — no client-side fetching - `<Suspense>` replaces manual loading/error checks - No JavaScript ships to the client for this component [Diagram: Side-by-side comparison showing client-side fetching requiring an extra API round trip after mount versus Server Component pattern where Rails streams data via async props — no extra round trips, no client state management, Suspense handles loading.] For pages with multiple data sources, use [`stream_react_component`](#data-fetching-in-react-on-rails-pro) to stream the rendered HTML to the browser as React renders the component tree. When slower data sources should resolve independently behind Suspense boundaries, use `stream_react_component_with_async_props`. ## Data Fetching in React on Rails Pro In React on Rails applications, Ruby on Rails is the backend. Rather than bypassing Rails to access the database directly from Server Components, React on Rails Pro provides **`stream_react_component`** -- a streaming view helper that uses React's `renderToPipeableStream` to stream rendered HTML to the browser as React processes the component tree. For ordinary Rails-provided props, pass the data through the helper's `props:` option. For slow or independent props that should resolve behind Suspense boundaries, use the async-props helper variant, **`stream_react_component_with_async_props`**. The helper block receives an emitter; call `emit.call(prop_name, value)` as each async prop becomes available. The Server Component reads emitted values with the injected `getReactOnRailsAsyncProp` prop. This is the recommended data fetching pattern for React on Rails because: - It preserves Rails' controller/model/view architecture - It leverages Rails' existing data access layers (ActiveRecord, authorization, caching) - It supports streaming SSR — HTML streams to the browser as React renders - Data passes through Rails-provided props or async props -- no client-side fetching needed > [!NOTE] > Server Components rendered through the node renderer do not automatically receive host Node.js globals such as `fetch`, `Headers`, `Request`, `Response`, `AbortController`, or `AbortSignal`. To make HTTP calls from a Server Component: > > - **Prefer props**: pass Rails-owned data from the controller and avoid HTTP entirely. > - **Bundle an HTTP client**: import `node-fetch` v2 (CJS) or a compatible `undici` version in component code so the bundler includes it. > - **Inject via `additionalContext`**: expose the host's fetch globals or a polyfill at renderer startup. > > See [Node Renderer Runtime Globals](../building-features/node-renderer/js-configuration.md#runtime-globals-for-ssr-and-rsc). ### How Streaming Works **Rails view (ERB), synchronous props:** ```erb <%= stream_react_component("ProductPage", props: { name: product.name, price: product.price, reviews: product.reviews .as_json(only: [:id, :text, :rating]) }) %> ``` **Rails view (ERB), async props:** ```erb <%= stream_react_component_with_async_props("ProductPage", props: { name: product.name, price: product.price }) do |emit| emit.call("reviews", product.reviews.as_json(only: [:id, :text, :rating])) end %> ``` > [!IMPORTANT] > The emitter block runs normal Ruby code sequentially, so `emit.call` does **not** parallelize slow queries by itself. For independent slow data sources, start the work concurrently before emitting values; see [Avoiding Server-Side Waterfalls](#avoiding-server-side-waterfalls). **See also:** [React on Rails Pro streaming SSR](../../pro/streaming-ssr.md) for setup instructions and configuration options. **React component for synchronous props (Server Component):** Use this version with the `stream_react_component` ERB helper above. Rails resolves every prop before rendering begins, including `reviews`. ```tsx type Review = { id: number; text: string; rating: number; }; type ProductPageProps = { name: string; price: number; reviews: Review[]; }; export default function ProductPage({ name, price, reviews }: ProductPageProps) { return ( <div> <h1>{name}</h1> <p>${price}</p> <ReviewList reviews={reviews} /> </div> ); } function ReviewList({ reviews }: { reviews: Review[] }) { return ( <ul> {reviews.map((review) => ( <li key={review.id}> {review.text} ({review.rating}/5) </li> ))} </ul> ); } ``` **React component for async props (Server Component):** Use this version with the `stream_react_component_with_async_props` ERB helper above. Keep the registered component name as `ProductPage`; the props shape changes so `reviews` comes from `getReactOnRailsAsyncProp`. `WithAsyncProps<AsyncProps, SyncProps>` combines the props passed directly through `props:` with a typed accessor for the keys emitted from Rails. This first async-props snippet is intentionally single-prop so it mirrors the synchronous example; the full two-prop version appears in [Async Props](#async-props-stream-each-slow-prop-independently). ```tsx import { Suspense } from 'react'; import type { WithAsyncProps } from 'react-on-rails-pro'; type Review = { id: number; text: string; rating: number; }; type SyncProps = { name: string; price: number; }; type AsyncProps = { reviews: Review[]; }; type ProductPageProps = WithAsyncProps<AsyncProps, SyncProps>; function ReviewList({ reviews }: { reviews: Review[] }) { return ( <ul> {reviews.map((review) => ( <li key={review.id}> {review.text} ({review.rating}/5) </li> ))} </ul> ); } async function AsyncReviewList({ reviewsPromise }: { reviewsPromise: Promise<Review[]> }) { // This awaits a Promise injected by getReactOnRailsAsyncProp, not a direct data fetch. return <ReviewList reviews={await reviewsPromise} />; } export default function ProductPage({ name, price, getReactOnRailsAsyncProp }: ProductPageProps) { const reviewsPromise = getReactOnRailsAsyncProp('reviews'); return ( <div> <h1>{name}</h1> <p>${price}</p> <Suspense fallback={<p>Loading reviews...</p>}> <AsyncReviewList reviewsPromise={reviewsPromise} /> </Suspense> </div> ); } ``` > [!IMPORTANT] > `<Suspense>` is the loading boundary, not the error UI. If the async-props stream closes before a requested prop is emitted, `getReactOnRailsAsyncProp` rejects and follows the same RSC/streaming error path as other Server Component render errors. Use the page-level handling described in [Error Boundary Limitations](./rsc-troubleshooting.md#error-boundary-limitations) rather than treating the Suspense fallback as failure UI. **How it works:** 1. Rails evaluates synchronous `props:` for `stream_react_component`, or passes those synchronous `props:` to `stream_react_component_with_async_props` while the block emits slower values with `emit.call` 2. The streaming helper uses React's `renderToPipeableStream` for streaming SSR 3. `getReactOnRailsAsyncProp('reviews')` returns a Promise that resolves when Rails calls `emit.call("reviews", ...)` 4. HTML streams to the browser as React renders the component tree 5. No client-side fetching or `useEffect`-based loading state needed 6. The component renders with zero JavaScript cost as a Server Component With async props, `stream_react_component_with_async_props` starts rendering with the synchronous `props:` values, then the block emits slow values with `emit.call`. The Server Component uses `getReactOnRailsAsyncProp` to obtain those values as Promises and places them behind Suspense boundaries. > **HTML streaming vs. progressive data streaming:** With synchronous props, all data is loaded in Rails before rendering begins. The streaming here is _HTML streaming_ — React sends rendered HTML to the browser as it processes the component tree, rather than waiting for the entire page to finish rendering. For progressive data streaming where slow data sources resolve independently via Suspense boundaries, see [Async props](#async-props-stream-each-slow-prop-independently) below; for the underlying SSR setup (Rack middleware, streaming controller), see [Streaming SSR](../../pro/streaming-ssr.md). > > **More details:** For setup instructions and configuration options, see the [React on Rails Pro RSC documentation](../../pro/react-server-components/tutorial.md). ### Async Props: Stream Each Slow Prop Independently {#async-props-stream-each-slow-prop-independently} The synchronous example above loads every prop in the controller before React starts rendering. When one data source is slow (a recommendations service, an expensive aggregate), it holds up the whole render. **Async props** let Rails send the fast props immediately and stream each slow prop to the browser as it resolves, so React shows the shell and fills in each `<Suspense>` boundary independently. [Diagram: How async props work in React on Rails] Use `stream_react_component_with_async_props` and emit each slow prop from the block. The fast props go in `props:`; each `emit.call(name, value)` streams one more prop as soon as Rails has it: > [!NOTE] > **Prerequisites:** the controller must `include ReactOnRailsPro::Stream` and render the view via `stream_view_containing_react_components`, and `config.enable_rsc_support = true` must be set in your React on Rails initializer. If either prerequisite is missing, the helpers raise explicit setup errors: `stream_react_component_with_async_props` raises `ReactOnRailsPro::Error` when `config.enable_rsc_support` is false, and `consumer_stream_async` raises `ReactOnRails::Error` when `stream_view_containing_react_components` was not called. ```erb <%= stream_react_component_with_async_props("ProductPage", props: { name: product.name, price: product.price }) do |emit| # Each emit.call streams a prop to the browser the moment Rails has it. emit.call("reviews", product.reviews.as_json(only: [:id, :text, :rating])) emit.call("recommendations", product.recommended_products.as_json(only: [:id, :name, :price])) end %> ``` On the React side, the component receives a `getReactOnRailsAsyncProp` helper alongside its synchronous props. Calling it returns a Promise for that prop; wrap the consumer in `<Suspense>` so React streams it in when Rails emits it: ```tsx import { Suspense } from 'react'; import type { WithAsyncProps } from 'react-on-rails-pro'; type Review = { id: number; text: string; rating: number }; type Product = { id: number; name: string; price: number }; type SyncProps = { name: string; price: number }; // AsyncProps lists the *resolved* prop types. WithAsyncProps wraps each in a // Promise at the call site, so getReactOnRailsAsyncProp('reviews') returns // Promise<Review[]> — which is then forwarded to an async child that awaits it. type AsyncProps = { reviews: Review[]; recommendations: Product[] }; export default function ProductPage({ name, price, getReactOnRailsAsyncProp, }: WithAsyncProps<AsyncProps, SyncProps>) { const reviewsPromise = getReactOnRailsAsyncProp('reviews'); const recommendationsPromise = getReactOnRailsAsyncProp('recommendations'); return ( <div> <h1>{name}</h1> <p>${price}</p> <Suspense fallback={<div>Loading reviews…</div>}> <AsyncReviewList reviewsPromise={reviewsPromise} /> </Suspense> <Suspense fallback={<div>Loading recommendations…</div>}> <AsyncRecommendationList itemsPromise={recommendationsPromise} /> </Suspense> </div> ); } // Each async child awaits only the prop it was handed. async function AsyncReviewList({ reviewsPromise }: { reviewsPromise: Promise<Review[]> }) { const resolved = await reviewsPromise; return ( <ul> {resolved.map((r) => ( <li key={r.id}>{r.text}</li> ))} </ul> ); } // AsyncRecommendationList mirrors AsyncReviewList: it awaits the recommendations Promise. async function AsyncRecommendationList({ itemsPromise }: { itemsPromise: Promise<Product[]> }) { const resolved = await itemsPromise; return ( <ul> {resolved.map((p) => ( <li key={p.id}>{p.name}</li> ))} </ul> ); } ``` > **Production note:** Wrap each `<Suspense>` in an `<ErrorBoundary>` so that if an async-prop stream rejects (e.g. a Rails-side exception while emitting), the boundary degrades to a fallback instead of crashing the whole page. See the [error-handling pattern](../../pro/react-server-components/inside-client-components.md#error-handling) for a reusable boundary. **Sync props vs. async props — which to use:** | | Sync props (`stream_react_component`) | Async props (`stream_react_component_with_async_props`) | | ----------------------- | ---------------------------------------- | ------------------------------------------------------- | | When Rails has the data | All props loaded before rendering begins | Fast props now; each slow prop streamed as it resolves | | What streams | Rendered HTML, as React walks the tree | Rendered HTML **plus** each prop independently | | Best for | All data sources are fast | One or more data sources are slow | Async props keep Rails as the backend: Rails still owns the queries, authorization, and caching — the `emit` block is ordinary Rails code running in the streaming view helper, not the React component. It just emits each result the moment it has it instead of blocking the whole render on the slowest source. (Referencing controller instance variables like `@product` from the block is fine and normal — the constraint is narrower: don't _pre-resolve_ the slow emit-block queries in the controller action, because it runs to completion before the view streams, so doing that work up front defeats the progressive streaming.) Requires React Server Components (`config.enable_rsc_support = true`). #### Parallelize the queries with the `async` gem In the block above, `reviews` is emitted before `recommendations` — the second query doesn't start until the first `emit.call` returns, so their times add up. The block already runs inside an [`async`](https://github.com/socketry/async) reactor (the same one the Pro renderer uses for its HTTP/2 stream), so you can fan the independent queries out into concurrent tasks and emit each prop the moment its own query resolves: ```erb <%= stream_react_component_with_async_props("ProductPage", props: { name: product.name, price: product.price }) do |emit| # The block is already running inside an Async reactor. `Sync` reuses it (or # starts one if none exists — either way no new OS thread) and acts as a # synchronization barrier: it runs the block with the current task (`parent`) # and returns only after every child started via `parent.async` has finished # — exactly when the stream should close. Sync do |parent| parent.async do # Each concurrent fiber checks out its OWN connection for the duration of # its query, then releases it before emitting (see the note below). reviews = ActiveRecord::Base.connection_pool.with_connection do product.reviews.as_json(only: [:id, :text, :rating]) end emit.call("reviews", reviews) end parent.async do recommendations = ActiveRecord::Base.connection_pool.with_connection do product.recommended_products.as_json(only: [:id, :name, :price]) end emit.call("recommendations", recommendations) end end end %> ``` Both tasks follow the same shape — wrap each query in its own `with_connection`, then emit. (If a prop comes from an external service over a fiber-aware HTTP client rather than the database, that task skips `with_connection` since it never touches the connection pool.) Each child task emits on its own, so props arrive in whatever order they resolve and React fills each `<Suspense>` boundary as its prop lands — the fastest source paints first and the total time is roughly the slowest source instead of the sum of all of them. Calling `emit.call` from concurrent fibers is safe: the reactor is single-threaded and cooperatively scheduled, and each `emit.call` writes one complete NDJSON line in a single operation — so concurrent emits never interleave within a line. Their _order_ can vary (whichever query resolves first emits first), which is fine because each line is a self-contained prop update. > **When this actually runs in parallel:** the `async` gem parallelizes **I/O-bound** work that yields to the fiber scheduler — most reliably calls to external services through a fiber-aware HTTP client (the renderer already depends on [`async-http`](https://github.com/socketry/async-http)). For ActiveRecord, give each concurrent fiber its own connection with `ActiveRecord::Base.connection_pool.with_connection`, run with fiber-based connection isolation (`config.active_support.isolation_level = :fiber`, Rails 7.1+), and size the pool for the fan-out — otherwise the fibers share one connection and the queries serialize. (On Rails 6.x–7.0 the connection pool ignores fiber identity, so the queries serialize with no visible error — or worse, corrupt results under concurrent load.) For CPU-bound work, or a database driver that doesn't cooperate with `Fiber.scheduler`, parallelize with threads instead (see [Avoiding Server-Side Waterfalls](#avoiding-server-side-waterfalls)). > > See [Database Queries in Async Props Blocks](../../pro/async-props-database-queries.md) for the complete configuration guide covering isolation level, pool sizing, driver compatibility, connection lifecycle (`with_connection` vs `lease_connection`), `CurrentAttributes` behavior, and troubleshooting. If fiber scheduling isn't configured, queries fall back to running sequentially — but with multiple async-props components on one page, the default `isolation_level = :thread` can cause silent connection corruption rather than graceful serialization. ## Migrating from React Query / TanStack Query > **New to TanStack Query on Rails?** This section covers _migrating_ an existing React Query setup into RSC. For a from-scratch guide to the recommended patterns (CSRF-aware fetch, stable query keys, first-paint seeding, and mutations), see [Using TanStack Query](../building-features/tanstack-query.md). React Query remains valuable in the RSC world for features like polling, optimistic updates, and infinite scrolling. But for simple data display, Server Components replace it entirely. ### Pattern 1: Simple Replacement (No Client Cache Needed) If a component only displays data without mutations, polling, or optimistic updates, replace React Query with a Server Component: ```jsx // Before: React Query 'use client'; import { useQuery } from '@tanstack/react-query'; function ProductList() { const { data, isLoading, error } = useQuery({ queryKey: ['products'], queryFn: () => fetch('/api/products').then((res) => res.json()), }); if (isLoading) return <Spinner />; if (error) return <Error message={error.message} />; return ( <ul> {data.map((p) => ( <li key={p.id}>{p.name}</li> ))} </ul> ); } ``` ```erb <%# ERB view — Rails passes the data as props %> <%= stream_react_component("ProductList", props: { products: Product.limit(50).as_json(only: [:id, :name]) }) %> ``` ```jsx // After: Server Component -- receives data from Rails controller props function ProductList({ products }) { return ( <ul> {products.map((p) => ( <li key={p.id}>{p.name}</li> ))} </ul> ); } ``` > **React on Rails note:** In React on Rails, the controller prepares the data and passes it as props -- no `async/await` in the component, no direct data layer calls. For data that's slow to compute, use [`stream_react_component_with_async_props`](#data-fetching-in-react-on-rails-pro) to stream it in progressively with Suspense. The generic `async function` + `await` pattern shown in other RSC frameworks bypasses Rails' authorization and caching layers and is not recommended. ### Pattern 2: Rails Props as Initial Data (Keep React Query for Client Features) When you need React Query's client features (background refetching, mutations, optimistic updates), pass Rails controller props as `initialData` so the component renders instantly with server data, then React Query takes over for client-side updates: ```jsx // ReactQueryProvider.jsx -- Client Component (provides QueryClient) 'use client'; import { QueryClient, QueryClientProvider } from '@tanstack/react-query'; import { useState } from 'react'; export default function ReactQueryProvider({ children }) { const [queryClient] = useState(() => new QueryClient()); return <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>; } ``` ```jsx // ProductsPage.jsx -- Server Component (receives data from Rails controller props) import ReactQueryProvider from './ReactQueryProvider'; import ProductList from './ProductList'; export default function ProductsPage({ products }) { return ( <ReactQueryProvider> <ProductList initialProducts={products} /> </ReactQueryProvider> ); } ``` ```jsx // ProductList.jsx -- Client Component (uses React Query hooks) 'use client'; import { useQuery } from '@tanstack/react-query'; export default function ProductList({ initialProducts }) { const { data: products } = useQuery({ queryKey: ['products'], queryFn: () => fetch('/api/products').then((res) => res.json()), initialData: initialProducts, initialDataUpdatedAt: Date.now(), // Marks the data as fresh as of client render time staleTime: 5 * 60 * 1000, // Treat Rails-fetched data as fresh for 5 min }); return ( <ul> {products.map((p) => ( <li key={p.id}> {p.name} - ${p.price} </li> ))} </ul> ); } ``` ```erb <%# ERB view — Rails passes the data as props %> <%= stream_react_component("ProductsPage", props: { products: Product.limit(50).as_json }) %> ``` **How it works:** 1. Rails controller fetches products and passes them as props 2. Server Component passes the data to the Client Component as `initialProducts` 3. React Query uses `initialData` to populate the cache with no loading state on first render 4. Subsequent refetches happen client-side as usual > **Note:** `initialDataUpdatedAt` and `staleTime` work together to prevent React Query from treating the Rails data as immediately stale on mount. `Date.now()` uses the client render timestamp, not the actual Rails fetch time — this is close enough for most apps. For precise control, pass a timestamp from your Rails controller (e.g., `(Time.now.to_f * 1000).to_i`) as a prop and use that instead. If you don't need timed refetching at all, use `staleTime: Infinity` to prevent automatic refetches entirely. > **Alternative:** For complex cases with many queries, you can use TanStack Query's `dehydrate`/`HydrationBoundary` pattern to prefetch and seed the entire QueryClient cache on the server. See the [TanStack Query SSR docs](https://tanstack.com/query/latest/docs/framework/react/guides/ssr) for details. ## Migrating from SWR SWR follows a similar pattern -- pass Rails controller props as `fallbackData` so the component renders instantly with server data: ```jsx // DashboardPage.jsx -- Server Component (receives data from Rails controller props) import DashboardStats from './DashboardStats'; export default function DashboardPage({ stats }) { return <DashboardStats fallbackData={stats} />; } ``` ```erb <%# ERB view — Rails passes the data as props %> <%= stream_react_component("DashboardPage", props: { stats: DashboardStats.compute.as_json }) %> ``` ```jsx // DashboardStats.jsx -- Client Component 'use client'; import useSWR from 'swr'; const fetcher = (url) => fetch(url).then((res) => res.json()); export default function DashboardStats({ fallbackData }) { const { data: stats } = useSWR('/api/dashboard/stats', fetcher, { fallbackData, }); return ( <div> <span>Revenue: {stats.revenue}</span> <span>Users: {stats.users}</span> </div> ); } ``` ## Avoiding Server-Side Waterfalls > **React on Rails note:** In React on Rails, use [`stream_react_component_with_async_props`](#data-fetching-in-react-on-rails-pro) when slow Rails data should stream into Suspense boundaries independently. If independent values require slow Ruby work, start that work concurrently before emitting; the patterns below apply when you have async Server Components that fetch data directly (outside the async props flow). The most critical performance pitfall with Server Components is sequential data fetching. When one `await` blocks the next, you create a waterfall on the server: ### The Problem: Sequential Queries ```ruby # BAD: Each query blocks the next (750ms total) def show @user = User.find(params[:user_id]) # 200ms @stats = DashboardStats.for(@user) # 300ms (waits for user) @posts = @user.posts.recent # 250ms (sequential) stream_view_containing_react_components(template: "dashboard/show") end ``` ### Solution 1: Parallelize Independent Queries When data sources are independent, use Ruby threads to fetch in parallel: ```ruby # GOOD: Fetch in parallel (300ms -- limited by slowest) def show user_id = params[:user_id] results = {} threads = [] threads << Thread.new do ActiveRecord::Base.connection_pool.with_connection do results[:user] = User.find(user_id).as_json end end threads << Thread.new do ActiveRecord::Base.connection_pool.with_connection do results[:stats] = DashboardStats.compute.as_json end end threads << Thread.new do ActiveRecord::Base.connection_pool.with_connection do results[:posts] = Post.recent.as_json end end threads.each(&:join) @dashboard_props = { title: "My Dashboard" }.merge(results) stream_view_containing_react_components(template: "dashboard/show") end ``` ```erb <%# All data fetched in parallel, rendered with streaming SSR %> <%= stream_react_component("Dashboard", props: @dashboard_props) %> ``` > **Note:** In production, wrap each thread body in a `rescue` to avoid incomplete results if a query fails. An unhandled exception in any thread will be re-raised by `join`. ### Solution 2: Separate Components for Independent Data For data that is truly independent, render multiple `stream_react_component` calls. Each component renders as its data becomes available: ```erb <%# Each component renders independently %> <%= stream_react_component("DashboardHeader", props: { title: "My Dashboard" }) %> <%= stream_react_component("UserProfile", props: { user: User.find(params[:user_id]).as_json(only: [:id, :name, :avatar_url]) }) %> <%= stream_react_component("StatsPanel", props: { stats: DashboardStats.compute.as_json }) %> <%= stream_react_component("PostFeed", props: { posts: Post.recent.as_json }) %> ``` ```jsx // Each component is a simple Server Component function UserProfile({ user }) { return <div>{user.name}</div>; } function StatsPanel({ stats }) { return ( <div> <span>Revenue: {stats.revenue}</span> <span>Users: {stats.users}</span> </div> ); } function PostFeed({ posts }) { return ( <ul> {posts.map((p) => ( <li key={p.id}>{p.title}</li> ))} </ul> ); } ``` ### Solution 3: Pass All Data as Props Fetch all data in the controller and pass it as props. `stream_react_component` streams the rendered HTML to the browser via React's `renderToPipeableStream`: ```erb <%= stream_react_component("ProductPage", props: { name: product.name, price: product.price, reviews: product.reviews .as_json(only: [:id, :text, :rating]), related: product.recommended_products .as_json(only: [:id, :name, :price]) }) %> ``` ```jsx export default function ProductPage({ name, price, reviews, related }) { return ( <div> <h1>{name}</h1> <p>${price}</p> <ReviewList reviews={reviews} /> <RelatedProducts products={related} /> </div> ); } function ReviewList({ reviews }) { return ( <ul> {reviews.map((r) => ( <li key={r.id}>{r.text}</li> ))} </ul> ); } function RelatedProducts({ products }) { return ( <ul> {products.map((p) => ( <li key={p.id}>{p.name}</li> ))} </ul> ); } ``` All data is loaded in Rails before rendering begins. `stream_react_component` then streams the rendered HTML to the browser as React processes the component tree. ## The `use()` Hook for Client Components The `use()` hook lets Client Components resolve promises. In React on Rails, data typically arrives as resolved props from Rails, so `use()` is most relevant when combining Server Components with client-side data fetching libraries. ### Common `use()` Mistakes in Client Components Creating a promise inside a Client Component and passing it to `use()` triggers this runtime error: > **"A component was suspended by an uncached promise. Creating promises inside a Client Component or hook is not yet supported, except via a Suspense-compatible library or framework."** **Why it happens:** React tracks promises passed to `use()` by **object reference identity** across re-renders. On each render, it checks whether the promise is the same object as the previous render. When you create a promise inside a Client Component, every render produces a new promise instance -- React sees a different reference, cannot determine if the result is still valid, and throws. ```jsx // WRONG: Creating a promise inline — new promise every render 'use client'; import { use } from 'react'; function Comments({ postId }) { const comments = use(fetch(`/api/comments/${postId}`).then((r) => r.json())); return ( <ul> {comments.map((c) => ( <li key={c.id}>{c.text}</li> ))} </ul> ); } ``` ```jsx // WRONG: Variable doesn't help — still a new promise every render 'use client'; import { use } from 'react'; function Comments({ postId }) { const promise = getComments(postId); // New promise object each render const comments = use(promise); return ( <ul> {comments.map((c) => ( <li key={c.id}>{c.text}</li> ))} </ul> ); } ``` ```jsx // WRONG: useMemo seems to work but is NOT reliable 'use client'; import { use, useMemo } from 'react'; function Comments({ postId }) { const promise = useMemo(() => getComments(postId), [postId]); const comments = use(promise); // React does NOT guarantee useMemo stability. From the docs: // "React may choose to 'forget' some previously memoized values // and recalculate them on next render." // If React discards the memoized value, a new promise is created, // and use() throws the uncached promise error intermittently. } ``` **The safe approach -- use a Suspense-compatible library:** ```jsx // CORRECT: Suspense-compatible library (TanStack Query) 'use client'; import { useSuspenseQuery } from '@tanstack/react-query'; function Comments({ postId }) { const { data: comments } = useSuspenseQuery({ queryKey: ['comments', postId], queryFn: () => getComments(postId), // client-side fetch wrapper }); // The library manages promise identity internally — // same cache key returns the same promise reference. return ( <ul> {comments.map((c) => ( <li key={c.id}>{c.text}</li> ))} </ul> ); } ``` > **Rule:** Never create a raw promise for `use()` inside a Client Component. Use a Suspense-compatible library like TanStack Query or SWR that manages promise identity internally. ## Request Deduplication with `React.cache()` > **React on Rails note:** In most React on Rails applications, data flows through controller props or `stream_react_component_with_async_props`, so `React.cache()` is unnecessary. This section applies when Server Components call data-fetching functions directly (for example, from the Node renderer). If you are using `stream_react_component_with_async_props`, repeated calls within the same request already share the same deduped Promise. When multiple Server Components need the same data, `React.cache()` ensures the fetch happens only once per request: ```jsx // lib/data.js -- Define at module level import { cache } from 'react'; export const getUser = cache(async (id) => { return await fetchUserById(id); }); ``` ```jsx // Navbar.jsx and Sidebar.jsx both import getUser. // The first call fetches; the second returns the cached result. async function Navbar({ userId }) { const user = await getUser(userId); return <nav>Welcome, {user.name}</nav>; } ``` **Key properties:** - Cache is scoped to the **current request** -- no cross-request data leakage - Uses `Object.is` for argument comparison (pass primitives, not objects) - Must be defined at **module level**, not inside components - Only works in Server Components > **Note:** `React.cache()` is only available in React Server Component environments. It is not available in Client Components or non-RSC server rendering (e.g., `renderToString`). For most React on Rails applications, you won't need `React.cache()` for data fetching because data flows through Rails controller props. However, `React.cache()` is valuable for sharing **computed per-request state** (like intl instances, feature flag lookups, or auth context) across Server Components without prop drilling. See [Sharing Per-Request Data in Server Components](../../pro/react-server-components/per-request-data.md) for these patterns. ## Mutations: Rails Controllers, Not Server Actions > **Important:** React on Rails does **not** support Server Actions (`'use server'`). Server Actions run on the Node renderer, which is a rendering server -- it has no access to Rails models, sessions, cookies, or CSRF protection. Do not use `'use server'` in React on Rails applications. This is a deliberate, settled design decision, not a temporary gap (see the decision record in [#3867](https://github.com/shakacode/react_on_rails/issues/3867)): Rails controllers are the mutation layer, and the ergonomics gap with Next.js Server Actions is being closed by a first-class Rails-native bridge -- the [`useRailsForm`](../building-features/forms.md) hook paired with the `ReactOnRails::Controller::FormResponders` controller concern, **shipped** via [#3872](https://github.com/shakacode/react_on_rails/issues/3872) (see [Forms and Mutations](../building-features/forms.md)). The `fetch` + CSRF pattern below remains fully supported and is exactly what `useRailsForm` automates. An optional `'use server'`-shaped authoring syntax that compiles down to the Rails bridge (for Next.js-migration familiarity only) is a deferred follow-up RFC, tracked in [#3956](https://github.com/shakacode/react_on_rails/issues/3956). All mutations in React on Rails should go through Rails controllers via standard forms or API endpoints: ```jsx // CommentForm.jsx -- Client Component 'use client'; import { useState } from 'react'; import ReactOnRails from 'react-on-rails'; export default function CommentForm({ postId }) { const [content, setContent] = useState(''); async function handleSubmit(e) { e.preventDefault(); const response = await fetch('/api/comments', { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-CSRF-Token': ReactOnRails.authenticityToken(), }, body: JSON.stringify({ comment: { content, postId } }), }); if (!response.ok) throw new Error(`Request failed: ${response.status}`); setContent(''); } return ( <form onSubmit={handleSubmit}> <textarea value={content} onChange={(e) => setContent(e.target.value)} /> <button type="submit">Post Comment</button> </form> ); } ``` ```erb <%# ERB view %> <%= stream_react_component("CommentForm", props: { postId: @post.id }) %> ``` > **Note:** `ReactOnRails.authenticityToken()` reads the CSRF token from the `<meta name="csrf-token">` tag, which is the standard Rails approach. This avoids duplicating the token in component props. This preserves Rails' full controller/model layer -- authentication, authorization, CSRF protection, and validations all work as expected. ## When to Keep Client-Side Fetching Not everything should move to the server. In React on Rails, most read-only data is already server-side -- Rails controller props deliver it to your components without any client-side fetching. The table below covers the cases where you should keep client-side fetching instead of relying on Rails controller props or [`stream_react_component_with_async_props`](#data-fetching-in-react-on-rails-pro): | Use Case | Why Client-Side | Recommended Tool | | ------------------------------- | ------------------------------------------ | ----------------------------------- | | Real-time data (WebSocket, SSE) | Requires persistent connection | Native WebSocket + `useState` | | Polling / auto-refresh | Periodic updates after initial load | React Query / SWR | | Optimistic updates | Instant UI feedback before server confirms | React Query mutations | | Infinite scrolling | User-driven pagination | React Query / SWR | | User-triggered searches | Response to client interactions | `useState` + `fetch` or React Query | | Offline-first features | Must work without server | Local state + sync | ### Hybrid Pattern: Rails Props + Client Updates For features that need server-fetched initial data with client-side updates: ```erb <%# ERB view — Rails passes initial data as props %> <%= stream_react_component("ChatPage", props: { channelId: @channel.id, initialMessages: @channel.messages.recent.as_json }) %> ``` ```jsx // ChatPage.jsx -- Server Component import ChatWindow from './ChatWindow'; export default function ChatPage({ channelId, initialMessages }) { return ( <div> <ChannelHeader channelId={channelId} /> <ChatWindow channelId={channelId} initialMessages={initialMessages} /> </div> ); } ``` ```jsx // ChatWindow.jsx -- Client Component 'use client'; import { useState, useEffect } from 'react'; export default function ChatWindow({ channelId, initialMessages }) { const [messages, setMessages] = useState(initialMessages); useEffect(() => { const ws = new WebSocket(`wss://api.example.com/chat/${channelId}`); ws.onmessage = (event) => { setMessages((prev) => [...prev, JSON.parse(event.data)]); }; return () => ws.close(); }, [channelId]); return <MessageList messages={messages} />; } ``` ## Loading States and Suspense Boundaries ### Streaming HTML Delivery With synchronous props, Rails loads all data before rendering begins. `stream_react_component` then streams the rendered HTML as React processes the component tree — the browser receives content as it's rendered rather than waiting for the entire page: ```erb <%# ERB view — Rails passes all data as props %> <%= stream_react_component("Page", props: { title: @page.title, main_content: @page.main_content.as_json, recommendations: RecommendationService.for(@page).as_json, comments: @page.comments.recent.as_json }) %> ``` ```jsx export default function Page({ title, main_content, recommendations, comments }) { return ( <div> <Header /> <h1>{title}</h1> <nav> <SideNav /> </nav> <main> <MainContent content={main_content} /> <Recommendations items={recommendations} /> <Comments comments={comments} /> </main> </div> ); } ``` ### Avoiding "Popcorn UI" When many Suspense boundaries resolve at different times, content pops in unpredictably. Group related content in a single boundary: ```jsx // Bad: Each section pops in individually <Suspense fallback={<Skeleton1 />}><Section1 /></Suspense> <Suspense fallback={<Skeleton2 />}><Section2 /></Suspense> <Suspense fallback={<Skeleton3 />}><Section3 /></Suspense> // Better: Related sections appear together <Suspense fallback={<CombinedSkeleton />}> <Section1 /> <Section2 /> <Section3 /> </Suspense> ``` ### Dimension-Matched Skeletons Use skeleton components that match the dimensions of the real content to prevent layout shift: ```jsx function StatsSkeleton() { return ( <div className="stats-panel" style={{ height: '200px' }}> <div className="skeleton-bar" /> <div className="skeleton-bar" /> <div className="skeleton-bar" /> </div> ); } ``` ## Common Mistakes ### Mistake 1: Sequential queries in the Rails controller The most common performance regression after migrating to RSC. Since data now comes from the Rails controller (instead of parallel client-side fetches), sequential ActiveRecord queries block the entire page render: ```ruby # BAD: 750ms total -- each query waits for the previous one def show @user = User.find(params[:id]) # 200ms @stats = Stats.for_user(@user.id) # 300ms @posts = Post.where(user_id: @user.id) # 250ms stream_view_containing_react_components(template: "show") end ``` **Fix:** Use Ruby threads for independent queries (see [Avoiding Server-Side Waterfalls](#avoiding-server-side-waterfalls)), use `stream_react_component_with_async_props` for slow props within one component, or split truly independent sections into multiple `stream_react_component` calls in the ERB view. ### Mistake 2: Using Server Actions (`'use server'`) Server Actions are **not supported** in React on Rails in any environment. The Node renderer is a rendering server -- it has no access to Rails models, sessions, cookies, or CSRF protection. ```jsx // BAD: Server Actions don't have access to Rails 'use server'; export async function createUser(name) { // The Node renderer is a render-only environment -- it has no database // connection, no ORM, and no access to Rails models or sessions. // This code will fail at runtime. } ``` ```jsx // GOOD: Use a Client Component that submits to a Rails controller endpoint 'use client'; import { useState } from 'react'; import ReactOnRails from 'react-on-rails'; export default function CreateUserForm() { const [name, setName] = useState(''); async function handleSubmit(e) { e.preventDefault(); await fetch('/api/users', { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-CSRF-Token': ReactOnRails.authenticityToken(), }, body: JSON.stringify({ user: { name } }), }); setName(''); } return ( <form onSubmit={handleSubmit}> <input value={name} onChange={(e) => setName(e.target.value)} /> <button type="submit">Create</button> </form> ); } ``` ### Mistake 3: Forgetting CSRF tokens in fetch requests Rails rejects POST/PUT/PATCH/DELETE requests without a valid CSRF token. This is easy to miss when migrating from forms that included the token automatically: ```jsx // BAD: Missing CSRF token -- Rails returns 422 Unprocessable Entity await fetch('/api/items', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(data), }); // GOOD: Include the CSRF token await fetch('/api/items', { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-CSRF-Token': ReactOnRails.authenticityToken(), }, body: JSON.stringify(data), }); ``` ### Mistake 4: Removing loading states before adding streaming If you remove `useEffect` + loading state but haven't set up streaming with Suspense boundaries, the page appears blank until all server data is ready: **Fix:** Complete the streaming setup ([Preparing Your App](rsc-preparing-app.md#step-6-switch-to-streaming-rendering)) before converting data-fetching components. Use `stream_react_component_with_async_props` for Rails data that should resolve behind Suspense, and add Suspense boundaries around sections that should stream independently. ### Mistake 5: Over-serializing ActiveRecord objects Calling `.as_json` without specifying `only:` or `include:` can serialize the entire object graph, including associations, timestamps, and internal fields. This bloats the RSC payload and can leak sensitive data: ```ruby # BAD: Serializes everything, including potentially sensitive fields props: { user: @user.as_json } # GOOD: Whitelist exactly what the component needs props: { user: @user.as_json(only: [:id, :name, :email]) } ``` ## Migration Checklist ### Step 1: Identify Candidates For each component that fetches data: - Does it only display data? → Convert to Server Component (pass data as props via `stream_react_component`) - Does it need polling/optimistic updates? → Keep React Query/SWR, add server prefetch - Does it need real-time updates? → Keep client-side, pass initial data from server ### Step 2: Convert Simple Fetches 1. Remove the `'use client'` directive 2. Remove `useState` for data, loading, and error 3. Remove the `useEffect` data fetch 4. Accept data as props from Rails. For slow data, keep synchronous values in `props:` and emit the slow values with [`stream_react_component_with_async_props`](#data-fetching-in-react-on-rails-pro). 5. Use the matching ERB helper to enable streaming SSR: `stream_react_component` for synchronous props, or `stream_react_component_with_async_props` for async props. 6. Remove the API route if it was only used by this component ### Step 3: Add Suspense Boundaries 7. Wrap converted components in `<Suspense>` at the parent level 8. Create skeleton components that match content dimensions 9. Group related data sections in shared boundaries ### Step 4: Optimize 10. Use `stream_react_component` for synchronous props and streaming HTML delivery via React's `renderToPipeableStream` 11. Use `stream_react_component_with_async_props` for slow Rails props behind Suspense boundaries; parallelize independent Ruby queries inside the block when needed to avoid server-side waterfalls 12. For client-side updates after initial render, use React Query or SWR with `initialData`/`fallbackData` ## Next Steps - [HTTP Response Ownership](rsc-http-response-patterns.md) -- status codes, redirects, and cache headers - [Third-Party Library Compatibility](rsc-third-party-libs.md) -- dealing with incompatible libraries - [Troubleshooting and Common Pitfalls](rsc-troubleshooting.md) -- debugging and avoiding problems ================================================================================ PAGE: https://reactonrails.com/docs/migrating/rsc-http-response-patterns SOURCE: docs/oss/migrating/rsc-http-response-patterns.md ================================================================================ # RSC Migration: HTTP Response Ownership This guide covers status codes, redirects, and cache headers when Rails owns the HTTP request and React Server Components own the rendered UI. > **Part 5 of the [RSC Migration Series](migrating-to-rsc.md)** | Previous: [Data Fetching Migration](rsc-data-fetching.md) | Next: [Third-Party Library Compatibility](rsc-third-party-libs.md) > **Note:** The streaming helpers shown in this guide (`ReactOnRailsPro::Stream`, `stream_view_containing_react_components`, and `stream_react_component`) require React on Rails Pro. The same HTTP ownership rules apply to non-streaming Rails responses; use the rendering helper that matches your app. ## Core Rule: Rails Decides Before Rendering React Server Components decide what UI to render. Rails still decides the HTTP response: - Status codes (`200`, `404`, `410`, etc.) - Redirects - Cache headers - Cookies and session policy - Authentication and authorization failures With streaming, this boundary matters even more. Once Rails writes the first response chunk, headers are committed. After that point the app can no longer turn the response into a real HTTP redirect, change `200` to `404`, or revise cache policy. Make these route-level decisions in the controller or a Ruby preflight object before calling `stream_view_containing_react_components`. ## Preflight Pattern Use a controller or service object to gather data and choose the response policy before rendering the RSC tree. The preflight object exposes a small, serializable result. `StorySerializer`, `PublicStorySerializer`, `ViewerSerializer`, and `StoryPolicy` are placeholder names in these examples; substitute your app's serializer, presenter, or authorization helper as needed. ```ruby class StoriesController < ApplicationController include ReactOnRailsPro::Stream # Requires React on Rails Pro def show preflight = StoryPagePreflight.call(params[:id], current_user: current_user) if preflight.redirect_reason # Map every possible redirect_reason StoryPagePreflight can return. # Extend this hash whenever the preflight gains a new redirect branch. redirect_path = { unauthenticated: sign_in_path, }.fetch(preflight.redirect_reason) do |reason| raise ArgumentError, "Unknown redirect_reason: #{reason.inspect}" end return redirect_to(redirect_path, status: preflight.redirect_status) end response.status = preflight.status if preflight.status response.headers["Cache-Control"] = preflight.cache_control if preflight.cache_control @story_props = preflight.props stream_view_containing_react_components(template: "stories/show") end end ``` `stream_view_containing_react_components` commits the response status that was set before streaming begins. For example, a pre-set `:not_found` status remains a real `404` in the HTTP response line. One possible preflight implementation is: ```ruby class StoryPagePreflight # redirect_reason is nil when no redirect is needed. # redirect_status is only meaningful when redirect_reason is set; the override # below ignores it otherwise so callers cannot accidentally produce a status # without a reason. Result = Struct.new( :props, :status, :redirect_reason, :redirect_status, :cache_control, keyword_init: true ) do # Supply a default only for redirect results. def redirect_status return unless redirect_reason # 303 (:see_other) forces GET on the redirect target, which is correct # when the original request might be POST (for example, a sign-in flow # that follows a form submission). Override with :found (302) when both # legs are GET, matching Rails' redirect_to default. self[:redirect_status] || :see_other end end def self.call(story_id, current_user:) unless current_user return Result.new(redirect_reason: :unauthenticated) end story = Story.find_by(id: story_id) unless story return Result.new( props: { notFound: true, story: nil }, status: :not_found, cache_control: "no-store" ) end unless StoryPolicy.new(current_user, story).read? # Return 404 instead of 403 to avoid revealing that this record exists. return Result.new( props: { notFound: true, story: nil }, status: :not_found, cache_control: "no-store" ) end Result.new( props: { notFound: false, story: StorySerializer.render_as_hash(story) }, cache_control: "private, no-cache" ) end end ``` ```erb <%# app/views/stories/show.html.erb %> <%= stream_react_component("StoryPage", props: @story_props) %> ``` Keep the props serializable and intentional. A good preflight result usually contains: - The data the RSC tree needs to render - The selected HTTP status - Any redirect reason and status - Cache policy metadata - Small route-level flags such as `notFound: true` Avoid making React responsible for route outcomes. React can render a "not found" UI, but Rails should decide whether the response is actually a `404`. > **Important:** Set cookies and mutate session state before calling `stream_view_containing_react_components`, for the same reason you set status and cache headers first. Once streaming commits the headers, `Set-Cookie` changes and session writes can no longer be added reliably to the HTTP response. ## 404 and Not-Found Routes The following controller snippets assume the controller includes `ReactOnRailsPro::Stream`, as shown in the preflight example. For simple not-found cases, return a Rails response before streaming: ```ruby def show story = Story.find_by(id: params[:id]) return render(template: "errors/not_found", status: :not_found) unless story @story_props = { story: StorySerializer.render_as_hash(story) } stream_view_containing_react_components(template: "stories/show") end ``` Create `app/views/errors/not_found.html.erb` or use another existing error template before copying this pattern. For quick local testing, `render(plain: "Not Found", status: :not_found)` is a minimal stand-in. If you want the not-found page itself to be rendered by RSC, set the status before streaming: ```ruby def show story = Story.find_by(id: params[:id]) if story.nil? response.status = :not_found @story_props = { notFound: true, story: nil } else @story_props = { notFound: false, story: StorySerializer.render_as_hash(story) } end stream_view_containing_react_components(template: "stories/show") end ``` Then keep the React component purely presentational. Set `notFound` explicitly on every branch so the discriminated union is fully exhaustive and TypeScript narrows `story` correctly. Keep `props` whole until after the guard — destructuring upfront collapses the union and loses the narrowing. ```tsx type StoryData = { id: number; title: string }; type StoryPageProps = { notFound: true; story: null } | { notFound: false; story: StoryData }; ``` What not to do — destructuring before the guard loses narrowing: ```tsx export default function StoryPage(props: StoryPageProps) { const { notFound, story } = props; // story widens to StoryData | null — TypeScript can't narrow it further if (notFound) { return <NotFoundMessage />; } return <Story story={story} />; // TS error: story is still StoryData | null here } ``` Keep `props` intact through the guard so the discriminated union narrows correctly: ```tsx export default function StoryPage(props: StoryPageProps) { if (props.notFound) { return <NotFoundMessage />; } return <Story story={props.story} />; } ``` Use this pattern when the branded not-found UI benefits from the same RSC layout as the rest of the route. Use a plain Rails error template when you need the smallest, most reliable failure path. Rails normalizes `response.status` values through Rack, so both integer codes such as `404` and Rails symbols such as `:not_found` are valid. Cache `404` responses publicly only when the route is truly missing, such as typo-driven URLs that repeat often. Prefer `no-store` for user-specific or permission-sensitive misses, and use `410 Gone` for durable removals where caches should reuse the response as a permanent absence. Use `410 Gone` when the route identifies a permanently removed resource and you want caches to treat that response differently from a temporary `404`: ```ruby def show story = Story.find_by(slug: params[:slug]) return render(template: "errors/not_found", status: :not_found) unless story if story.removed? # Use this branch only when removed stories are truly permanent in your app. # max-age=0 makes browsers always revalidate; s-maxage=3600 lets shared caches # (such as a CDN) serve the 410 for up to an hour without hitting the origin. response.headers["Cache-Control"] = "public, max-age=0, s-maxage=3600" return render(template: "errors/gone", status: :gone) end @story_props = { story: StorySerializer.render_as_hash(story) } stream_view_containing_react_components(template: "stories/show") end ``` Create `app/views/errors/gone.html.erb` if your app does not already have a generic template for `410` responses. Cache a `410` only when the removal is durable enough for clients and CDNs to reuse that response. With `max-age=3600`, a shared cache may keep serving the `410` for up to one hour after the origin restores the resource unless you purge that cache explicitly. Choose the TTL based on how confident you are that the removal is permanent and whether your CDN supports on-demand purging; longer TTLs are appropriate only for irreversible removals. Without on-demand CDN purging, the only way to recover before `s-maxage` expires is to wait out the full TTL, so use a short `s-maxage` (such as 300–600 seconds) when you are not certain the resource is gone permanently and your CDN does not support instant purging. ## Redirects Use Rails redirects before streaming. Keep authentication redirects separate from authorization decisions so signed-in users are not sent back to sign-in and private resources do not reveal that a record exists. Replace `can?` with your app's authorization helper: ```ruby def show return redirect_to(sign_in_path, status: :see_other) unless current_user story = Story.find_by(id: params[:id]) return render(template: "errors/not_found", status: :not_found) unless story return render(template: "errors/not_found", status: :not_found) unless can?(:read, story) @story_props = { story: StorySerializer.render_as_hash(story) } stream_view_containing_react_components(template: "stories/show") end ``` Use `:forbidden` for unauthorized users only when the route is allowed to reveal that the resource exists. For private resources, returning the same `404` for missing and unauthorized records is usually safer. Do not model route redirects as Server Component return values. React on Rails render-functions may expose redirect metadata for client routers, but React on Rails does not turn that metadata into an actual HTTP redirect for the page response. See [Redirect Information](../core-concepts/render-functions.md#8-redirect-information-legacy). If a streamed response has already started and an error forces navigation, the fallback is client-side navigation or an error shell, not a true HTTP redirect. Treat that as an exception path, not the normal route design. ## Cache Headers Set cache headers in Rails before streaming. The streamed HTML can include serialized props and embedded RSC payloads, so cache it with the same care you would use for any Rails response that contains user-specific data. For personalized pages, prefer private HTTP caching with revalidation: ```ruby response.headers["Cache-Control"] = "private, no-cache" ``` `private` prevents CDNs and shared proxies from storing the response; `no-cache` allows permitted HTTP caches to store it but requires revalidation with the origin before each reuse. For a private response, that permitted cache is usually the browser. Use `no-store` instead when sensitive responses must never be cached by anyone. For public pages, let Rails decide freshness before rendering: > **Rails 7.1+:** The `cache_control:` keyword on `stale?` requires Rails 7.1 or later. On earlier Rails versions, set the full `Cache-Control` header directly with `response.headers["Cache-Control"] = "public, max-age=300"` and keep the explicit freshness guard before streaming. `stale_while_revalidate` only helps caches that support that extension; unsupported browsers, proxies, and CDNs fall back to normal `max-age` behavior. ```ruby def show story = Story.published.find_by(slug: params[:slug]) return render(template: "errors/not_found", status: :not_found) unless story # If request validators still match, stale? sends 304 Not Modified and returns false. # The explicit return avoids opening a stream for that already-selected response. return unless stale?( story, public: true, cache_control: { max_age: 60, stale_while_revalidate: 300 } ) @story_props = { story: PublicStorySerializer.render_as_hash(story) } stream_view_containing_react_components(template: "stories/show") end ``` If `stale?` returns `false`, Rails has already prepared the `304 Not Modified` response; the early return keeps the controller from starting a streamed render after that response has been selected. `stale?` compares Rails' response validators, such as the generated `ETag` and `Last-Modified`, with request headers such as `If-None-Match` and `If-Modified-Since`. Before relying on this for public caching, make sure those validators change whenever any rendered input changes. For example, models for comments or join records that affect the page can declare `belongs_to :story, touch: true`, while author/profile data may need an explicit composite cache key or a manual touch when it changes. Otherwise Rails can return `304 Not Modified` for content that should be regenerated. When the response varies by locale, device class, authentication state, or feature flag, set the corresponding `Vary` policy before streaming or keep the response private. Replace `Accept-Language` with the headers your app actually varies on, such as `Accept-Encoding`, `X-Device-Class`, or an application-specific header. When the controller is the only place setting `Vary` for this response, assign it directly: ```ruby response.headers["Vary"] = "Accept-Language" ``` > **Advanced: merging with an upstream `Vary`.** If Rack middleware, a `before_action`, or a parent layout may have > already set `Vary`, append new tokens with a small helper that deduplicates case-insensitively and short-circuits on > `Vary: *` (which already varies on everything). Define this helper on `ApplicationController` or a shared concern so > every streaming action can call it before streaming: > > ```ruby > # Call this before streaming, e.g. in a before_action or inline in the action. > def merge_vary_header(*tokens) > # Per RFC 7231, "*" must not appear alongside named fields, so collapse to > # "*" whenever any caller passes it. > return response.headers["Vary"] = "*" if tokens.map(&:strip).include?("*") > > existing = response.headers["Vary"].presence > return if existing == "*" > > merged = [existing, *tokens] > .compact > .flat_map { |value| value.split(",") } > .map(&:strip) > .reject(&:empty?) > .uniq { |token| token.downcase } > response.headers["Vary"] = merged.join(", ") > end > ``` > > Then the call site stays readable: > > ```ruby > merge_vary_header("Accept-Language") > ``` Every `Vary` header expands the cache key; avoid high-cardinality headers for public caches unless that extra cache storage is intentional. Do not bury cache decisions inside Server Components. By the time React is rendering, the controller should already know whether the response is public, private, stale, or not cacheable. ## What To Pass Into RSC Pass decisions as data, not as hidden HTTP side effects: ```ruby @story_props = { story: StorySerializer.render_as_hash(story), viewer: ViewerSerializer.render_as_hash(current_user), responsePolicy: { canonicalUrl: story_url(story) } } ``` Keep viewer props minimal. They are embedded in the streamed response and visible to browser DevTools, logs, and any permitted cache, so include only fields the component actually reads rather than a full user representation. ```tsx type StoryData = { id: number; title: string }; type ViewerData = { id: number; name: string }; type ResponsePolicy = { canonicalUrl: string }; type StoryPageProps = { story: StoryData; viewer: ViewerData; responsePolicy: ResponsePolicy }; export default function StoryPage({ story, viewer, responsePolicy }: StoryPageProps) { return ( <> <link rel="canonical" href={responsePolicy.canonicalUrl} /> <Story story={story} viewer={viewer} /> </> ); } ``` Use the same serialized key names that the TypeScript component consumes. React on Rails passes prop keys through by default, so these example props are already in camelCase for TypeScript. If your app uses `config.rendering_props_extension` or another custom serializer to change key casing, use the Ruby-side key names that your serializer expects and keep both sides aligned. Native `<link>` hoisting requires React 19. On React 18, use `react-helmet` or emit canonical URLs from the Rails layout instead. See [React 19 Native Metadata](../building-features/react-19-native-metadata.md). React can render metadata, route chrome, empty states, and branded error UI from these props. Rails remains the source of truth for the actual HTTP semantics. ## Checklist - Decide redirects before rendering. - Decide `404`, `410`, and authorization statuses before rendering. - Set cache headers before the first streamed chunk. - Set cookies and mutate session state before the first streamed chunk. - Pass route decisions into RSC as serializable props. - Keep Rails controllers, policies, and services responsible for authentication, authorization, and response policy. - Use Client Component navigation only for browser-side transitions after a valid HTTP response exists. ## Next Steps - [Third-Party Library Compatibility](rsc-third-party-libs.md) -- dealing with incompatible libraries - [Troubleshooting and Common Pitfalls](rsc-troubleshooting.md) -- debugging and avoiding problems ================================================================================ PAGE: https://reactonrails.com/docs/migrating/rsc-third-party-libs SOURCE: docs/oss/migrating/rsc-third-party-libs.md ================================================================================ # RSC Migration: Third-Party Library Compatibility Most third-party React libraries were built before Server Components existed. Many rely on hooks, Context, or browser APIs that are unavailable in Server Components. This guide covers how to identify incompatible libraries, create wrapper patterns, and choose RSC-compatible alternatives. > **Part 6 of the [RSC Migration Series](migrating-to-rsc.md)** | Previous: [HTTP Response Ownership](rsc-http-response-patterns.md) | Next: [Troubleshooting](rsc-troubleshooting.md) ## Why Libraries Break in Server Components Server Components cannot use: - `useState`, `useEffect`, `useRef`, `useReducer`, and most React hooks - `createContext` / `useContext` - Browser APIs (`window`, `localStorage`, `document`) - Event handlers (`onClick`, `onChange`) > **Note on `React.memo` and `forwardRef`:** These wrappers don't cause errors in Server Components -- the React Flight renderer silently unwraps them. However, their functionality has no effect: `memo` can't memoize (Server Components don't re-render), and `forwardRef` can't forward refs (the `ref` prop is explicitly rejected by the Flight serializer). Libraries that use these wrappers can still render as Server Components, unlike libraries that call hooks. `forwardRef` is deprecated in React 19 in favor of `ref` as a regular prop. > > **Note on `ref` in Server Components:** `React.createRef()` is available in the server runtime (it's a plain function, not a hook), but the resulting ref cannot be attached to any element. The Flight serializer explicitly rejects the `ref` prop on any element -- including Client Components -- with: _"Refs cannot be used in Server Components, nor passed to Client Components."_ Refs are inherently a client-side concept -- if a Client Component needs a ref, it should create one itself with `useRef()`. Any library that relies on these features must be used within a `'use client'` boundary. The React Working Group maintains a [canonical tracking list](https://github.com/reactwg/server-components/discussions/6) of library RSC support status. ## The Thin Wrapper Pattern The most common solution for incompatible libraries: create a minimal `'use client'` file that re-exports the component. This works because [`'use client'` marks a boundary](rsc-component-patterns.md#use-client-marks-a-boundary-not-a-component-type) -- the wrapper establishes the server-to-client transition point, and the library code below it automatically becomes client code. ### Direct Re-export (Simplest) ```jsx // ui/carousel.jsx 'use client'; import { Carousel } from 'acme-carousel'; export default Carousel; ``` Then use it in a Server Component: ```jsx // Page.jsx -- Server Component import Carousel from './ui/carousel'; export default function Page() { return ( <div> <p>View pictures</p> <Carousel /> </div> ); } ``` ### Named Re-exports (Multiple Components) ```jsx // ui/chart-components.jsx 'use client'; export { AreaChart, BarChart, LineChart, Tooltip, Legend } from 'recharts'; ``` ### Wrapper with Default Props ```jsx // ui/date-picker.jsx 'use client'; import DatePicker from 'react-datepicker'; import 'react-datepicker/dist/react-datepicker.css'; export default function AppDatePicker(props) { return <DatePicker dateFormat="yyyy-MM-dd" {...props} />; } ``` ### Provider Wrapper ```jsx // providers/query-provider.jsx 'use client'; import { QueryClient, QueryClientProvider } from '@tanstack/react-query'; import { useState } from 'react'; export default function QueryProvider({ children }) { const [queryClient] = useState(() => new QueryClient()); return <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>; } ``` ## CSS-in-JS Libraries CSS-in-JS is the most impactful compatibility challenge for RSC migration. Runtime CSS-in-JS libraries depend on React Context and re-rendering, which Server Components fundamentally lack. For React on Rails Pro bundle and asset-loading patterns, see [CSS and Styling with React Server Components](../../pro/react-server-components/css-and-styling.md). ### Runtime CSS-in-JS (Problematic) | Library | RSC Status | Notes | | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | **styled-components** | In maintenance mode. The v6.3.x series added incremental RSC compatibility fixes (e.g., suppressing server-side warnings in v6.3.3, fixing `createGlobalStyle` unmount behavior with React 19's `precedence` attribute in v6.3.9). | The maintainer stated: "For new projects, I would not recommend adopting styled-components." React Context dependency is the root incompatibility. | | **Emotion** | No native RSC support | Workaround: wrap all Emotion-styled components in `'use client'` files. | ### Zero-Runtime CSS-in-JS (RSC Compatible) | Library | Notes | | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | **Tailwind CSS** | No runtime JS. The standard choice for RSC projects. | | **CSS Modules** | Built into most frameworks. No runtime overhead. | | **Panda CSS** | Zero-runtime, type-safe, created by Chakra UI team. RSC-compatible by design. | | **Pigment CSS** | Created by MUI. Compiles to CSS Modules. Check the [Pigment CSS repo](https://github.com/mui/pigment-css) for current stability status. | | **vanilla-extract** | TypeScript-native. Known issue: `.css.ts` imports in RSC may need `swc-plugin-vanilla-extract` workaround. | | **StyleX** | Facebook's compile-time solution. | | **Linaria** | Zero-runtime with familiar styled API. | **Migration advice:** If you're currently using styled-components or Emotion and your app's performance is acceptable, there's no urgency to migrate. But for new RSC projects, choose a zero-runtime solution. ## UI Component Libraries ### shadcn/ui **Best RSC compatibility.** Copy-paste model means you own the source code and control exactly which components have `'use client'`. Built on Radix + Tailwind. ### Radix UI Best-in-class RSC compatibility among full-featured headless libraries. Non-interactive primitives can be Server Components. Interactive primitives (`Dialog`, `Popover`, etc.) still need `'use client'`. ### Material UI (MUI) All MUI components require `'use client'` due to Emotion dependency. None can be used as pure Server Components. **v5.14.0+** added `'use client'` directives, so components work alongside Server Components without manual wrappers. Use direct imports (e.g., `import Button from '@mui/material/Button'`) instead of barrel imports to avoid bundling the entire library. ### Chakra UI Requires `'use client'` for all components due to Emotion runtime. The Chakra team created **Panda CSS** and **Ark UI** as RSC-compatible alternatives. ### Mantine All components include `'use client'` directives. Cannot use compound components (`<Tabs.Tab />`) in Server Components -- use non-compound equivalents (`<TabsTab />`). ## Form Libraries | Library | RSC Pattern | Notes | | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | | **React Hook Form** | Client-only (uses Context). Create a `'use client'` form component, import into Server Component. Submit to Rails controller endpoints via `fetch`. | Most popular option. | | **TanStack Form** | Emerging alternative with RSC-aware architecture. Submit to Rails controller endpoints. | Framework-agnostic. | | **Standard forms** | Use Rails' standard form helpers (`form_with`, `form_tag`) for non-React forms. For React forms, submit via `fetch` to Rails API endpoints. | No library needed for simple forms. | ### Form Submission Pattern > **Important:** React on Rails does **not** support Server Actions (`'use server'`). Server Actions run on the Node renderer, which has no access to Rails models, sessions, cookies, or CSRF protection. Use Rails controllers for all form submissions. ```jsx // UserForm.jsx -- Client Component 'use client'; import { useState } from 'react'; import ReactOnRails from 'react-on-rails'; export default function UserForm() { const [name, setName] = useState(''); async function handleSubmit(e) { e.preventDefault(); const response = await fetch('/api/users', { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-CSRF-Token': ReactOnRails.authenticityToken(), }, body: JSON.stringify({ user: { name } }), }); if (!response.ok) throw new Error(`Request failed: ${response.status}`); setName(''); } return ( <form onSubmit={handleSubmit}> <input type="text" value={name} onChange={(e) => setName(e.target.value)} /> <button type="submit">Submit</button> </form> ); } ``` ```erb <%# ERB view %> <%= stream_react_component("UserForm") %> ``` **Pattern 2: Standard Rails form (no JavaScript required)** ```erb <%= form_with(model: @user, url: users_path, local: true) do |f| %> <%= f.text_field :name %> <%= f.submit "Submit" %> <% end %> ``` > **Note:** `local: true` is required for Rails 5.1–6.0, where `form_with` defaults to `remote: true` (Ajax). Rails 6.1+ defaults to `local: true`, so it can be omitted on newer versions. Both patterns leverage Rails' full controller/model layer -- authentication, authorization, CSRF protection, and validations all work as expected. ## Animation Libraries | Library | RSC Status | Notes | | -------------------------- | ------------------------------------ | ------------------------------------------------------- | | **Framer Motion / Motion** | Client-only. Relies on browser APIs. | Wrap animated elements in `'use client'` files. | | **React Spring** | Client-only. Uses hooks. | Same wrapper pattern. | | **CSS animations** | Fully compatible | `@keyframes`, `transition`, Tailwind animate utilities. | | **View Transitions API** | Browser-native, compatible | No React dependency. | ### Animation Wrapper Pattern ```jsx // ui/animated-div.jsx 'use client'; import { motion } from 'motion/react'; export default function AnimatedDiv({ children, ...props }) { return <motion.div {...props}>{children}</motion.div>; } ``` ## Charting Libraries | Library | RSC Compatibility | Notes | | ------------------------------ | -------------------- | ----------------------------------------------------------------------- | | **Nivo** | Best RSC support | Pre-renders SVG charts on the server. | | **Recharts** | Client-only | SVG + React hooks. Needs `'use client'` wrapper. | | **Chart.js / react-chartjs-2** | Client-only | Canvas-based, requires DOM. | | **D3.js** | Partially compatible | Data transformation works server-side. DOM manipulation is client-only. | | **Tremor** | Client-only | Built on Recharts + Tailwind. | ## Date Libraries All major date libraries work in Server Components since they are pure utility functions with no React or browser dependencies: - **date-fns** -- tree-shakable, recommended - **dayjs** -- lightweight alternative - **Moment.js** -- works but deprecated and not tree-shakable **Performance benefit:** These dependencies stay entirely server-side when used in Server Components, removing them from the client bundle. ## Data Fetching Libraries | Library | RSC Pattern | Notes | | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | **React on Rails Pro streaming** | Recommended for React on Rails. Rails streams components via `stream_react_component`, or slow emitted props via `stream_react_component_with_async_props`. | See [Data Fetching Migration](rsc-data-fetching.md#data-fetching-in-react-on-rails-pro) for details. | | **TanStack Query** | Prefetch on server with `queryClient.prefetchQuery()`, hydrate on client with `HydrationBoundary`. | See [Data Fetching Migration](rsc-data-fetching.md) for details. | | **Apollo Client** | Server-side queries in Server Components, `ApolloProvider` for client queries. | Requires `'use client'` wrapper for provider. | | **SWR** | Client-only hooks. Use `fallbackData` pattern: fetch in Server Component, pass as props. | See [Data Fetching Migration](rsc-data-fetching.md) for details. | ## Internationalization | Library | RSC Pattern | Notes | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- | | **Rails I18n + react-intl** | Pass translations from Rails controller as props. Server Components use `createIntl` from `react-intl/server` for full formatting (interpolation, pluralization, dates); Client Components use `<IntlProvider>` + `useIntl()`. | Recommended for React on Rails. See [Context guide](rsc-context-and-state.md#i18n-provider). | | **i18next / react-i18next** | `react-i18next` hooks (`useTranslation`) require `'use client'`. For Server Components, `i18next` can be initialized per-request via `i18next.createInstance()` and used without hooks — but you must manage locale/namespace initialization yourself. | Requires per-request setup; not used in this codebase. | ## Authentication In React on Rails, authentication is handled by Rails (Devise, OmniAuth, etc.) before the React component renders. The controller passes the authenticated user as props: ```ruby # Rails controller handles auth, passes user to component stream_react_component("Dashboard", props: { user: current_user.as_json(only: [:id, :name, :email]) }) ``` This is a simpler model than client-side auth libraries -- Rails middleware handles sessions, CSRF protection, and authorization before any React code executes. See the [auth provider pattern](rsc-context-and-state.md#auth-provider) for passing auth data to nested Client Components via Context. ## The Barrel File Problem Barrel files (`index.js` files that re-export from many modules) cause serious issues with RSC. ### The Problem ```jsx // components/index.js -- barrel file export { Button } from './Button'; export { Modal } from './Modal'; export { Chart } from './Chart'; // ... hundreds more ``` When you `import { Button } from './components'`, the bundler must parse the entire barrel file and all transitive imports. With RSC: 1. **Client boundary infection:** Adding `'use client'` to a barrel file forces ALL exports into the client bundle 2. **Tree-shaking failure:** Bundlers struggle to eliminate unused exports 3. **Mixed server/client exports:** A barrel file that re-exports both server and client components can cause unexpected bundle inclusion ### The Solution: Direct Imports The most reliable fix is to bypass barrel files entirely. Use direct imports instead: ```jsx // BAD: Import from barrel -- pulls in everything import { Button } from './components'; import { AlertIcon } from 'lucide-react'; // GOOD: Import directly -- only bundles what you use import Button from './components/Button'; import AlertIcon from 'lucide-react/dist/esm/icons/alert'; ``` For third-party packages, check if the library provides direct import paths (most popular libraries do). For example: - `@mui/material/Button` instead of `{ Button } from '@mui/material'` - `lodash-es/debounce` instead of `{ debounce } from 'lodash-es'` ### For Your Own Code Avoid creating barrel files that mix server and client components. If you must use a barrel file, keep separate barrels for server and client exports: [Diagram: Static diagram showing how a single barrel file (index.js) with 'use client' contaminates all re-exports, and the fix using separate server/client barrels to keep imports isolated.] ## The `server-only` and `client-only` Packages These packages act as build-time guards to prevent code from running in the wrong environment: ```jsx // lib/database.js import 'server-only'; // Build error if imported in a Client Component export async function getUser(id) { return await db.users.findUnique({ where: { id } }); } ``` > **React on Rails note:** The example above illustrates `server-only` in a generic RSC context. In React on Rails, the Node renderer has no database connection — database access stays in Rails controllers, which pass the results to components as props or [async props](rsc-data-fetching.md#async-props-stream-each-slow-prop-independently). See [RSC Data Fetching Patterns](rsc-data-fetching.md). ```jsx // lib/analytics.js import 'client-only'; // Build error if imported in a Server Component export function trackEvent(event) { window.analytics.track(event); } ``` Use `server-only` for: - Modules that use API keys or secrets - Server-side utility functions - Database access modules (in frameworks where the server runtime has DB access — **not** React on Rails, where Rails controllers handle data access) Use `client-only` for: - Browser analytics - Modules that access `window`, `document`, `localStorage` - Client-specific utilities ## Library Compatibility Decision Matrix | Category | RSC-Native Choices | Requires `'use client'` Wrapper | Avoid / Migrate Away From | | ----------------- | ------------------------------------------------------------------ | -------------------------------------------- | -------------------------------------------------- | | **Styling** | Tailwind, CSS Modules, Panda CSS | vanilla-extract (with workaround) | styled-components (maintenance mode), Emotion | | **UI Components** | shadcn/ui, Radix (non-interactive) | MUI, Chakra, Mantine, Radix (interactive) | CSS-in-JS-dependent UI libs without migration path | | **Forms** | Rails controller endpoints + standard forms | React Hook Form, TanStack Form | Formik (less maintained) | | **Animation** | CSS animations, Tailwind animate | Framer Motion/Motion, React Spring | -- | | **Charts** | Nivo (SSR support) | Recharts, Tremor, Chart.js | -- | | **Data Fetching** | React on Rails Pro streaming, bundled or injected HTTP clients | TanStack Query (with hydration), Apollo, SWR | -- | | **State** | Server Component props, `React.cache` | Zustand, Jotai (v2.6+), Redux Toolkit | Recoil (discontinued) | | **i18n** | Rails I18n + `react-intl/server` (Server), `IntlProvider` (Client) | react-i18next (hooks require `'use client'`) | -- | | **Auth** | Rails auth (Devise, etc.) via controller props | -- | -- | | **Date Utils** | date-fns, dayjs (pure functions) | -- | Moment.js (not tree-shakable) | ## Common Mistakes ### Mistake 1: Adding `'use client'` to a barrel file Marking a barrel file (e.g., `components/index.js`) with `'use client'` forces every export into the client bundle, even components that could be Server Components: ```jsx // BAD: All 50 exported components become Client Components 'use client'; export { Header } from './Header'; export { Footer } from './Footer'; export { ProductCard } from './ProductCard'; // ... 47 more ``` **Fix:** Add `'use client'` only to individual component files that actually need it. Better yet, avoid barrel files entirely and use direct imports. ### Mistake 2: Not checking library RSC compatibility before migrating Starting a component migration only to discover that a deeply nested dependency uses hooks wastes significant time. **Fix:** Before removing `'use client'` from a component, audit its import tree. Run a build with the change and look for errors like _"You're importing a component that needs useState."_ The [React Working Group compatibility list](https://github.com/reactwg/server-components/discussions/6) tracks library status. ### Mistake 3: Using barrel imports across `'use client'` boundaries In standard (non-RSC) builds, modern bundlers tree-shake barrel imports effectively -- `import { Button } from '@mui/material'` produces roughly the same output as the direct path import. However, **at `'use client'` boundaries**, the full transitive import graph is included in the client bundle because webpack must serialize the entire module for the RSC manifest. This makes import granularity matter specifically in RSC: ```jsx // AVOID at 'use client' boundaries: pulls in the full import graph import { Button } from '@mui/material'; // PREFER: direct import keeps the client boundary small import Button from '@mui/material/Button'; ``` ```jsx // AVOID at 'use client' boundaries import { debounce } from 'lodash'; // PREFER: imports only what's needed import debounce from 'lodash-es/debounce'; ``` > **Note:** Outside of `'use client'` files, barrel imports are generally fine with modern bundlers. This advice is specific to files that form RSC client boundaries. ### Mistake 4: Continuing to use runtime CSS-in-JS without a plan Styled-components and Emotion work inside `'use client'` boundaries, but they prevent those components from ever becoming Server Components. If your migration goal includes reducing JavaScript bundle size, CSS-in-JS will be the bottleneck. **Fix:** For new components, use Tailwind CSS, CSS Modules, or another zero-runtime solution. For existing styled-components/Emotion code, create a migration plan or accept that those components will remain Client Components. ## Next Steps - [Troubleshooting and Common Pitfalls](rsc-troubleshooting.md) -- debugging and avoiding problems - [Data Fetching Migration](rsc-data-fetching.md) -- migrating from useEffect to server-side fetching - [HTTP Response Ownership](rsc-http-response-patterns.md) -- status codes, redirects, and cache headers ================================================================================ PAGE: https://reactonrails.com/docs/migrating/rsc-troubleshooting SOURCE: docs/oss/migrating/rsc-troubleshooting.md ================================================================================ # RSC Migration: Troubleshooting and Common Pitfalls This guide covers the most common problems you'll encounter when migrating to React Server Components, with concrete solutions for each. Use it as a reference when you hit errors or unexpected behavior. > **Part 7 of the [RSC Migration Series](migrating-to-rsc.md)** | Previous: [Third-Party Library Compatibility](rsc-third-party-libs.md) | Next: [Flight Payload Optimization](rsc-flight-payload.md) ## Diagnostic Quick-Reference When something goes wrong during RSC migration, start here. This table maps symptoms to the most likely cause and the relevant section in this guide: | Symptom | Most Likely Cause | Section | | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | Build error: _"cannot be passed directly to Client Components"_ | Passing functions or class instances across the server-client boundary | [Serialization Boundary Issues](#serialization-boundary-issues) | | Build error: _"needs useState/useEffect"_ | Using hooks in a Server Component file | [Error Message Catalog](#error-message-catalog) | | RSC page downloads unexpectedly large JS chunks | Chunk contamination from shared `'use client'` modules | [Chunk Contamination](#chunk-contamination) | | Static RSC route is fast after emptying `clientReferences`, but client islands fail later | The RSC client-reference manifest no longer includes needed Client Components | [Client Reference Scope and Empty `clientReferences`](#client-reference-scope-and-empty-clientreferences) | | RSC conversion looks faster but visible UI changed or assets are missing | Performance was measured without visual parity or equivalent assets | [RSC Performance Validation](rsc-performance-validation.md) | | Mostly static RSC page still loads the full global browser pack | Static shell needs a page-scoped global-JS opt-out and a small sidecar for remaining behavior | [Mostly Static RSC Shell With a Tiny Sidecar](rsc-static-shell-sidecar.md) | | Global CSS resets change only on RSC pages | Bare element selectors in an RSC CSS Module winning source-order ties | [RSC Stylesheet Injection](#rsc-stylesheet-injection-render-blocking-links-and-cascade-order) | | Component stays a Client Component after removing `'use client'` | Imported by another `'use client'` file, or RSC bundle not rebuilding | [Accidental Client Components](#accidental-client-components) | | Hydration mismatch warnings in console | Server/client render output differs (timestamps, browser APIs, invalid HTML) | [Hydration Mismatches](#hydration-mismatches) | | `ReferenceError: performance is not defined` | Node renderer VM context missing globals | [Node Renderer VM Context](#node-renderer-vm-context----missing-globals) | | `ReferenceError: fetch is not defined` (or `Headers`, `Request`, `Response`, `AbortController`, `AbortSignal`) | Node renderer VM context missing fetch globals | [Node Renderer VM Context](#node-renderer-vm-context----missing-globals) | | `ReferenceError: require is not defined` | Server bundle or RSC bundle uses `externals` for Node builtins instead of `resolve.fallback` | [Handling Node Builtins](#handling-node-builtins----externals-vs-resolvefallback) | | `ReferenceError: MessageChannel is not defined` | `react-dom/server.browser` needs `MessageChannel` at load time in VM sandbox | [MessageChannel Not Defined](#messagechannel-not-defined) | | RSC says a module is missing from the React Client Manifest and the manifest is empty in Rspack `bin/dev` | Rspack lazy compilation deferred RSC client references before the server renderer read them | [Empty Client Manifest with Rspack Dev Server](#empty-client-manifest-with-rspack-dev-server) | | SSR hangs or times out on large pages | Stream backpressure deadlock | [Stream Backpressure Deadlock](#stream-backpressure-deadlock) | | Rails boot error about version mismatch | Gem and npm package at different versions | [Gem and npm Package Version Mismatch](#gem-and-npm-package-version-mismatch) | | 422 Unprocessable Entity on form submission | Missing CSRF token in fetch request | [Mutations](rsc-data-fetching.md#mutations-rails-controllers-not-server-actions) | | Page is blank until all data loads | Missing `stream_react_component` or Suspense boundaries | [Performance Pitfalls](#performance-pitfalls) | ## Serialization Boundary Issues Everything passed from a Server Component to a Client Component must be serializable by React. This is the most frequent source of migration errors. ### What Can Cross the Server-to-Client Boundary | Allowed | Not Allowed | | ----------------------------------------------- | -------------------- | | Strings, numbers, booleans, `null`, `undefined` | Functions | | Plain objects and arrays | Class instances | | `Date` objects | `WeakMap`, `WeakSet` | | `Map`, `Set`, typed arrays (React 19+) | Symbols | | `Promise` (resolved by `use()`) | DOM nodes | | React elements (`<Component />`) | Closures | ### Common Error: Passing Functions ```jsx // ERROR: "Functions cannot be passed directly to Client Components // unless you explicitly expose it by marking it with 'use server'" async function Page() { const handleClick = () => console.log('clicked'); return <ClientButton onClick={handleClick} />; // Breaks! } ``` **Fix 1:** Move the function to the Client Component: ```jsx // Page.jsx -- Server Component export default function Page() { return <ClientButton />; } // ClientButton.jsx 'use client'; export default function ClientButton() { return <button onClick={() => console.log('clicked')}>Click</button>; } ``` **Fix 2:** Move the logic to a Client Component that calls a Rails endpoint: ```jsx // ClientForm.jsx -- Client Component 'use client'; import { useState } from 'react'; import ReactOnRails from 'react-on-rails'; export default function ClientForm() { const [name, setName] = useState(''); async function handleSubmit(e) { e.preventDefault(); const response = await fetch('/api/items', { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-CSRF-Token': ReactOnRails.authenticityToken(), }, body: JSON.stringify({ name }), }); if (!response.ok) throw new Error(`Request failed: ${response.status}`); setName(''); } return ( <form onSubmit={handleSubmit}> <input type="text" value={name} onChange={(e) => setName(e.target.value)} /> <button type="submit">Submit</button> </form> ); } ``` ```erb <%# ERB view %> <%= stream_react_component("ClientForm") %> ``` ### Common Error: railsContext Contains Functions When using React on Rails Pro with RSC, the `railsContext` object includes non-serializable functions (`addPostSSRHook`, `getRSCPayloadStream`). Passing the entire `railsContext` to a Client Component causes: ``` Functions cannot be passed directly to Client Components unless you explicitly expose it by marking it with "use server". ``` **Fix:** Strip non-serializable properties before passing to Client Components: ```jsx // Server Component (render function) const MyPage = (props, railsContext) => { const { addPostSSRHook, getRSCPayloadStream, ...serializableContext } = railsContext; return () => <ClientComponent {...props} railsContext={serializableContext} />; }; ``` > **Note:** React on Rails does **not** support Server Actions (`'use server'`). Server Actions run on the Node renderer, which has no access to Rails models, sessions, cookies, or CSRF protection. Use Rails controller endpoints for all mutations. ### Common Error: Passing Class Instances ```jsx // ERROR: Class instances are not serializable async function Page() { const user = await User.findById(1); // Returns a class instance return <ProfileCard user={user} />; // Breaks if ProfileCard is 'use client' } ``` **Fix:** Convert to a plain object: ```jsx async function Page() { const userRecord = await User.findById(1); const user = { id: userRecord.id, name: userRecord.name, email: userRecord.email }; return <ProfileCard user={user} />; } ``` ## Import Chain Contamination The `'use client'` directive operates at the **module level**. Once a file is marked `'use client'`, all its imports become part of the client bundle, even if those imported modules don't use client features. ### The Problem [Diagram: Static diagram showing how a small 'use client' component can inherit large chunk groups from heavier import paths, and the fix using a thin wrapper file to isolate the dependency tree.] ### How to Detect It Use the `server-only` package to create guardrails: ```jsx // lib/db-utils.js import 'server-only'; // Build error if imported into client code export async function getUsers() { return await db.query('SELECT * FROM users'); } ``` If someone imports `db-utils.js` from a Client Component (directly or transitively), the build fails immediately rather than silently shipping server code to the client. ### How to Fix It 1. **Split shared files:** Separate server-only and client-safe utilities into different modules 2. **Use `server-only`:** Add the import to any module containing secrets, database access, or server-only logic 3. **Audit import chains:** Check what each `'use client'` file imports transitively ## Chunk Contamination When a component with `'use client'` is statically imported by both a small RSC path and a heavier client path, the RSC page can inherit chunks from both paths. The impact can be severe (for example, 382 KB instead of 8 KB). [Diagram: Animated before/after showing how a shared import between a heavy page and a small component drags vendor chunks into the RSC page bundle, and the fix that shrinks it by isolating the import.] ### How to Detect It After building, inspect your `react-client-manifest.json`. Each `'use client'` module has a `chunks` array listing the JS files the browser must download. Pro RSC manifests can also include a `css` array listing stylesheet files that React on Rails Pro injects as render-blocking `<link rel="stylesheet" data-precedence="rsc-css">` resources. If you see large vendor chunks or unrelated page-specific CSS listed for a small component, you have contamination: ```json { "file:///app/components/HelloWorldHooks.jsx": { "id": "./components/HelloWorldHooks.jsx", "chunks": ["2", "2-b77936c4.js", "rsc-PostsPage", "rsc-PostsPage-d655b05a.js"], "css": ["css/client-PostsPage-d655b05a.css"], "name": "*" } } ``` In this example, `HelloWorldHooks` (a tiny component) picks up PostsPage chunks, including a 375 KB vendor chunk containing lodash and moment. The browser downloads all of it. If the same contaminated mapping includes `css` entries, the browser can also wait on CSS that the current RSC page does not visually need. You can also check the browser DevTools **Network** tab: load your RSC page, filter to JS and CSS files, and look for unexpectedly large downloads that contain unrelated libraries or page styles. Tools like **webpack-bundle-analyzer** can help visualize which modules ended up in which chunks. ### Why It Happens The RSC client manifest maps each `'use client'` module to the JS chunks the browser needs to download and, in Pro builds with CSS manifest support, the CSS files React links as render-blocking stylesheets for that client boundary. When a `'use client'` module is imported by multiple entry points (for example, both an RSC page and a heavy SSR/client page), its mapping can include chunks and CSS that originate from both paths. When `PostsPage.jsx` (`'use client'`) statically imports `HelloWorldHooks.jsx` along with heavy dependencies (lodash, moment), `HelloWorldHooks.jsx` can inherit chunks from that heavier path. The result is chunk contamination: one small component ends up carrying unrelated chunks because it appears in multiple chunk groups. Redundant `'use client'` directives increase the risk. If a component is already imported by a `'use client'` parent, adding `'use client'` to it too creates extra manifest entries and extra opportunities to accumulate unrelated chunks and stylesheet links. Keep `'use client'` only on files that must be server/client boundaries. ### How to Fix It Create a thin `'use client'` wrapper file that isolates the import tree: ```jsx // HelloWorldHooksClient.jsx -- thin wrapper (new file) 'use client'; import HelloWorldHooks from './HelloWorldHooks'; export default HelloWorldHooks; ``` ```jsx // HelloWorldHooks.jsx -- NO 'use client' directive import React, { useState } from 'react'; export default function HelloWorldHooks({ name }) { const [greeting, setGreeting] = useState(name); return <h3>Hello, {greeting}!</h3>; } ``` ```jsx // RSCPage.jsx -- Server Component imports the wrapper import HelloWorldHooks from './HelloWorldHooksClient'; export default function RSCPage() { return <HelloWorldHooks name="World" />; } ``` The wrapper file doesn't appear in PostsPage's import tree, so it avoids inheriting PostsPage's heavier chunk groups and usually stays mapped to a much smaller chunk footprint. If the contamination is CSS-specific, keep page-specific global CSS out of broad client components. Use CSS Modules, Tailwind utilities, or a route/layout stylesheet for styles that are meant to be shared, and let the thin wrapper import only the CSS needed by that RSC boundary. Also watch for cascade changes. React inserts the `data-precedence="rsc-css"` stylesheet group after precedence-less stylesheets already in `<head>`, such as links emitted by Rails layouts, so contaminated framework or page CSS can win source-order ties on unrelated pages. CSS Modules scope class names, but bare element selectors such as `html`, `body`, or `a:focus` still apply globally once their stylesheet is delivered. ### When the Wrapper Isn't Enough: Prop Injection If a shared component is used by both RSC and SSR/client paths, the wrapper alone may not fully isolate imports. In that case, remove the import edge by passing client elements as props. ```jsx // InteractiveWidgetsClient.jsx -- thin wrapper used by the RSC path 'use client'; export { AddToCartButton } from './InteractiveWidgets'; ``` ```jsx // ProductCard.jsx BEFORE -- direct client import in a shared component import { AddToCartButton } from './InteractiveWidgets'; export function ProductCard({ product }) { return ( <div> <h3>{product.name}</h3> <AddToCartButton productId={product.id} /> </div> ); } ``` ```jsx // ProductCard.jsx AFTER -- no direct 'use client' imports export function ProductCard({ product, addToCartButton }) { return ( <div> <h3>{product.name}</h3> {addToCartButton} </div> ); } ``` ```jsx // RSCPage.jsx -- Server Component (prop injection via thin wrapper) import { AddToCartButton } from './InteractiveWidgetsClient'; import { ProductCard } from './ProductCard'; export default function RSCPage({ products }) { return products.map((product) => ( <ProductCard key={product.id} product={product} addToCartButton={<AddToCartButton productId={product.id} />} /> )); } ``` ```jsx // SSRPage.jsx -- client/SSR path can import the heavier module directly import { AddToCartButton } from './InteractiveWidgets'; import { ProductCard } from './ProductCard'; export default function SSRPage({ products }) { return products.map((product) => ( <ProductCard key={product.id} product={product} addToCartButton={<AddToCartButton productId={product.id} />} /> )); } ``` The RSC path uses `InteractiveWidgetsClient` (thin wrapper) to keep ProductCard's import edge clean, while the SSR path can import the full `InteractiveWidgets` module without affecting the RSC manifest for ProductCard. > **When to apply this:** Check the manifest or Network tab after building. If an RSC page downloads chunks larger than expected, start with a thin wrapper. If contamination persists because the component is shared across RSC and non-RSC entry points, use prop injection to remove the shared import edge. ## Client Reference Scope and Empty `clientReferences` The RSC client manifest maps each `'use client'` module to the browser chunks needed to hydrate that Client Component when an RSC payload references it. The `clientReferences` option on `RSCWebpackPlugin` controls what the plugin can discover and emit into both `react-client-manifest.json` and `react-server-client-manifest.json`; it is not just a performance knob. ### The Static-Page Trap A purely static RSC page with no client islands can render even when the build has no client references: ```js // Safe only for a build that never renders RSC client islands. const rscClientReferences = []; ``` That can make the static page appear faster because it avoids unrelated client-reference cost. However, a later RSC page that imports a `'use client'` search box, button, menu, or form can fail because the manifest lacks the reference needed to load and hydrate the island. The failure may not appear until someone adds that client island to a route that shares the same build. Route/page/entry-scoped manifests are the desired long-term fix, tracked in [react_on_rails_rsc#134](https://github.com/shakacode/react_on_rails_rsc/issues/134). Related RSC sidecar and scoped-loading design work is tracked in [react_on_rails_rsc#145](https://github.com/shakacode/react_on_rails_rsc/issues/145). ### Decision Guide | Scenario | Safe guidance | | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Static RSC page with no client islands, isolated build | Empty or narrow client references may be acceptable if the affected routes are documented and covered by tests. | | Mixed RSC app with both static pages and client islands | Do not globally empty `clientReferences`; use normal app-source discovery until route-scoped manifests exist. | | Small RSC page downloads large unrelated chunks | Inspect `react-client-manifest.json`, reduce `'use client'` boundaries, use thin wrappers or prop injection, and check `clientReferences` scope. | | Browser sidecar handles behavior outside the RSC payload | Keep the sidecar distinct from RSC client references; sidecar success does not prove RSC client islands still work. | | Temporary app workaround is required | Document affected routes, add smoke tests for RSC routes with client islands, and link the workaround to [react_on_rails_rsc#134](https://github.com/shakacode/react_on_rails_rsc/issues/134). | ### How to Detect It - Inspect `react-client-manifest.json` for unexpected entries that explain large downloads, or for a missing entry for a Client Component you expect an RSC route to render. - Compare the browser Network tab for a static RSC route before and after narrowing client references. Look for large vendor/app chunks loaded before interaction. - If a page with no islands improved after `clientReferences = []`, test a second RSC route that renders a tiny known Client Component from the same build. - Use [RSC Client Reference Diagnostics](../../pro/react-server-components/client-reference-diagnostics.md) to derive a local report for emitted client-reference chunks and asset byte totals from the client manifest. - Distinguish this from the Rspack dev-server lazy-compilation issue: if the manifest is empty only in normal `bin/dev` and generated bundles mention `lazy-compilation-proxy`, see [Empty Client Manifest with Rspack Dev Server](#empty-client-manifest-with-rspack-dev-server). ### Safer Interim Mitigations - Push `'use client'` boundaries down to real interactive leaves. - Remove redundant `'use client'` directives inside already-client subtrees. - Use thin client wrapper files for RSC entry paths. - Use prop injection to remove shared import edges when a component is used by both RSC and non-RSC paths. - Scope `clientReferences` to the app source directory rather than the whole project when broad default scanning is the issue. - Isolate static-only builds only when the app can prove no client islands depend on that build. - Keep browser sidecars as plain browser JavaScript. The mostly-static sidecar pattern tracked in [#4300](https://github.com/shakacode/react_on_rails/issues/4300) and documented in [Mostly Static RSC Shell With a Tiny Sidecar](rsc-static-shell-sidecar.md) is separate from RSC client-reference discovery. - For broader chunk-contamination work, follow this guide's [Chunk Contamination](#chunk-contamination) section and the package-level context in [#4111](https://github.com/shakacode/react_on_rails/issues/4111). ## RSC Stylesheet Injection: Render-Blocking Links and Cascade Order This section documents the current RSC stylesheet injection behavior so you know what to expect in the page source — it is not an open defect. It applies to React 19+ installations; earlier React versions do not support the `data-precedence` stylesheet groups used for this hoisting and render-blocking behavior. For RSC pages, React on Rails Pro injects `<link rel="stylesheet" data-precedence="rsc-css">` tags for CSS hrefs whose client chunk names appear in the current Flight payload. These links are **render-blocking** for the streamed RSC tree: React delays committing the streamed content until the referenced stylesheets are ready, which prevents a flash of unstyled content (FOUC) as the tree streams in. ### Per-reference broadcast multiplication (fixed in the 19.2 line) Earlier versions re-broadcast shared vendor and common CSS _per client reference_, multiplying the same `<link>` tag across every reference that depended on it. This was fixed upstream in `react-on-rails-rsc` 19.2.0-rc.3 via: - [react_on_rails_rsc#108](https://github.com/shakacode/react_on_rails_rsc/pull/108) - [react_on_rails_rsc#110](https://github.com/shakacode/react_on_rails_rsc/pull/110) - [react_on_rails_rsc#113](https://github.com/shakacode/react_on_rails_rsc/pull/113) If you see the same vendor stylesheet `<link>` repeated many times in an RSC page, use a coordinated React 19.2-compatible release set once stable Pro metadata is available. Key constraints: - The fix landed in `react-on-rails-rsc` 19.2.0-rc.3. Check the [react_on_rails_rsc releases](https://github.com/shakacode/react_on_rails_rsc/releases) and the Pro release notes to determine whether a stable, coordinated release incorporating 19.2.x is available and accepted by your Pro peer metadata. Do not install the rc prerelease in production unless the Pro release notes name a matching package or peer range. - **Do not** bump `react-on-rails-rsc` on its own; it must be upgraded together with a compatible React, React DOM, and React on Rails Pro set, or the Pro node renderer's peer-compatibility check can fail at startup. - **Do not** use the default React 19.0.x generator pin from [Upgrading an existing Pro app](../../pro/react-server-components/upgrading-existing-pro-app.md) for this duplicate-CSS fix; that guide remains the baseline 19.0.x RSC setup path. - Use maintainer-provided 19.2 compatibility guidance for the exact React, React DOM, React on Rails Pro, and `react-on-rails-rsc` versions. On a supported, coordinated version set this is resolved — the shared CSS is emitted once. ### Cascade order The `data-precedence="rsc-css"` group lands at the **end** of `<head>`, after precedence-less stylesheets such as the Rails-layout `stylesheet_pack_tag` links. This means rsc-css links win source-order ties when specificity is equal, and bare element selectors inside RSC CSS Modules can override globals once their stylesheet is delivered. See [CSS cascade guidance](../../pro/react-server-components/css-and-styling.md#rsc-stylesheet-cascade-order-end-of-head-precedence) for the full explanation and the cautionary `html { font-size }` example. See [React Performance Tracks and Profiling](../building-features/performance-tracks-and-profiling.md#measuring-an-rsc-conversion-with-a-paired-ab) to measure the end-to-end performance impact of RSC changes with a paired A/B comparison. ## Accidental Client Components A component that should be a Server Component becomes a Client Component because it's imported by a `'use client'` file. ### The Problem ```jsx // BAD: ServerComponent becomes client code via import 'use client'; import ServerComponent from './ServerComponent'; export function ClientWrapper() { return <ServerComponent />; // This is now client code! } ``` ### The Fix: Children Pattern ```jsx // GOOD: Pass Server Components as children 'use client'; export function ClientWrapper({ children }) { return <div>{children}</div>; } // In a Server Component parent: import ClientWrapper from './ClientWrapper'; import ServerComponent from './ServerComponent'; export default function Page() { return ( <ClientWrapper> <ServerComponent /> {/* Stays a Server Component */} </ClientWrapper> ); } ``` ### Why It Works The Server Component (`Page`) is the "owner" -- it decides what `ServerComponent` receives as props and renders it on the server. `ClientWrapper` receives pre-rendered content as `children`, not the component definition. ## Hydration Mismatches Hydration mismatches occur when server-rendered HTML doesn't match what React produces during client-side hydration. ### Common Causes | Cause | Example | Fix | | -------------------- | -------------------------------------------- | ------------------------------------------------------------------- | | Timestamps | `new Date()` differs server vs client | Use `suppressHydrationWarning` or render in `useEffect` | | Browser APIs | `window.innerWidth` is `undefined` on server | Guard with `typeof window !== 'undefined'` or use `useEffect` | | `localStorage` reads | Theme preference stored in browser | Read from cookie on server, or delay render with `useEffect` | | Random values | `Math.random()` produces different results | Generate on server, pass as prop | | Browser extensions | Extensions inject unexpected HTML | Cannot prevent; use `suppressHydrationWarning` on affected elements | | Invalid HTML nesting | `<p>` inside `<p>`, `<div>` inside `<p>` | Fix HTML structure | ### Error Messages - `"Text content does not match server-rendered HTML"` - `"Hydration failed because the initial UI does not match what was rendered on the server"` - `"There was an error while hydrating. Because the error happened outside of a Suspense boundary, the entire root will switch to client rendering."` ### The "Mounted" Pattern for Client-Only Rendering ```jsx 'use client'; import { useState, useEffect } from 'react'; function ThemeToggle() { const [mounted, setMounted] = useState(false); useEffect(() => setMounted(true), []); if (!mounted) return null; // Server and first client render return null // Only runs on client return <button>{localStorage.getItem('theme')}</button>; } ``` ### `suppressHydrationWarning` For elements that intentionally differ between server and client: ```jsx <time suppressHydrationWarning>{new Date().toLocaleDateString()}</time> ``` This suppresses the warning for **this element only** (not its descendants) and does not fix the mismatch -- use it only for non-critical content. If child elements also differ, each needs its own `suppressHydrationWarning`. > [!WARNING] > The `if (!mounted) return null` pattern causes **Cumulative Layout Shift (CLS)** -- the element occupies no space on first paint, then pops in after hydration. Only use it for small, positionally stable UI elements (icon buttons, toggles). For anything that affects page layout, read the preference from a server-readable cookie to render the correct value on first paint (see the [Theme Provider](rsc-context-and-state.md#theme-provider-no-flash-of-wrong-theme) section), or use `suppressHydrationWarning` on non-layout-critical elements. ## Error Boundary Limitations Error Boundaries do **not** catch errors thrown during the initial Server Component HTML stream -- those errors bypass client-side Error Boundaries entirely. However, errors during RSC payload fetches (client-side navigations, `refetchComponent` calls) surface as `ServerComponentFetchError` and **can** be caught by Error Boundaries. ### Workaround: Retry with Page Reload Since React on Rails renders each component tree independently via `stream_react_component`, a full page reload re-renders all Server Components on the server: ```jsx 'use client'; import { ErrorBoundary } from 'react-error-boundary'; function ErrorFallback({ error, resetErrorBoundary }) { function retry() { window.location.reload(); // Re-renders Server Components on the server } return ( <div> <p>Something went wrong</p> <button onClick={retry}>Retry</button> </div> ); } export default function PageErrorBoundary({ children }) { return <ErrorBoundary FallbackComponent={ErrorFallback}>{children}</ErrorBoundary>; } ``` ### Finer-Grained Retry with `refetchComponent` React on Rails Pro provides `useRSC()` with a `refetchComponent` method that re-fetches a single Server Component's RSC payload without a full page reload: ```jsx 'use client'; import { ErrorBoundary } from 'react-error-boundary'; import { useRSC } from 'react-on-rails-pro/RSCProvider'; import { isServerComponentFetchError } from 'react-on-rails-pro/ServerComponentFetchError'; function ErrorFallback({ error, resetErrorBoundary }) { const { refetchComponent } = useRSC(); function retry() { if (isServerComponentFetchError(error)) { const { serverComponentName, serverComponentProps } = error; refetchComponent(serverComponentName, serverComponentProps) .catch((err) => console.error('Retry failed:', err)) .finally(() => resetErrorBoundary()); } else { window.location.reload(); } } return ( <div> <p>Something went wrong</p> <button onClick={retry}>Retry</button> </div> ); } export default function PageErrorBoundary({ children }) { return <ErrorBoundary FallbackComponent={ErrorFallback}>{children}</ErrorBoundary>; } ``` `refetchComponent` re-fetches the RSC payload for the named component with `enforceRefetch: true`, bypassing any cached promise. This is the React on Rails equivalent of Next.js's `router.refresh()`. For refetch triggers that aren't part of an error-recovery flow — a "Refresh" toolbar button, a websocket-driven invalidation, or an inline refresh button rendered by the server component itself — see [Manually refetching a server component](../../pro/react-server-components/inside-client-components.md#manually-refetching-a-server-component) for the `<RSCRoute ref={...}>` and `useCurrentRSCRoute()` APIs that don't require the caller to know the component's name or props. ## `'use client'` Directive Mistakes ### Only at the Boundary `'use client'` marks the server-to-client boundary, not individual components. Components imported below a `'use client'` file are automatically client code -- they don't need their own directive. Adding it redundantly creates unnecessary webpack async chunks and increases [chunk contamination](#chunk-contamination) risk. See [the boundary rule](rsc-component-patterns.md#use-client-marks-a-boundary-not-a-component-type) for details. ### Must Be at the Very Top **BAD:** Directive after imports ```text import { useState } from 'react'; 'use client'; // Too late -- will not work ``` **GOOD:** Directive before everything (comments allowed above) ```jsx 'use client'; import { useState } from 'react'; ``` ### Must Use Quotes, Not Backticks **BAD:** ```text `use client`; ``` **GOOD:** ```jsx 'use client'; ``` ### Confusing `'use client'` with `'use server'` - `'use client'` marks a file's components as **Client Components** - `'use server'` marks **Server Actions** (functions callable from the client) -- NOT Server Components - Server Components are the **default** and need no directive > **React on Rails note:** Server Actions (`'use server'`) are **not supported** in React on Rails. The Node renderer has no access to Rails models, sessions, cookies, or CSRF protection. Use Rails controller endpoints for all mutations. ## Performance Pitfalls ### Server Waterfalls The most common performance regression. Sequential queries in the Rails controller block rendering: ```ruby # BAD: Each query blocks the next (750ms total) def show @user = User.find(params[:user_id]) # 200ms @stats = Stats.for_user(@user.id) # 300ms (waits for user) @posts = Post.where(user_id: @user.id).limit(10) # 250ms (sequential) stream_view_containing_react_components(template: "pages/show") end ``` **Fix 1:** Use Ruby threads for independent data sources: ```ruby # GOOD: Fetch independent data in parallel def show user_id = params[:user_id] results = {} threads = [] threads << Thread.new do ActiveRecord::Base.connection_pool.with_connection do results[:user] = User.find(user_id).as_json end end threads << Thread.new do ActiveRecord::Base.connection_pool.with_connection do results[:stats] = Stats.for_user(user_id).as_json end end threads << Thread.new do ActiveRecord::Base.connection_pool.with_connection do results[:posts] = Post.where(user_id: user_id).limit(10).as_json end end threads.each(&:join) @page_props = { title: "Page" }.merge(results) stream_view_containing_react_components(template: "pages/show") end ``` ```erb <%# GOOD: All data fetched in parallel, rendered with streaming SSR %> <%= stream_react_component("Page", props: @page_props) %> ``` **Fix 2:** Prefetch critical data in the controller and pass all data as props: ```erb <%# All data is passed as props — stream_react_component handles progressive HTML delivery %> <%= stream_react_component("Page", props: { user: current_user.as_json(only: [:id, :name]), stats: Stats.for_user(current_user.id).as_json, posts: Post.where(user_id: current_user.id).limit(10).as_json }) %> ``` See [Data Fetching Migration](rsc-data-fetching.md#avoiding-server-side-waterfalls) for detailed patterns, including `stream_react_component_with_async_props` when slow Rails props should resolve behind Suspense boundaries. ### Missing Suspense Boundaries Without Suspense, Server Components perform similarly to traditional SSR. Benchmarks show that the performance benefit comes from **streaming with Suspense**, not Server Components alone. ### RSC Payload Duplication The RSC payload (a serialized representation of the component tree) is embedded in `<script>` tags alongside the server-rendered HTML. This payload is used by React on the client to reconcile the component tree without re-rendering from scratch. The HTML and the RSC payload are not exact duplicates -- the payload contains component structure and props, not rendered markup -- but they do represent overlapping information, which increases document size. Payload size can grow rapidly when Server Components produce verbose element trees -- particularly with utility-first CSS frameworks like Tailwind, where className strings alone can account for nearly half the payload. Components repeated many times on a page (product cards, review lists, tag grids) amplify this effect. In one benchmark, moving four presentational subtrees from server to client components reduced the raw Flight payload by 42% with only a 2.2 KB client JS increase. For a detailed analysis, measurement techniques, and the decision flowchart for when to apply this optimization, see [Flight Payload Optimization](rsc-flight-payload.md). ## Testing Strategies ### The Fundamental Challenge Async Server Components introduce new testing challenges. Vitest and Jest can test async Server Components as **plain async functions** (call the function, `await` the result, assert on the returned JSX). However, **rendering them through React's component pipeline** (e.g., with `@testing-library/react`) does not yet have full support -- React's test renderer does not handle the async server rendering path. The React team has published guidance on testing patterns, and `@testing-library/react` is actively adding RSC support. ### Recommended Testing Approach ```text Unit Tests (Vitest/Jest) ├── Client Components -- full support with hooks mocking ├── Synchronous Server Components -- basic rendering tests └── Utility/helper functions -- standard unit tests Integration Tests ├── Component composition -- Server + Client together └── Data fetching flows -- mock at the boundary E2E Tests (Playwright) ├── Async Server Components -- the only reliable option currently ├── Streaming behavior -- verify progressive rendering ├── Hydration correctness -- verify interactivity └── Full page flows -- navigation, forms, etc. ``` For Rails system tests that exercise the node renderer, see [RSC and Node Renderer System Tests](../building-features/testing-configuration.md#rsc-and-node-renderer-system-tests). That guide covers test bundle compilation, renderer process startup/shutdown, bundle-cache isolation, parallel-worker caveats, and stubbing external APIs without bypassing the RSC path. ### Testing Mutations In React on Rails, mutations go through Rails controller endpoints rather than Server Actions. Test mutation logic in your Rails controller specs (RSpec request specs) and test the Client Component's form submission behavior with component tests: ```jsx // UserForm.test.jsx import { render, screen, fireEvent, waitFor } from '@testing-library/react'; import ReactOnRails from 'react-on-rails'; import UserForm from './UserForm'; it('submits to the Rails endpoint', async () => { global.fetch = jest.fn(() => Promise.resolve({ ok: true })); jest.spyOn(ReactOnRails, 'authenticityToken').mockReturnValue('test-token'); render(<UserForm />); fireEvent.change(screen.getByRole('textbox'), { target: { value: 'Alice' } }); fireEvent.click(screen.getByText('Submit')); await waitFor(() => expect(global.fetch).toHaveBeenCalledWith( '/api/users', expect.objectContaining({ method: 'POST', }), ), ); }); ``` ## TypeScript Considerations ### Async Component Type Error The most common TypeScript issue: **Error:** `"'App' cannot be used as a JSX component. Its return type 'Promise<JSX.Element>' is not a valid JSX element type."` **Fix:** Upgrade to TypeScript 5.1.2+ with `@types/react@19` (React 19 projects) or `@types/react` 18.2.8+ (React 18 projects), or omit the explicit return type annotation: ```tsx // BROKEN: Explicit return type triggers error in older TS async function Page(): Promise<React.ReactNode> { const data = await fetchData(); return <div>{data.title}</div>; } // FIXED: Let TypeScript infer the type async function Page() { const data = await fetchData(); return <div>{data.title}</div>; } ``` ### Runtime Validation for API Endpoints TypeScript only provides compile-time checking. Rails API endpoints that receive data from React forms should validate input on the server side. Use Rails' built-in model validations and strong parameters in your controllers: ```ruby # app/controllers/api/users_controller.rb class Api::UsersController < ApplicationController def create user = User.new(user_params) if user.save render json: user, status: :created else render json: { errors: user.errors.full_messages }, status: :unprocessable_entity end end private def user_params params.require(:user).permit(:name, :email) end end ``` ## Empty Client Manifest with Rspack Dev Server In RSC apps that use Rspack, normal `bin/dev` dev-server mode must compile RSC client references before the server renderer reads the React Client Manifest. If Rspack lazy compilation is still enabled, the first server render can see an empty manifest and fail with an error like: ```text Could not find the module ".../LikeButton.jsx#default" in the React Client Manifest. ``` Common signs: - `react-client-manifest.json` contains `"filePathToModuleMetadata": {}` - the generated Rspack client bundle mentions `lazy-compilation-proxy` - the browser sends `POST /_rspack/lazy/trigger` and Rails returns `404` - `bin/dev static` works, but normal `bin/dev` fails Run the RSC doctor first: ```bash bundle exec rails react_on_rails:doctor:rsc ``` For existing generated apps, update `config/rspack/development.js` so the Rspack dev-server branch disables lazy compilation when an RSC config is present: ```js const developmentEnvOnly = (clientWebpackConfig, _serverWebpackConfig, rscWebpackConfig) => { if (process.env.WEBPACK_SERVE) { if (config.assets_bundler === 'rspack') { const { ReactRefreshRspackPlugin } = require('@rspack/plugin-react-refresh'); clientWebpackConfig.plugins.push(new ReactRefreshRspackPlugin()); if (rscWebpackConfig) { clientWebpackConfig.lazyCompilation = false; } } } }; ``` Also verify that `config/rspack/ServerClientOrBoth.js` passes the RSC config as the third argument to the environment-specific config hook: ```js envSpecific(clientConfig, serverConfig, rscConfig); ``` If it only passes `clientConfig` and `serverConfig`, rerun the RSC generator to refresh both `ServerClientOrBoth.js` and `development.js`. Fresh generator output includes this guard. If your config has been heavily customized, keep the important behavior: RSC + Rspack + dev-server mode should set `clientWebpackConfig.lazyCompilation = false`. ## Bundle Analysis Tools | Tool | Purpose | | ----------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | | **[webpack-bundle-analyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer)** | Analyze client bundle composition and module sizes | | **[RSC Devtools](https://chromewebstore.google.com/detail/rsc-devtools/jcejahepddjnppkhomnidalpnnnemomn)** (Chrome extension) | Visualize RSC streaming data, server vs client rendering | | **[RSC Parser](https://rsc-parser.vercel.app/)** | Parse the React Flight wire format to inspect the component tree | | **[webpack-stats-explorer](https://github.com/erykpiast/webpack-stats-explorer)** | Interactive exploration of webpack stats for chunk analysis | ### Key Metrics to Track - **JavaScript bundle size** (before/after migration, per page) - **RSC Payload size** (the hidden cost -- check this grows reasonably) - **LCP / TTFB / TBT** (Core Web Vitals) - **Time to Interactive** (hydration cost) - **Server render latency** (new metric to monitor after migration) ## Error Message Catalog | Error Message | Cause | Solution | | ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `"Functions cannot be passed directly to Client Components unless you explicitly expose it by marking it with 'use server'"` | Passing a function prop from Server to Client Component | Define the function in the Client Component, or submit to a Rails controller endpoint. Note: React on Rails does not support Server Actions (`'use server'`). | | `"You're importing a component that needs useState/useEffect..."` | Using hooks in a Server Component | Add `'use client'` to the component file | | `"Only plain objects, and a few built-ins, can be passed to Client Components..."` | Passing class instances or non-serializable values | Convert to plain objects with `.toJSON()` or manual serialization | | `"async/await is not yet supported in Client Components"` | Making a Client Component async. This is an intentional design constraint, not a temporary limitation -- Client Components re-render on state changes, which is incompatible with async rendering. | Move async logic to a Server Component, or use `useEffect`/`use()` | | `"A component was suspended by an uncached promise..."` | Creating a promise inside a Client Component and passing it to `use()` | Pass the promise from a Server Component as a prop, or use a Suspense-compatible library like TanStack Query. See [Common `use()` Mistakes](rsc-data-fetching.md#common-use-mistakes-in-client-components) | | `"createContext is not supported in Server Components"` | Using `createContext` or `useContext` in a Server Component | Move context to a `'use client'` provider wrapper | | `"'App' cannot be used as a JSX component. Its return type 'Promise<JSX.Element>' is not a valid JSX element type"` | TypeScript doesn't recognize async components | Upgrade to TS 5.1.2+ and `@types/react@19` (or `@types/react` 18.2.8+ for React 18), or omit return type | | RSC page downloads unexpectedly large chunks | A shared `'use client'` module appears in multiple entry paths, so its manifest entry accumulates unrelated chunks | Inspect `react-client-manifest.json` for oversized mappings. Start with a thin `'use client'` wrapper; if the component is shared by both RSC and SSR/client paths, use prop injection to remove shared import edges. See [Chunk Contamination](#chunk-contamination). | | RSC client island is missing from the React Client Manifest after narrowing `clientReferences` | The plugin scan no longer covers the `'use client'` module needed by that RSC route | Restore app-source client-reference discovery, or isolate the static-only build and add a client-island smoke test. See [Client Reference Scope and Empty `clientReferences`](#client-reference-scope-and-empty-clientreferences). | | `"Text content does not match server-rendered HTML"` | Hydration mismatch | Ensure identical rendering on server and client; use `suppressHydrationWarning` for intentional differences | | `"Refs cannot be used in Server Components, nor passed to Client Components"` | Using the `ref` prop on any element inside a Server Component -- including on Client Components. The Flight serializer rejects the literal `ref` prop before checking the target type. | Remove the `ref` prop. Refs are a client-side concept -- if a Client Component needs a ref, it should create one itself with `useRef()`. While `React.createRef()` is callable on the server, the result cannot be attached to any element. | | `"Both 'react-on-rails' and 'react-on-rails-pro' packages are installed"` | Both packages installed as separate top-level dependencies, often due to yalc link issues | Ensure only `react-on-rails-pro` is in your `package.json`; the base package is installed automatically as a dependency. See [Duplicate Package Detection](#duplicate-package-detection) | | `ReferenceError: performance is not defined` | Node renderer VM context missing the `performance` global. Triggered by `React.lazy()` in dev mode | Enable `supportModules: true` and add `performance` via `additionalContext`. See [Node Renderer VM Context](#node-renderer-vm-context----missing-globals) | | `ReferenceError: require is not defined` | Server or RSC bundle webpack config uses `externals` for Node builtins, generating `require()` calls that fail in VM sandbox | Use `resolve.fallback: { path: false, fs: false }` instead of `externals`. See [Handling Node Builtins](#handling-node-builtins----externals-vs-resolvefallback) | | `ReferenceError: MessageChannel is not defined` | `react-dom/server.browser` instantiates `MessageChannel` at module load time; VM sandbox lacks this global | Inject a `BannerPlugin` polyfill in the server webpack config. See [MessageChannel Not Defined](#messagechannel-not-defined) | | `"global object mismatch"` | `react-on-rails` and `react-on-rails-pro` resolved from different sources (e.g., npm vs yalc) | Force consistent resolution with `pnpm.overrides` or `yarn.resolutions`. See [Version Mismatch](#version-mismatch----global-object-mismatch) | | Missing module in React Client Manifest with empty `filePathToModuleMetadata` in Rspack `bin/dev` | Rspack lazy compilation deferred RSC client references before manifest generation | Disable Rspack lazy compilation for RSC dev-server mode. See [Empty Client Manifest with Rspack Dev Server](#empty-client-manifest-with-rspack-dev-server) | | SSR hangs indefinitely / request timeout on large RSC payloads | Stream backpressure deadlock when RSC payload exceeds 16 KB | Update to latest React on Rails Pro. See [Stream Backpressure Deadlock](#stream-backpressure-deadlock) | | `"The 'react-on-rails' package version does not match the gem version"` | Gem and npm package installed at different versions | Install the npm package version matching your gem. See [Gem and npm Package Version Mismatch](#gem-and-npm-package-version-mismatch) | | `"The 'react-on-rails' package version is not an exact version"` | Using semver ranges (`^`, `~`, `*`) instead of an exact version in package.json | Pin to the exact version without range operators. See [Gem and npm Package Version Mismatch](#gem-and-npm-package-version-mismatch) | | RSC payload returns `ServerComponentFetchError: Error parsing JSON` or `SyntaxError` in development | Rails' `annotate_rendered_view_with_filenames` wraps the RSC payload JSON in `<!-- BEGIN -->` / `<!-- END -->` HTML comments | Upgrade to React on Rails Pro 16.4.0+ which renders RSC templates with `formats: [:text]`. For older versions, disable `config.action_view.annotate_rendered_view_with_filenames` for the RSC controller. | | `railsContext` causes "Functions cannot be passed directly to Client Components" | `railsContext` includes non-serializable functions (`addPostSSRHook`, `getRSCPayloadStream`) added by Pro | Destructure and exclude function properties before passing to Client Components. See [railsContext Contains Functions](#common-error-railscontext-contains-functions) | ## Environment Variable Access ### Server Components Server Components run on the server (in the node renderer). When the launcher sets `supportModules: true`, `process` is injected into the VM context, so Server Components can read environment variables via `process.env`: ```jsx // Server Component -- this file is bundled by webpack/esbuild into the server/RSC bundle, // not the launcher file. The launcher file (`node-renderer.js`) is separate and stays plain // CommonJS with `require()`. In component files, webpack/esbuild normalize CJS interop: // node-fetch v2 is a CJS module, module.exports is treated as the default import, and // node-fetch v2 exports the fetch function that way. import nodeFetch from 'node-fetch'; async function InternalDataComponent() { // Requires `supportModules: true` in the launcher config so `process` is injected // into the VM context. Without it, these reads throw `ReferenceError: process is not defined`. const serviceUrl = process.env.INTERNAL_SERVICE_URL; // Works const secret = process.env.API_SECRET; // Works if (!serviceUrl || !secret) { throw new Error('INTERNAL_SERVICE_URL and API_SECRET must be set.'); } // Use env vars with server-only data access, a bundled HTTP client, or fetch // injected via additionalContext. Avoid URLs that route back through the same // Rails app, which can create a Node renderer -> Rails -> Node renderer loop. // This example uses node-fetch v2 bundled in the server/RSC bundle. const response = await nodeFetch(serviceUrl, { headers: { Authorization: `Bearer ${secret}` }, }); if (!response.ok) throw new Error(`HTTP error fetching data: ${response.status}`); const data = await response.json(); return <pre>{JSON.stringify(data)}</pre>; } export default InternalDataComponent; ``` ### Client Components Client Components only have access to environment variables that are explicitly injected into the webpack bundle. In Shakapacker, you control this via `webpack.EnvironmentPlugin` or `webpack.DefinePlugin`: ```js // config/webpack/webpack.config.js (Shakapacker) const { generateWebpackConfig } = require('shakapacker'); const webpack = require('webpack'); const webpackConfig = generateWebpackConfig(); // Only these variables are available in Client Components webpackConfig.plugins.push(new webpack.EnvironmentPlugin(['RAILS_ENV', 'PUBLIC_API_URL'])); module.exports = webpackConfig; ``` ```jsx 'use client'; function ClientComp() { const apiUrl = process.env.PUBLIC_API_URL; // Works (injected by webpack) const secret = process.env.API_SECRET; // undefined (not injected) } ``` **Security:** Never add secret keys to webpack's `EnvironmentPlugin` -- they would be embedded in the client bundle. Use `server-only` to protect modules that access secrets. Without it, secrets could accidentally leak to the client through import chains. ## React on Rails-Specific Issues The sections above cover generic RSC pitfalls. The following issues are specific to the React on Rails stack and its node renderer architecture. ### Stream Backpressure Deadlock **Symptoms:** SSR hangs indefinitely when the RSC payload is large (> 16 KB). The page never loads and eventually times out. **Cause:** This was a bug in `react-on-rails-pro` where the internal RSC stream teeing mechanism could deadlock under backpressure with large payloads. **Fix:** Upgrade to a release that includes this patch (`react-on-rails-pro` 16.4.0.rc.3+ was the first patched line). If a newer stable release is available, prefer that and check the [CHANGELOG](https://github.com/shakacode/react_on_rails/blob/main/CHANGELOG.md) for the current recommendation. See also [PR #2444](https://github.com/shakacode/react_on_rails/pull/2444). ### Node Renderer VM Context -- Missing Globals **Symptoms:** Cryptic errors like `ReferenceError: performance is not defined`, `ReferenceError: fetch is not defined`, or `ReferenceError: require is not defined` when rendering Server Components. Often triggered by code that assumes the renderer VM inherits every global from the host Node.js process. **Root cause:** The node renderer runs uploaded bundles in isolated V8 VM contexts (`vm.createContext`). By default, each VM context only includes basic globals. Node.js-specific globals like `performance`, `Buffer`, `TextDecoder`, etc. must be explicitly added. Critically, `require()` is also not available in the VM sandbox. > **Important:** This VM global constraint applies to the **server bundle** (SSR) and to the **RSC bundle** when the node renderer executes it to generate an RSC payload. See the [Bundle Architecture Reference](../../pro/react-server-components/rendering-flow.md#bundle-architecture-reference) for a comparison. > **Migration note:** If you relied on earlier docs that said the RSC bundle runs in full Node.js, and your Server Components call `fetch()` directly (or use `Headers`, `Request`, `Response`, `AbortController`, `AbortSignal`), the renderer VM will not have those globals. Bundle an HTTP client into the RSC/server bundle or inject the fetch globals through `additionalContext`. See [Node Renderer Runtime Globals for SSR and RSC](../building-features/node-renderer/js-configuration.md#runtime-globals-for-ssr-and-rsc) for guarded startup examples. **Fix:** Enable `supportModules` in your node renderer configuration to inject common Node.js globals: ```js // renderer/node-renderer.js (or wherever you configure the renderer) module.exports = { supportModules: true, // Injects: Buffer, TextDecoder, TextEncoder, // URLSearchParams, ReadableStream, process, performance, // setTimeout, setInterval, setImmediate, // clearTimeout, clearInterval, clearImmediate, // queueMicrotask }; ``` Or set the environment variable: ```bash RENDERER_SUPPORT_MODULES=true ``` For globals not covered by `supportModules`, use `additionalContext`. For `fetch`, `Headers`, `Request`, `Response`, `AbortController`, and `AbortSignal`, see [Node Renderer JavaScript Configuration](../building-features/node-renderer/js-configuration.md#runtime-globals-for-ssr-and-rsc) for guarded startup examples that fail fast when a required global is missing. If your Node.js runtime does not provide the fetch globals, use a bundled HTTP client such as `node-fetch` v2 (CJS-compatible; v3+ is ESM-only) or `undici` from the component code, or pass a fetch implementation through `additionalContext`. For other globals, inject them directly. For example, to provide a deterministic `performance` stub for byte-stable SSR: ```js module.exports = { supportModules: true, additionalContext: { performance: { now: () => 0 }, }, }; ``` #### Handling Node Builtins -- `externals` vs `resolve.fallback` A common mistake when configuring the server bundle is using webpack `externals` to handle Node builtins like `path`, `fs`, and `stream`. This generates `require('path')` calls in the output -- but the VM sandbox has **no `require` function** by default, causing `ReferenceError: require is not defined` at runtime. > **Note:** If you have `supportModules` or `additionalContext` enabled in your renderer configuration, the renderer wraps the bundle in a module wrapper and injects `require` into the VM. In that case, `externals` will work. The guidance below applies to the default configuration without these options. **Wrong approach (causes `require is not defined`):** ```js // DON'T do this in serverWebpackConfig.js externals: { path: 'commonjs path', fs: 'commonjs fs', stream: 'commonjs stream', } ``` **Correct approach:** ```js // In serverWebpackConfig.js -- tells webpack not to polyfill these modules (imports resolve to nothing; no shim bundled) resolve: { fallback: { path: false, fs: false, stream: false, }, } ``` `resolve.fallback: false` tells webpack not to provide a polyfill for the module — the import resolves to an empty module at build time and no fallback shim is bundled. Apply the same rule to the RSC bundle when the node renderer executes it: the RSC bundle also runs in a VM context without host `require()` by default, so unresolved externals can crash at render time as well. ### MessageChannel Not Defined **Symptoms:** `ReferenceError: MessageChannel is not defined` when the server bundle loads. This typically crashes during module initialization, not during rendering. **Root cause:** `react-dom/server.browser.js` (used for SSR streaming) instantiates `MessageChannel` at **module load time** for React's internal scheduler. The VM sandbox does not provide `MessageChannel` as a global, and `supportModules` does not include it. **Fix (recommended):** Use `additionalContext` in the node renderer config to inject Node.js' native `MessageChannel` into the VM sandbox. Node.js has had a native `MessageChannel` since Node 15, and passing it through `additionalContext` gives React's scheduler correct async scheduling (macrotask delivery), which is what it depends on: ```js // In your node-renderer.js config const { MessageChannel } = require('node:worker_threads'); const config = { // ... other options additionalContext: { MessageChannel }, }; module.exports = config; // export from node-renderer.js ``` See the [node renderer JS configuration reference](../building-features/node-renderer/js-configuration.md) for where `config` is consumed. **Fallback:** If you cannot change the renderer config (e.g., a build-only setup without renderer config control), inject a minimal `MessageChannel` polyfill at the top of the server bundle using webpack's `BannerPlugin`. The polyfill only needs to support `port2.postMessage` triggering `port1.onmessage`, which is all React's scheduler requires: ```js // In serverWebpackConfig.js const webpack = require('webpack'); const messageChannelPolyfill = ` if (typeof MessageChannel === 'undefined') { globalThis.MessageChannel = class MessageChannel { constructor() { this.port1 = { onmessage: null }; this.port2 = { postMessage: (msg) => { if (this.port1.onmessage) { this.port1.onmessage({ data: msg }); } }, }; } }; } `; // Add to plugins array plugins: [ new webpack.BannerPlugin({ banner: messageChannelPolyfill, raw: true, }), // ... other plugins ]; ``` This injects the polyfill as raw JavaScript at the top of the bundle output, ensuring `MessageChannel` is defined before any module code executes. Note: this polyfill delivers messages synchronously, which works for current SSR streaming scenarios but may cause subtle rendering bugs if React yields mid-render and re-enters the scheduler. Prefer the `additionalContext` approach above whenever possible. > **When to use the `BannerPlugin` polyfill:** Use it only when the renderer config's `additionalContext` is not accessible (e.g., in a build-only setup without renderer config control). If you encounter recursive stack-overflow errors or unexpected rendering behavior with the synchronous polyfill, switch to the `additionalContext` approach. > **Note:** This usually affects the server bundle because SSR streaming loads `react-dom/server.browser`. The RSC bundle still follows the node renderer VM global rules, so inject or bundle `MessageChannel` there too if RSC code or its dependencies require it. The client bundle runs in the browser, which has native `MessageChannel`. ### Version Mismatch -- "Global Object Mismatch" **Symptoms:** Runtime error `"global object mismatch"` when both `react-on-rails` and `react-on-rails-pro` JS packages are installed. **Root cause:** The `react-on-rails` and `react-on-rails-pro` packages share internal global state. If they resolve from different sources (e.g., one from npm and one from yalc during development), each gets its own copy of the shared module, and internal checks detect the mismatch. **Fix:** Force consistent package resolution using your package manager's override mechanism: ```json // package.json (pnpm) { "pnpm": { "overrides": { "react-on-rails": "file:../path/to/local/package", "react-on-rails-pro": "file:../path/to/local/pro-package" } } } ``` ```json // package.json (yarn) { "resolutions": { "react-on-rails": "file:../path/to/local/package" } } ``` When using **yalc** for local development: 1. Publish all packages in dependency order: base package first, then pro 2. Ensure both packages resolve to the same version source 3. Run `yalc installations show` to verify no stale installations exist ### Duplicate Package Detection **Symptoms:** Boot-time error: `"Both 'react-on-rails' and 'react-on-rails-pro' packages are installed."` This prevents the Rails application from starting. **Root cause:** The `react_on_rails` gem validates that only one of the JavaScript packages is installed. During development with yalc, both packages may appear in `node_modules` simultaneously if the yalc link chain isn't set up correctly. **Fix:** 1. **Verify your package setup:** `react-on-rails-pro` includes `react-on-rails` as a direct dependency. You should only have `react-on-rails-pro` in your `package.json` -- the base package is automatically installed through the dependency chain. 2. **Check for stale yalc links:** ```bash # Remove stale yalc installations yalc installations clean # Re-publish and re-add in the correct order cd /path/to/react-on-rails && yalc publish cd /path/to/react-on-rails-pro && yalc publish cd /path/to/your-app && yalc add react-on-rails-pro ``` 3. **Inspect `node_modules`:** Confirm that `node_modules/react-on-rails` is a symlink pointing into `react-on-rails-pro`'s dependency tree, not a separate top-level installation. ### Gem and npm Package Version Mismatch React on Rails requires the gem and npm package versions to match exactly. The validation runs at Rails boot time and will prevent the application from starting if versions are mismatched or improperly specified. **Symptom 1 -- Version mismatch:** ```text **ERROR** ReactOnRails: The 'react-on-rails' package version does not match the gem version. Package: 16.3.0 Gem: 16.4.0 ``` This happens when you upgrade the gem (e.g., `bundle update react_on_rails`) without upgrading the npm package, or vice versa. Both must be the same version. **Fix:** Install the npm package version that matches your gem. Replace `VERSION` with the version shown in the error message (e.g., the `Gem:` line): ```bash # Check your gem version bundle show react_on_rails # Install the matching npm package (use your package manager) yarn add react-on-rails@VERSION --exact # or pnpm add react-on-rails@VERSION --save-exact # or npm install react-on-rails@VERSION --save-exact ``` **Symptom 2 -- Non-exact version:** ```text **ERROR** ReactOnRails: The 'react-on-rails' package version is not an exact version. Detected: ^16.4.0 Gem: 16.4.0 ``` React on Rails does not allow semver ranges (`^`, `~`, `>`, `<`, `*`) or special tags (`latest`, `next`, `beta`) in `package.json`. The version must be an exact match. **Fix:** Remove the range operator and pin to the exact version shown in the `Gem:` line: ```json { "dependencies": { "react-on-rails": "VERSION" } } ``` **Symptom 3 -- Pro gem with base package:** ```text **ERROR** ReactOnRails: You have the Pro gem installed but are using the base 'react-on-rails' package. ``` If you have the `react_on_rails_pro` gem in your Gemfile, you must use the `react-on-rails-pro` npm package, not `react-on-rails`. **Fix:** Replace the base package with the Pro package. Replace `VERSION` with the gem version from the `Gem:` line in the error message: ```bash yarn remove react-on-rails && yarn add react-on-rails-pro@VERSION --exact ``` **Symptom 4 -- Pro package without Pro gem:** ```text **ERROR** ReactOnRails: You have the 'react-on-rails-pro' package installed but the Pro gem is not installed. ``` The `react-on-rails-pro` npm package requires the `react_on_rails_pro` gem. **Fix:** Either add the Pro gem to your Gemfile (`gem 'react_on_rails_pro'`) and run `bundle install`, or switch to the base npm package if you don't have a Pro license. > **Tip:** Set `REACT_ON_RAILS_SKIP_VALIDATION=true` to temporarily bypass version validation during setup or generator runs. ## When NOT to Use Server Components Server Components are not always the right choice: - **Highly interactive interfaces:** Dashboards, design tools, real-time collaboration - **Offline-first applications:** Systems designed around local persistence - **Rapid iteration teams:** The architectural constraints may slow development velocity during early prototyping For these cases, keep components as Client Components and adopt Server Components selectively for data-heavy, display-oriented sections. ## Next Steps - [Component Tree Restructuring Patterns](rsc-component-patterns.md) -- how to restructure your component tree - [Context, Providers, and State Management](rsc-context-and-state.md) -- how to handle Context and global state - [Data Fetching Migration](rsc-data-fetching.md) -- migrating from useEffect to server-side fetching - [HTTP Response Ownership](rsc-http-response-patterns.md) -- status codes, redirects, and cache headers - [Third-Party Library Compatibility](rsc-third-party-libs.md) -- dealing with incompatible libraries ================================================================================ PAGE: https://reactonrails.com/docs/migrating/rsc-flight-payload SOURCE: docs/oss/migrating/rsc-flight-payload.md ================================================================================ # RSC Migration: Flight Payload Optimization This guide covers a critical and counterintuitive RSC performance nuance: not all non-interactive, stateless components should be Server Components. When presentational components produce element trees much larger than their data props, moving them to Client Components can dramatically reduce page weight. > **Part 8 of the [RSC Migration Series](migrating-to-rsc.md)** | Previous: > [Troubleshooting and Common Pitfalls](rsc-troubleshooting.md) | Next: > [RSC Performance Validation Playbook](rsc-performance-validation.md) ## What's in the Flight Payload When a Server Component renders, React serializes its output into the **RSC Flight payload** -- a JSON-like stream embedded in `<script>` tags alongside the server-rendered HTML. This payload tells React on the client how to reconcile the component tree without re-rendering from scratch. Every server-rendered element becomes a JSON array in the payload: ```json ["$","div",null,{"className":"flex items-center justify-between px-4 py-2 bg-white shadow-sm rounded-lg","children":[...]}] ``` In contrast, when a Client Component is referenced from a Server Component, the payload contains only a lightweight **client reference** (module ID + chunk metadata) plus the serialized props. The browser renders the element tree locally from the JavaScript bundle it already has. ## Why "All Display-Only = Server" Is an Oversimplification The standard RSC guidance says: "If a component doesn't use hooks, event handlers, or browser APIs, make it a Server Component." This is a good default, but it ignores the **expansion ratio** between data props and rendered element trees. Consider a `StarRating` component: ```jsx // StarRating as a Server Component // Data: { rating: 4.5, count: 128 } — ~30 bytes // Flight payload per instance: ~498 bytes of nested divs, ★ characters, and className strings export default function StarRating({ rating, count }) { const fullStars = Math.floor(rating); const hasHalf = rating % 1 >= 0.5; return ( <div className="flex items-center gap-1"> {Array.from({ length: 5 }, (_, i) => ( <span key={i} className={`text-lg ${i < fullStars ? 'text-yellow-400' : i === fullStars && hasHalf ? 'text-yellow-300' : 'text-gray-300'}`} > ★ </span> ))} <span className="ml-2 text-sm text-gray-600">({count})</span> </div> ); } ``` As a Server Component, the Flight payload contains the **entire expanded element tree** -- every `<span>`, every className string, every `★` character. The 30 bytes of data (`rating` + `count`) expands to ~498 bytes in the payload. That's a 16:1 expansion ratio. As a Client Component, the payload contains only the client reference plus serialized props -- a fraction of the expanded element tree. The browser renders the element tree from the JS bundle. ## The Counterintuitive Pattern: Presentational Client Components Sometimes the right move is to make a purely presentational component a Client Component. This is counterintuitive because the component doesn't use hooks, state, or event handlers -- the usual reasons for `'use client'`. ### When to Apply This Pattern A component is a candidate for this optimization when these signals line up: 1. **High per-instance expansion** -- the rendered element tree is several times larger than the data props 2. **Repeated many times on the page** -- the component renders per-item in a list (e.g., product cards, review snippets, tag lists) 3. **Heavy className density** -- the component has many utility CSS classes (especially Tailwind) that inflate the element tree 4. **Bundle scope is narrow** -- the component is not part of a shared client bundle loaded on many pages where it never renders Treat ratio and repetition count together. A 3:1 component rendered 60 times can be a better target than a 10:1 component rendered once. ### Real-World Example This was demonstrated on a product search page rendering 36 products, each with reviews, features, tags, and star ratings. Four purely presentational subtrees were moved from server to client components: | Component | Server element tree per card | Client props per card | Savings ratio | | ------------------ | ----------------------------------------- | -------------------------------- | ------------- | | **StarRating** | ~498 B (nested divs, ★ chars, classNames) | ~30 B (2 numbers: rating, count) | 16:1 | | **ReviewSnippets** | ~934 B per snippet | ~100 B (ReviewSnippet data) | 9:1 | | **FeaturesList** | ~190 B per feature item | ~30 B (string) | 6:1 | | **ProductTags** | ~155 B per tag | ~10 B (string) | 15:1 | These before/after numbers came from the same page in one benchmark environment. The large TTFB gain here is most representative of buffered or non-streaming SSR, where the server finishes more work before sending bytes. Streaming deployments may see smaller or different TTFB changes, and results will also vary under different server load, caching, or multi-region production setups. Results: | Metric | Before | After | Change | | ---------------------- | --------- | ------------------------- | ------------------------------ | | **Raw Flight payload** | 158,267 B | 91,244 B | **-42.3%** | | **Total HTML** | 370,461 B | 273,901 B | **-26.1%** | | **Client JS increase** | -- | +2,152 B (+471 B gzipped) | minimal | | **TTFB** | 808 ms | 245 ms | -70% | | **FCP** | 982 ms | 350 ms | -64% | | **LCP** | 982 ms | 1,058 ms | +8% (tradeoff: more hydration) | The **2.2 KB client JS increase** produced a **67 KB Flight payload reduction** -- a 31:1 ratio. In this benchmark, the TTFB improvement came primarily from the server serializing far less Flight data before it could emit the first byte. The wire-size reduction alone would not normally explain the full change. The savings were dominated by className strings. In the Tailwind-heavy benchmark, the Flight payload broke down as: | Category | Approximate share | Description | | --------------------- | ----------------- | --------------------------------------------------------------------- | | **className strings** | ~48% | CSS class lists, especially verbose with utility-first CSS (Tailwind) | | **Structural JSON** | ~25% | The `["$","div",null,{...}]` wrappers around every element | | **Content data** | ~27% | Actual text, numbers, and data values | [Diagram: Diagram showing what makes up the RSC Flight payload: className strings (~48%), structural JSON (~25%), and content data (~27%). Includes expansion ratio benchmarks for real components like StarRating (16:1) and ReviewSnippets (9.3:1).] ### How to Apply It **Step 1:** Identify presentational subtrees with high expansion ratios. **Step 2:** Add `'use client'` to those components. The directive must appear at the top of the file, before any `import` statements. It tells React to send a client reference instead of the expanded element tree. Before adding `'use client'`, confirm the component and its import tree are free of server-only dependencies (`server-only`, direct DB queries, API-key-bearing helpers, async props, etc.). If any exist, move that work into a parent Server Component and pass the results down as props first. After the change, inspect the resulting client bundle or import tree as well. Any direct or transitive import under that file now becomes client code, so server-only helpers must be pulled out before you keep the directive. Note: Client Components cannot be `async` functions. If the component you want to convert is currently loading its own data with `async`/`await`, move that fetch into a parent Server Component first and pass the data down as props before adding `'use client'`. ```jsx // Before: Server Component — entire element tree in Flight payload // (No 'use client' directive — React renders this on the server.) export default function ProductTags({ tags }) { return ( <div className="flex flex-wrap gap-2 mt-3"> {tags.map((tag) => ( <span key={tag} className="inline-flex items-center px-2.5 py-0.5 rounded-full text-xs font-medium bg-blue-100 text-blue-800" > {tag} </span> ))} </div> ); } ``` ```jsx // After: Client Component — only tags array in Flight payload 'use client'; export default function ProductTags({ tags }) { return ( <div className="flex flex-wrap gap-2 mt-3"> {tags.map((tag) => ( <span key={tag} className="inline-flex items-center px-2.5 py-0.5 rounded-full text-xs font-medium bg-blue-100 text-blue-800" > {tag} </span> ))} </div> ); } ``` The code is identical except for the `'use client'` directive. The component still receives the same props and renders the same output. The difference is where the rendering happens and what the Flight payload contains. **Step 3:** Verify the savings by measuring the payload (see next section). ## How to Measure Your Flight Payload The Flight payload is embedded in `<script>` tags in the HTML response. To extract and measure it: ### Browser DevTools 1. Open **Network** tab, load the page, find the document request 2. View the response and search for `<script>` tags containing RSC data 3. The payload is the JSON-like content between the script tags ### Programmatic Extraction ```js // In browser console: extract RSC payload size // Heuristic only: inspect your rendered RSC script tags first and adjust the filter if needed. // If your framework exposes explicit RSC markers/attributes, prefer those over content matching. const scripts = document.querySelectorAll('script'); let rscPayloadSize = 0; scripts.forEach((script) => { // Heuristic: Flight records usually contain element tuples like ["$","div",...] if (script.textContent && /\["\$","[a-zA-Z]/.test(script.textContent)) { rscPayloadSize += new Blob([script.textContent]).size; } }); console.log(`RSC payload: ${(rscPayloadSize / 1024).toFixed(1)} KB`); ``` This is still an approximation. Validate the marker pattern against how your app emits Flight chunks. For React on Rails specifically, inspect the actual `<script>` payload format in your rendered HTML before relying on this heuristic, and adapt the filter condition if your app uses a different wrapper format (a `0` result may mean the regex missed your format, not that RSC is disabled). ### Analyzing Payload Composition To understand what's taking up space in your payload, parse the Flight data and categorize the content: ```js // Rough breakdown of payload composition const payload = Array.from(document.querySelectorAll('script')) .map((script) => script.textContent || '') .filter((text) => /\["\$","[a-zA-Z]/.test(text)) .join(''); const classNameMatches = payload.match(/"className":"[^"]*"/g) || []; const classNameBytes = classNameMatches.reduce((sum, m) => sum + new Blob([m]).size, 0); const totalBytes = new Blob([payload]).size; console.log(`className share: ${((classNameBytes / totalBytes) * 100).toFixed(1)}%`); ``` If className strings account for a large share of your payload, that is a strong signal to investigate this optimization. Even 30%+ can be worth examining on larger pages. ## Compression Effectiveness Modern HTTP compression (gzip, Brotli) partially offsets the bloated payload because repetitive className strings compress well. However, raw payload size still matters for: - **Parse time** -- the browser must parse the full decompressed payload before React can reconcile the tree - **Memory usage** -- the decompressed payload is held in memory during reconciliation - **Server generation time** -- serializing larger element trees takes more CPU time on the server In the benchmark above, the payload reduction was significant even after compression because the savings came from eliminating entire subtrees, not just deduplicating strings. ## The LCP Tradeoff Moving presentational components to the client increases the amount of JavaScript the browser must download and execute before those components fully hydrate. This can slightly increase Largest Contentful Paint (LCP): - **TTFB and FCP improve** because the server generates and streams a smaller payload faster - **LCP may increase** because the converted components now require their JavaScript bundle to be parsed and executed before hydration completes, which can slightly delay when React considers those subtrees ready. This is most noticeable when the LCP element itself sits inside a converted component. In the benchmark, LCP increased by 8% (982 ms to 1,058 ms) -- a minor regression offset by the 64% FCP improvement and 42% payload reduction. **Recommendation:** Always benchmark before and after. The tradeoff is favorable when: - The payload reduction is large (> 20%) - The client JS increase is small (< 5 KB gzipped) - The page has many repeated components (lists, grids, cards) If LCP is your critical metric (e.g., for a landing page with a hero image), be more conservative about moving components to the client. ## React on Rails: Double JSON.stringify (Resolved) React on Rails previously double-encoded the RSC payload when embedding it in inline `<script>` tags — the Flight payload (already a serialized wire format) was JSON-encoded again, adding ~24% overhead. This was fixed in [issue #2522](https://github.com/shakacode/react_on_rails/issues/2522) with the length-prefixed streaming protocol, which sends HTML content as raw bytes with a length prefix instead of re-encoding it as JSON. The Flight payload optimization patterns in this guide (expansion ratios, presentational client components) remain important regardless — they address the inherent size of the serialized element tree, not the encoding overhead. ## Decision Flowchart Use this flowchart when deciding whether a presentational component should be a Server or Client Component: [Diagram: Static flowchart guiding developers through the decision of whether a component should be a Server Component or Client Component, based on interactivity, server-only resources, repetition ratio, expansion ratio, and bundle cost.] ## Summary The standard RSC advice -- "make everything a Server Component unless it needs interactivity" -- is a good starting point but not the full picture. For presentational components with high expansion ratios that render many times on a page, moving them to Client Components can dramatically reduce the Flight payload with minimal JS cost. Always measure to confirm the tradeoff is favorable for your specific page. ## Related Articles - [Component Tree Restructuring Patterns](rsc-component-patterns.md) -- the foundational patterns for splitting server and client components - [Troubleshooting and Common Pitfalls](rsc-troubleshooting.md) -- debugging payload duplication and other RSC issues - [Data Fetching Migration](rsc-data-fetching.md) -- migrating data-fetching patterns to Server Components ================================================================================ PAGE: https://reactonrails.com/docs/migrating/rsc-performance-validation SOURCE: docs/oss/migrating/rsc-performance-validation.md ================================================================================ # RSC Performance Validation Playbook Use this playbook when an RSC migration is intended to improve page performance. It defines the evidence package reviewers need before treating an RSC conversion as a performance win. > **Part 9 of the [RSC Migration Series](migrating-to-rsc.md)** | Previous: > [Flight Payload Optimization](rsc-flight-payload.md) | Next: > [Mostly Static RSC Shell With a Tiny Sidecar](rsc-static-shell-sidecar.md) ## Start With a Local Control and Experiment The cleanest merge signal is usually a local A/B comparison: - **Control:** current `origin/main`, or the explicit baseline branch the app already uses in production. - **Experiment:** the PR branch or candidate branch. - **Machine:** same developer machine, same browser version, same CPU/network throttling, same sample order. - **Builds:** comparable production-like builds. Do not compare a development server with compiled production assets. - **Environment:** same data snapshot, Rails cache state, browser cache policy, image/CDN setup, asset host, feature flags, secrets, and locale/device assumptions. - **Smoke test first:** open every control and experiment URL before measuring. Confirm the page returns the expected status, real images and fonts load, and required user-visible content is present. Review-app, staging, production PageSpeed, and production Lighthouse runs are useful context, but they are not automatically a clean A/B. CDN, hosting, cache warmth, data, image signatures, and deploy topology can differ enough to explain the result. ## Compare Against the Real Incumbent Path RSC should be compared against the path users actually have today. If the existing page uses [`cached_react_component` or `cached_react_component_hash`](../building-features/caching.md#level-2-fragment-caching) with React on Rails Pro prerender caching, include a warm cached SSR baseline. A static page that is already served from a warm SSR fragment cache can be very hard to beat on TTFB, FCP, or LCP, even when RSC reduces hydration work and JavaScript bytes. Use the matrix in [Benchmarking RSC Against Warm SSR Caches](../core-concepts/performance-benchmarks.md#benchmarking-rsc-against-warm-ssr-caches) to label cold uncached SSR, warm cached SSR, RSC cold, and RSC warm runs. The public tracker for that tradeoff is [#4294](https://github.com/shakacode/react_on_rails/issues/4294). ## Pair Visual Regression With Performance Performance evidence is incomplete without visual evidence. A page is not faster in a useful sense if it is missing visible UI, fonts, images, layout wrappers, search bars, or mobile navigation behavior. For every changed page and viewport: - Run visual checks in the same validation loop as performance checks. - Report diff pixels and diff percent, not only "looks fine". - Block unaccepted visual changes. Treat them as regressions unless the UI change was explicitly reviewed and accepted. - Confirm screenshots include real page assets before using them as evidence. - Recheck keyboard, focus, and responsive states when the migration changes hydration or global JavaScript loading. This also protects performance interpretation. A lower Total Blocking Time can be real while LCP gets worse because CSS, fonts, or the LCP image moved later in the critical path. ## Keep the Package Stack Stable Final merge evidence should use installable packages: - Published packages, canary packages, or release-candidate packages are valid final evidence. - Framework `main` source checkouts and local package tarballs are diagnostic only unless the tested package has been published and remeasured. - If a local tarball is useful during diagnosis, record its package name, version, source commit, and shasum. - If a main-tip diagnostic improves performance, publish or use a canary/RC and rerun visual plus performance before depending on it. - If a diagnostic stack improves performance but fails visual parity, it is not a ship candidate. Keep one variable per run. Do not combine an app conversion, package bump, framework SHA, bundler configuration change, and static-shell sidecar rewrite in one measurement if the result needs to guide implementation. ## Archive and Parse Benchmark Output Each run should leave durable artifacts. Name archives so a future reader can identify the stack, baseline, candidate, date, pages, and viewport set without opening the report. Record: - Archive path or published artifact URL. - Tool version and configuration. - Control and experiment URLs. - Control and experiment SHAs. - Package versions and package SHAs or shasums where relevant. - Pages and viewports tested. - Environment caveats, especially local-vs-production differences. Parse JSON or equivalent machine-readable artifacts. Do not rely on terminal scrollback or a single summary screenshot. For ShakaPerf runs based on the HiChee lesson: - Run visual plus performance for every changed page and viewport. - Use Lighthouse `throttlingMethod: 'devtools'` for this workflow. - Prefer sequential sampling on one developer machine unless the benchmark setup was designed for parallel execution. - Save both the full report and the self-contained report when available. The methodology matters more than the tool. ShakaPerf is the known ShakaCode workflow; equivalent tooling is fine when it produces the same control/experiment, visual, performance, and archived evidence. ## Metrics Checklist Include this checklist in the PR description or benchmark comment: | Evidence | Required detail | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------- | | URLs | Control URL and experiment URL | | SHAs | Control SHA and experiment SHA | | Package stack | React on Rails, React on Rails Pro, `react-on-rails`, `react-on-rails-pro`, `react-on-rails-rsc`, and tarball shasums when used | | Pages/viewports | Every changed page and desktop/mobile viewport that matters | | Visual diff | Diff pixels and percent for each page/viewport | | Lighthouse score | Score for control and experiment, plus win/regression/no material change | | FCP | Control, experiment, delta, verdict | | Speed Index | Control, experiment, delta, verdict | | LCP | Control, experiment, delta, verdict | | TBT | Control, experiment, delta, verdict | | Total downloads | Control, experiment, delta, verdict | | JavaScript bytes | Control, experiment, delta, verdict | | Caveats | Local-vs-production, cache, CDN, image, data, throttling, sample-size, or visual caveats | Use honest verdicts. It is valid for an RSC migration to be a win on TBT and JavaScript bytes, a regression on LCP, and still worth pursuing for maintainability or future optimization. Say that plainly. ## HiChee Case Study A HiChee public-page conversion moved the home and FAQ pages to mostly static RSC output. Earlier attempts produced misleading signals because they mixed package stacks, incomplete visual evidence, missing asset setup, and hosted PageSpeed context that was not a clean local A/B. The final merge confidence came from a local master-vs-PR ShakaPerf run on the same machine. It tested home and FAQ in desktop and mobile viewports, paired visual regression with performance, used the published package stack, and treated review-app or production PageSpeed as context rather than the canonical merge signal. The published-stack run had clean visual diffs, materially lower JavaScript and download bytes, and large mobile Lighthouse gains on the changed pages. A separate diagnostic run against local framework main-tip packages was rejected because it failed visual parity, even though some performance numbers looked better. The key lesson is not "RSC always wins." The lesson is that RSC performance work needs a disciplined evidence package: same-machine control/experiment, stable package stack, one variable per run, archived parsed output, and visual parity as a merge gate. ## Follow-Up Diagnostics and Related Work When the evidence points to unexpected RSC cost, use the existing troubleshooting guides before changing architecture: - [RSC render asset/cache diagnostics](https://github.com/shakacode/react_on_rails/issues/4296) tracks framework support for showing cache hit/miss state, emitted assets, client references, and payload size during benchmark runs. - [RSC Client Reference Diagnostics](../../pro/react-server-components/client-reference-diagnostics.md) shows how to derive a local report for client-reference chunks and asset byte totals from the emitted client manifest. - [Chunk contamination](rsc-troubleshooting.md#chunk-contamination) explains large unexpected chunks from shared `'use client'` modules. - [Client Reference Scope and Empty `clientReferences`](rsc-troubleshooting.md#client-reference-scope-and-empty-clientreferences) explains why globally emptying `clientReferences` is not a safe general optimization. - [#4111](https://github.com/shakacode/react_on_rails/issues/4111) tracks the RSC CSS and cross-page chunk bloat warning work. - [react_on_rails_rsc#134](https://github.com/shakacode/react_on_rails_rsc/issues/134) tracks route-scoped client-reference manifests. - [react_on_rails_rsc#145](https://github.com/shakacode/react_on_rails_rsc/issues/145) tracks tiny sidecar entries for mostly static RSC pages. - [#4298](https://github.com/shakacode/react_on_rails/issues/4298) tracks the repo-local agent skill that operationalizes this workflow. For mostly static pages that still need a few browser behaviors, continue with [Mostly Static RSC Shell With a Tiny Sidecar](rsc-static-shell-sidecar.md). ================================================================================ PAGE: https://reactonrails.com/docs/migrating/rsc-static-shell-sidecar SOURCE: docs/oss/migrating/rsc-static-shell-sidecar.md ================================================================================ # Mostly Static RSC Shell With a Tiny Sidecar Use this pattern when a public page can render almost all useful content as static RSC HTML but still needs a few browser behaviors. The goal is to keep the static shell and CSS on the critical path while loading only a small, explicit browser entry for progressive enhancement. > **Part 10 of the [RSC Migration Series](migrating-to-rsc.md)** | Previous: > [RSC Performance Validation Playbook](rsc-performance-validation.md) ## When to Use This Pattern Use a mostly static shell plus tiny sidecar when: - The page is public, SEO-sensitive, or mostly static. - The initial UI can render without browser state. - The normal global application pack is much larger than the required behavior. - The page needs a small amount of progressive enhancement, such as search, auth, currency, analytics, newsletter signup, or URL-driven effects. - Visual parity with the old page is required. Do not use it when: - The page is mostly an authenticated application surface. - The page needs many eager client islands. - The global app pack is already tiny. - Route-level behavior depends on global JavaScript that the team has not audited. - The team is trying to hide a broad RSC client-reference problem by disabling discovery globally. ## Architecture Sketch ```text Rails view |-- renders static RSC component output |-- appends explicit static shell CSS |-- opts out of selected global JavaScript packs |-- emits inert JSON props/context for the sidecar `-- appends a tiny sidecar JavaScript entry StaticPublicPage `-- renders layout, chrome, and page content without browser-only hooks public-page-effects sidecar |-- parses JSON props/context |-- handles URL-driven effects immediately when needed |-- listens for user intent on static placeholders `-- lazy-imports React/client islands only on demand ``` The names above are placeholders. In an app, use page-specific names such as `StaticPublicPage`, `PublicPageEffects`, or `public-page-effects` rather than copying names from another product. ## Rails Layout Pack Opt-Out Until a first-class helper exists, use an explicit Rails layout convention. Keep global CSS and layout markup intact; skip only the selected JavaScript pack on pages that opt in. The broader Pro layout pattern is documented in [Page-Level Global JavaScript Opt-Out for Static Shells](../../pro/react-server-components/static-shell-global-js-opt-out.md), and the public follow-up is [#4297](https://github.com/shakacode/react_on_rails/issues/4297). ```erb <%# app/views/layouts/application.html.erb %> <% unless content_for?(:skip_global_javascript) %> <% append_javascript_pack_tag "global" %> <% end %> <%= javascript_pack_tag defer: true %> ``` ```erb <%# app/views/public/home.html.erb %> <% content_for :skip_global_javascript, "true" %> <% append_javascript_pack_tag "public-page-effects" %> ``` Keep the contract narrow: - Skip only the JavaScript pack you intend to replace. - Keep global CSS, layout CSS, fonts, and RSC/page-specific styles if the static HTML depends on them. - Make the opt-out page-scoped and visible in the view. - List behavior normally initialized by the skipped pack and either replace it, move it to a smaller sidecar, or consciously drop it. ## Props and Context Handoff Avoid mounting a full React on Rails client component just to pass props to the sidecar. Emit inert JSON and let the sidecar parse it. ```erb <script type="application/json" id="public-page-effects-props"> <%= raw json_escape(props.to_json) %> </script> ``` The sidecar can also read a small Rails context script when it needs CSRF, locale, currency, or feature flags. Keep the payload serializable and page-specific. ```js function readJsonScript(id) { const element = document.getElementById(id); if (!element?.textContent) return {}; return JSON.parse(element.textContent); } const props = readJsonScript('public-page-effects-props'); const context = readJsonScript('public-page-effects-context'); ``` Sidecar rules: - Parse inert JSON scripts; do not depend on a hidden React mount for data transport. - Create a small root only when a real client island is needed. - Lazy import React and `react-dom/client` only when user intent or URL state requires it. - Fail safely when optional target elements are absent. - Keep sidecar behavior independent from RSC client-reference hydration. ## Intent Hydration Render a static placeholder or fallback UI in the RSC HTML. Attach lightweight listeners to it from the sidecar. On first user intent, lazy import the real client island, mount it, and replay the intent. ```js const searchTarget = document.querySelector('[data-public-search]'); const props = readJsonScript('public-page-effects-props'); let hydrating = false; async function hydrateSearch(firstEvent) { const [{ default: SearchIsland }, { createRoot }, React] = await Promise.all([ import('./SearchIsland'), import('react-dom/client'), import('react'), ]); const root = createRoot(searchTarget); root.render(React.createElement(SearchIsland, { props, firstEventType: firstEvent.type })); } async function onIntent(event) { if (hydrating) return; hydrating = true; try { await hydrateSearch(event); searchTarget.removeEventListener('click', onIntent); searchTarget.removeEventListener('focusin', onIntent); searchTarget.removeEventListener('keydown', onKeydown); } catch (error) { console.error('Failed to load search island', error); } finally { hydrating = false; } } function onKeydown(event) { if (event.key !== 'Enter' && event.key !== ' ') return; event.preventDefault(); onIntent(event); } if (searchTarget) { searchTarget.addEventListener('click', onIntent); searchTarget.addEventListener('focusin', onIntent); searchTarget.addEventListener('keydown', onKeydown); } ``` Keep accessibility and fallback behavior explicit: - Support keyboard activation, not only pointer clicks. - Make intent targets keyboard-focusable before hydration: use a real `button`/`a`, or add `tabindex="0"` and an appropriate `role` to a non-interactive placeholder. - Preserve focus order and visible focus styles before and after hydration. - Provide a no-JS or slow-JS fallback for required flows, such as a normal form action or link. - Replay the first intent so the user does not need to click or type twice. - Smoke-test URL-driven effects that must run without waiting for a click, such as auth or query-param flows. ## CSS Parity A static RSC shell cannot rely on a skipped JavaScript pack to incidentally import required styles. Make CSS delivery explicit: - Keep layout/global styles loaded when the static HTML depends on them. - Add a static shell stylesheet entry for page chrome that moved out of the old client graph. - Add page-specific CSS entries for page-only styles. - Keep existing preload or modulepreload behavior when it is part of the old page's critical path. - Compare before/after screenshots for fonts, icons, spacing, layout wrappers, hover/focus states, mobile navigation, and responsive breakpoints. - Avoid hidden dependencies where a JavaScript pack imports SCSS needed by static HTML. If the RSC page downloads unexpected CSS or JS through client references, check [Chunk Contamination](rsc-troubleshooting.md#chunk-contamination) and [RSC Stylesheet Injection](rsc-troubleshooting.md#rsc-stylesheet-injection-render-blocking-links-and-cascade-order). Use [RSC Client Reference Diagnostics](../../pro/react-server-components/client-reference-diagnostics.md) when you need a local asset report for the exact client-reference chunks emitted by the RSC plugin. ## Bundler and Client-Reference Caveats A tiny sidecar is ordinary browser JavaScript. It is not an RSC Client Component and it is not an RSC client reference. Sidecar success does not prove RSC client islands will hydrate. Do not use this pattern as a reason to globally disable RSC client-reference discovery: - Do not set `clientReferences = []` as a general app optimization. - Do not change normal RSC vendor or client-reference chunking unless the change is isolated and tested. - If a sidecar is kept out of a monolithic vendor split, verify that RSC client-reference hydration still works on a route that has a real Client Component. - Prefer app-source-scoped discovery until route-scoped client-reference manifests exist. See [Client Reference Scope and Empty `clientReferences`](rsc-troubleshooting.md#client-reference-scope-and-empty-clientreferences), [react_on_rails_rsc#134](https://github.com/shakacode/react_on_rails_rsc/issues/134), and [react_on_rails_rsc#145](https://github.com/shakacode/react_on_rails_rsc/issues/145). ## Behavior Audit Before Skipping Global JavaScript Audit the selected global pack before opting a page out: - Auth, sign-in modal, sign-up modal, account menu, and session-expiration behavior. - Magic-link, campaign, referral, flash, or query-param flows. - CSRF/session-dependent fetches or forms. - Analytics, consent management, error tracking, and web-vitals reporting. - Currency, locale, theme, or user-preference state. - Navbar, menu, search, footer, and mobile layout interactions. - Third-party widgets and embeds. - Event handlers installed by the global pack on layout elements. - CSS imported only by the global pack. Move required behavior into the sidecar or a smaller layout-owned script. Do not assume skipped global JavaScript is harmless just because the page still renders. ## Verification Checklist For each static shell page: - Smoke-test control and experiment URLs before measuring. - Confirm the global JavaScript pack is absent only on opted-out pages. - Confirm global CSS, static shell CSS, page CSS, fonts, and critical images still load. - Run visual regression for every changed page and viewport. - Compare total downloads and JavaScript bytes against the control. - Run the [RSC Performance Validation Playbook](rsc-performance-validation.md) when the PR claims a performance win. - Inspect [RSC Client Reference Diagnostics](../../pro/react-server-components/client-reference-diagnostics.md) when client-reference chunks look larger than expected. - Exercise every sidecar-triggered flow, including URL-driven flows. - Check keyboard activation, focus management, and no-JS or slow-JS fallback behavior. - Add targeted system or E2E specs for behavior moved out of the global pack. - Test at least one RSC route with a real Client Component if `clientReferences` was narrowed. Related work: [#4295](https://github.com/shakacode/react_on_rails/issues/4295) tracks cached RSC output for static public pages, [#4297](https://github.com/shakacode/react_on_rails/issues/4297) tracks the page-level global JavaScript opt-out, and [#4299](https://github.com/shakacode/react_on_rails/issues/4299) tracks the performance validation playbook behind this guide. ================================================================================ PAGE: https://reactonrails.com/docs/getting-started/comparison-with-alternatives SOURCE: docs/oss/getting-started/comparison-with-alternatives.md ================================================================================ # Comparison with Alternatives Choosing a React integration strategy for Rails? This guide compares React on Rails (OSS and Pro) with the main alternatives so you can make an informed decision. ## Feature Comparison | Option | Keep Rails as the main app? | Incremental React inside Rails views? | Full-page React app model? | Built-in SSR path | RSC / streaming path | Operational model | Best when | | ------------------------- | --------------------------- | ------------------------------------- | -------------------------- | --------------------------------- | ----------------------- | ---------------------------------------------------- | -------------------------------------------------------------------------- | | **React on Rails** | Yes | Excellent | Good | Yes, via ExecJS | Pro upgrade path | One Rails app | You want the strongest React + Rails integration with a clear upgrade path | | **React on Rails Pro** | Yes | Excellent | Good | Yes, via a dedicated Node process | Yes | Same Rails app plus a Node SSR process | You want higher-performance SSR, streaming, RSC, or advanced SSR features | | **Inertia Rails + React** | Yes | Limited | Excellent | Optional | No first-class RSC path | One Rails app with SPA-style pages | You want React pages with Rails controllers and no separate API | | **Vite Ruby + React** | Yes | DIY | DIY | Experimental / DIY | No first-class RSC path | One Rails app with custom integration decisions | You want maximum flexibility and minimal framework conventions | | **react-rails** | Yes | Good | Limited | Yes, via ExecJS | No | One Rails app | You want a simpler, older integration and do not need newer React features | | **Next.js + Rails API** | Usually no | Poor | Excellent | Yes | Excellent | Separate frontend/backend boundary in most real apps | You want a React-first architecture and are willing to split concerns | | **Hotwire / Turbo** | Yes | N/A | N/A | HTML-over-the-wire | N/A | One Rails app | You want minimal JavaScript and the most Rails-native path | ## Recommended Default If you want React inside a Rails app, start with React on Rails. It is the best default when you want to keep Rails as the main application while still getting React components, Rails view helpers, props hydration, and an upgrade path to more advanced rendering later. Upgrade to React on Rails Pro when you want Node-based SSR, streaming SSR, React Server Components, higher-performance rendering, or advanced SSR tooling. See [OSS vs Pro](./oss-vs-pro.md) for the detailed feature matrix. ## Overview of Each Option ### react-rails [react-rails](https://github.com/reactjs/react-rails) was one of the first gems to integrate React with Rails. It provides a `react_component` view helper and basic ExecJS-based server rendering. The project is now in maintenance mode and maintained by [ShakaCode](https://www.shakacode.com/), with active feature development focused on React on Rails. It lacks support for modern React features like streaming SSR, code splitting, or React Server Components. Switching from react-rails to React on Rails is straightforward since both use a `react_component` view helper with a compatible API. See the [migration guide](../migrating/migrating-from-react-rails.md) for details. **Best for:** Legacy projects already using react-rails that don't need advanced rendering features. ### Inertia.js [Inertia.js](https://inertiajs.com/) replaces Rails views entirely with a single-page app architecture while keeping server-side routing. Controllers return Inertia responses instead of HTML, and the client-side adapter renders React (or Vue/Svelte) components as full pages. The [Evil Martians Inertia Rails React Starter Kit](https://evilmartians.com/opensource/inertia-rails-react-starter-kit) is a polished example of this approach, not a separate category. **Strengths:** - Simple mental model — controllers drive page navigation, no client-side router needed - Works with multiple frontend frameworks (React, Vue, Svelte) - Built-in form helpers and shared data conventions **Trade-offs:** - **Every page navigation is a server round-trip.** Even client-side transitions hit a Rails controller to serialize page props as JSON. Inertia v2 adds [partial reloads](https://inertia-rails.dev/guide/partial-reloads) to narrow which props are refreshed, but a controller round-trip is still required for every transition and perceived performance depends on Rails response time. - **All-or-nothing per route.** A route is either fully Inertia or fully traditional Rails — you cannot embed a React component into part of an existing ERB template. This makes incremental adoption in existing Rails apps significantly harder compared to React on Rails' `react_component` helper. - **No client-side router compatibility.** Inertia is incompatible with [React Router](https://reactrouter.com/) and [TanStack Router](https://tanstack.com/router) by design — routes live server-side. This rules out type-safe routing, file-based routing, route-level data loaders, and search-params-as-state patterns that have become common in modern React applications. React on Rails Pro supports TanStack Router SSR for teams that want these patterns. - **SSR is opt-in and limited.** SSR requires a separate Node.js server process. Route-level code splitting via dynamic imports works with SSR, but there is no component-level code splitting with SSR or streaming SSR, which are available in React on Rails Pro. - **Controller coupling.** Controllers become tied to the Inertia response protocol. Switching to a different frontend approach later requires rewriting controller actions. - **No path to React Server Components or fragment caching.** **Best for:** New apps where you want a SPA-like experience with server-side routing, using a controller-driven architecture across React, Vue, or Svelte. ### Hotwire / Turbo [Hotwire](https://hotwired.dev/) is Rails' default frontend approach, using Turbo (for page navigation and partial updates) and Stimulus (for lightweight JavaScript behavior). It minimizes JavaScript by sending HTML over the wire. **Strengths:** - Zero-JS approach — most interactivity requires no custom JavaScript - Deep Rails integration — built into Rails 7+ by default - Turbo Streams enable real-time partial page updates **Trade-offs:** - Not React — if your team has React expertise or needs React's component ecosystem, Hotwire is a fundamentally different paradigm - Complex interactive UIs (drag-and-drop, rich editors, data visualizations) can be harder to build - No component reuse between web and mobile (React Native) **Best for:** Apps where most pages are CRUD-oriented and you want to minimize JavaScript complexity. ### Vite Ruby [Vite Ruby](https://vite-ruby.netlify.app/) integrates the [Vite](https://vite.dev/) build tool with Rails. Vite uses esbuild for fast development builds and Rollup for optimized production bundles. The `vite_rails` gem provides asset tag helpers and a dev server proxy, but it is a **build tool only** — it does not provide React-specific helpers, server-side rendering, or a component rendering layer. **Strengths:** - Very fast dev server startup and HMR via Vite's native ESM approach - Large plugin ecosystem (Vite plugins, Rollup plugins) - Simple configuration compared to Webpack **Trade-offs:** - No `react_component` view helper — you must manually mount React components via DOM selectors or data attributes - SSR is possible, but the Rails integration is much more DIY and currently less turnkey than React on Rails - No props-from-controller pattern — data must be passed through `data-*` attributes, JSON script tags, or a separate API - No auto-bundling — each component entry point must be manually registered **Best for:** Rails apps that only need client-side React rendering and want the simplest possible build tooling without SSR or Rails view integration. ### Vite vs Rspack: Build Tooling Compared If build performance is your primary concern, both Vite and Rspack offer dramatic improvements over Webpack — but they have different strengths. The following benchmarks come from [rspack-contrib/performance-compare](https://github.com/rspack-contrib/performance-compare), an open-source benchmark suite maintained by the Rspack team that tests both tools on identical React component trees. Treat these numbers as directional rather than independently verified. #### Build Performance Benchmarks **Dev server cold startup** (lower is better): | Project size | Rspack | Vite | Webpack | | -------------- | :------: | :------: | :-------: | | 1k components | 942 ms | 3,702 ms | 3,697 ms | | 5k components | 759 ms | 3,294 ms | 9,324 ms | | 10k components | 1,438 ms | 6,505 ms | 21,444 ms | Rspack's dev server starts **3–5x faster** than Vite because it bundles upfront in Rust, while Vite serves unbundled ESM and transforms on demand — which scales less well as the module graph grows. **Hot module replacement** (lower is better): | Project size | Rspack | Vite | Webpack | | -------------- | :----: | :----: | :------: | | 1k components | 129 ms | 133 ms | 444 ms | | 5k components | 105 ms | 147 ms | 1,831 ms | | 10k components | 137 ms | 129 ms | 2,783 ms | HMR is **essentially a tie** — both deliver sub-150ms updates at any project size. **Production builds** (lower is better): | Project size | Rspack | Vite | Webpack | | -------------- | :------: | :------: | :-------: | | 1k components | 539 ms | 386 ms | 3,555 ms | | 5k components | 1,724 ms | 1,075 ms | 9,278 ms | | 10k components | 3,466 ms | 1,986 ms | 28,138 ms | Vite (powered by Rolldown) produces production builds **1.4–1.7x faster** than Rspack. Both are **5–10x faster** than Webpack. **Memory usage in development** (lower is better): | Project size | Rspack | Vite | Webpack | | -------------- | :----: | :------: | :------: | | 5k components | 305 MB | 740 MB | 1,642 MB | | 10k components | 367 MB | 1,214 MB | 2,064 MB | Rspack uses **2–3x less memory** than Vite in development. #### Integration Comparison Build speed is only part of the picture. Here's how the two approaches compare as Rails integration tools: | Aspect | Vite (via vite_rails) | Rspack (via Shakapacker) | | -------------------------- | ----------------------------------------------- | ---------------------------------------------------- | | **SSR support** | Vite SSR mode (manual Rails integration) | Integrated with React on Rails SSR pipeline | | **Webpack compatibility** | None — different plugin/loader format | Near-complete Webpack API compatibility | | **Migration from Webpack** | Full rewrite of build config | Minimal changes — same config format | | **Rails view integration** | Asset tag helpers; manual component mounting | `react_component` helper with props from controllers | | **Client-side routing** | Any React router (React Router, TanStack, etc.) | Any React router; TanStack Router SSR in Pro | | **Plugin ecosystem** | Vite/Rollup plugins | Webpack/Rspack plugins | **Key takeaway:** As pure bundlers, Vite and Rspack are both excellent — Rspack starts dev faster and uses less memory, while Vite produces production builds faster. HMR is a tie. But Vite is _only_ a bundler. Choosing Vite means giving up React on Rails' `react_component` helper, automatic props passing from controllers, built-in SSR, and auto-bundling. With Rspack, you get competitive build speeds while retaining the full React on Rails integration layer. If you need SSR, the gap widens further: React on Rails provides SSR out of the box, while Vite requires building a custom Node.js rendering pipeline and wiring it into Rails yourself. ### React on Rails (OSS) [React on Rails](https://github.com/shakacode/react_on_rails) provides full React integration with Rails views. Components render directly in ERB/Haml templates via the `react_component` helper, with props passed from Rails. Server-side rendering uses ExecJS (via mini_racer). **Strengths:** - Render React components alongside Rails views — progressive enhancement, not all-or-nothing - Built-in SSR for SEO and fast initial page loads - No separate API layer needed — props flow directly from controllers - Auto-bundling eliminates manual pack management - Rspack support for faster builds (~20x vs Webpack) - Hot module replacement for fast development **Best for:** Rails apps that need React's component model with server-side rendering, without replacing the Rails view layer. ### React on Rails Pro [React on Rails Pro](../../pro/react-on-rails-pro.md) extends the OSS gem with production-grade rendering performance and modern React features. **Key additions over OSS:** - **React Server Components** — full RSC support with Rails integration - **Streaming SSR** — progressive rendering with React 18's `renderToPipeableStream` - **Node renderer** — dedicated Node.js server for 3-10x faster SSR (replaces ExecJS) - **Fragment caching** — cache rendered components with `cached_react_component` - **Code splitting with SSR** — route-based splitting via Loadable Components - **TanStack Router SSR** — type-safe routing with server rendering Available under ShakaCode Trust-Based Commercial Licensing for free evaluation, with startup-friendly pricing for production licenses. See [Pro pricing and sign up](https://pro.reactonrails.com/), the [React on Rails Pro docs](../../pro/react-on-rails-pro.md), and the [OSS vs Pro feature matrix](./oss-vs-pro.md) for a detailed breakdown. **Best for:** Production Rails apps with high-traffic pages, SEO requirements, or need for React Server Components. ### Next.js + Rails API [Next.js](https://nextjs.org/docs/app) is the React-first benchmark for App Router, React Server Components, and streaming. It is a strong choice when your team wants the frontend framework to drive the architecture and is comfortable treating Rails as an API or backend service rather than the main rendering app. **Strengths:** - Excellent App Router, streaming, and RSC support - Large React ecosystem mindshare and deployment ecosystem - Strong choice when the team is already oriented around Node-first frontend architecture **Trade-offs:** - Usually means separating frontend and backend concerns instead of keeping one Rails app - Duplicates routing, auth/session, and deployment concerns across two layers unless designed very carefully - Less natural if your goal is to add React to an existing Rails app without re-architecting it **Best for:** React-first teams that want a frontend-led architecture and are willing to split responsibilities between Next.js and Rails. ## Choosing the Right Approach | Your situation | Recommended approach | | ------------------------------------- | ----------------------------------------------------------------------------------------- | | CRUD-heavy app, minimal JS needed | Hotwire / Turbo | | SPA-like experience, server routing | Inertia.js | | Client-side React only, no SSR needed | Vite Ruby (simple) or React on Rails (with Rails view integration) | | React components within Rails views | React on Rails (OSS) | | React + SSR + SEO requirements | React on Rails (OSS or Pro) | | React-first app with a separate API | Next.js + Rails API | | High-traffic SSR, RSC, streaming | React on Rails Pro | | Fast builds + full Rails integration | React on Rails with Rspack | | Legacy react-rails app | Migrate to React on Rails ([migration guide](../migrating/migrating-from-react-rails.md)) | ## Can I Combine Approaches? Yes. React on Rails is designed for progressive adoption: - Use Hotwire for simple pages and React on Rails for interactive components on the same app - Start with React on Rails OSS and upgrade to Pro when you need advanced features ## Further Reading - [OSS vs Pro feature comparison](./oss-vs-pro.md) - [Quick Start guide](./quick-start.md) - [Migration from react-rails](../migrating/migrating-from-react-rails.md) ================================================================================ PAGE: https://reactonrails.com/docs/getting-started/nextjs-with-separate-rails-backend SOURCE: docs/oss/getting-started/nextjs-with-separate-rails-backend.md ================================================================================ # Next.js with a Separate Rails Backend: Pros and Drawbacks Teams evaluating React on Rails often ask whether they should instead run Next.js as a standalone frontend and Rails as a separate backend API. This guide outlines the tradeoffs so you can decide based on architecture and team constraints, not trend pressure. ## What This Architecture Means In this model: - Next.js owns the web UI, frontend routing, and frontend SSR. - Rails exposes JSON/GraphQL APIs and usually owns business rules, persistence, and background jobs. - Frontend and backend become independent deployables with an explicit API contract between them. ## Pros - Clear frontend/backend ownership boundaries - API reuse for additional clients (mobile apps, partner integrations, internal tools) - Frontend release cadence can move independently from backend release cadence - Strong fit for organizations already staffed like separate frontend and platform teams ## Drawbacks - Two deploy pipelines and two production runtimes to monitor - Cross-app authentication/session complexity (cookies, CSRF, token flows, refresh behavior) - More contract maintenance between teams (versioning, schema drift, backwards compatibility) - Extra integration testing burden to catch frontend/backend contract regressions - More distributed debugging across service boundaries ## Where React on Rails Differs React on Rails keeps Rails and React integrated in one app boundary: - React components can be rendered directly from Rails views - You can avoid mandatory API-first architecture for server-rendered pages - End-to-end debugging and deployment are often simpler for Rails-first teams This is often a better fit when your primary goal is substantial React UI in a Rails app without taking on full frontend/backend split complexity. ## Decision Checklist Choose **Next.js + separate Rails backend** if most of these are true: - You explicitly want API-first boundaries as a long-term architecture - You already operate with independent frontend/backend ownership - You need the same API consumed by multiple external clients Choose **React on Rails** if most of these are true: - You want one integrated deployment and ownership model - Your team is Rails-heavy and wants React without full stack separation - You want to incrementally adopt React within existing Rails views/pages ## Related Reading - [Comparing React on Rails to alternatives](./comparing-react-on-rails-to-alternatives.md) - [Comparison with alternatives (feature matrix and benchmarks)](./comparison-with-alternatives.md) - [Installation into an Existing Rails App](./installation-into-an-existing-rails-app.md) ================================================================================ PAGE: https://reactonrails.com/docs/upgrading/release-notes/15.0.0 SOURCE: docs/oss/upgrading/release-notes/15.0.0.md ================================================================================ # React on Rails 15.0.0 Release Notes **⚠️ Version 15.0.0 has been retracted. Please upgrade directly to v16.0.0.** See [React on Rails 16.0.0 Release Notes](./16.0.0.md) for the latest version. ================================================================================ PAGE: https://reactonrails.com/docs/upgrading/release-notes/16.0.0 SOURCE: docs/oss/upgrading/release-notes/16.0.0.md ================================================================================ # React on Rails 16.0.0 Release Notes Also see the [Changelog for 16.0.0](https://github.com/shakacode/react_on_rails/blob/main/CHANGELOG.md#1600---2025-01-xx). **Note: Version 15.0.0 has been retracted. Please upgrade directly from v14 to v16.** ## Major Features ### 🚀 React Server Components Support Experience the future of React with full RSC integration in your Rails apps: - Seamlessly use React Server Components - Reduce client bundle sizes - Enable powerful new patterns for data fetching - ⚡️ Requires React on Rails Pro - [See the full tutorial](../../../pro/react-server-components/tutorial.md) ### 🚀 Major Performance Breakthrough: Early Hydration **React on Rails now starts hydration even before the full page is loaded!** This revolutionary change delivers significant performance improvements across all pages: - **Eliminates Race Conditions**: No more waiting for full page load before hydration begins - **Faster Time-to-Interactive**: Components hydrate as soon as their server-rendered HTML reaches the client - **Streaming HTML Optimization**: Perfect for modern streaming responses - components hydrate in parallel with page streaming - **Async Script Safety**: Can use `async` scripts without fear of race conditions - **No More Defer Needed**: The previous need for `defer` to prevent race conditions has been eliminated This optimization is particularly impactful for: - **Streamed pages** where content loads progressively - **Large pages** with many components - **Slow network conditions** where every millisecond counts - **Modern web apps** requiring fast interactivity _How early hydration changes the timeline:_ [Diagram: A timeline comparison of two hydration strategies. In v14 and v15, hydration is a serial waterfall: the browser downloads the full page, renders it, and only after full page load does hydration begin, so time-to-interactive is late. In v16, with async pack loading and immediate hydration, HTML streams from the server while each component hydrates as soon as its server-rendered markup and code arrive — hydration runs in parallel with page streaming, so components become interactive much earlier.] _Performance improvement visualization:_  _The image above demonstrates the dramatic performance improvement:_ - **Left (Before)**: Hydration didn't start until the full page load completed, causing a huge delay before hydration - **Right (After)**: Hydration starts immediately as soon as components are available, without waiting for full page load - **Result**: Components now become interactive much faster, eliminating the previous race condition delays ### Enhanced Script Loading Strategies - New configuration option `generated_component_packs_loading_strategy` replaces `defer_generated_component_packs` - Supports three loading strategies: - `:async` - Loads scripts asynchronously (default for Shakapacker ≥ 8.2.0) - `:defer` - Defers script execution until after page load (doesn't work well with Streamed HTML as it will wait for the full page load before hydrating the components) - `:sync` - Loads scripts synchronously (default for Shakapacker < 8.2.0) (better to upgrade to Shakapacker 8.2.0 and use `:async` strategy) - Improves page performance by optimizing how component packs are loaded ## Breaking Changes ### Component Hydration Changes - The `defer_generated_component_packs` configuration has been deprecated. Use `generated_component_packs_loading_strategy` instead. - The `generated_component_packs_loading_strategy` defaults to `:async` for Shakapacker ≥ 8.2.0 and `:sync` for Shakapacker < 8.2.0. - The `immediate_hydration` configuration now defaults to `false`. **Note: `immediate_hydration` is a React on Rails Pro (licensed) feature.** - When `generated_component_packs_loading_strategy: :async` and `immediate_hydration: true` are configured together, they optimize component hydration. Components hydrate as soon as their code and server-rendered HTML are available, without waiting for the full page to load. This parallel processing significantly improves time-to-interactive by eliminating the traditional waterfall of waiting for page load before beginning hydration (It's critical for streamed HTML). - The previous need for deferring scripts to prevent race conditions has been eliminated due to improved hydration handling. Making scripts not defer is critical to execute the hydration scripts early before the page is fully loaded. - The `immediate_hydration` configuration (React on Rails Pro licensed feature) makes `react-on-rails` hydrate components immediately as soon as their server-rendered HTML reaches the client, without waiting for the full page load. - To enable optimized hydration, you can set `immediate_hydration: true` in your `config/initializers/react_on_rails.rb` file (requires React on Rails Pro license). - You can also enable it for individual components by passing `immediate_hydration: true` to `react_component` or `stream_react_component`. - Redux store now supports the `immediate_hydration` option (React on Rails Pro licensed feature), which defaults to `config.immediate_hydration` (and so to `false` if that isn't set). If `true`, the Redux store will hydrate immediately as soon as its server-side data reaches the client. - You can override this behavior for individual Redux stores by calling the `redux_store` helper with `immediate_hydration: true` or `immediate_hydration: false`, same as `react_component`. - `ReactOnRails.reactOnRailsPageLoaded()` is now an async function: - If you manually call this function to ensure components are hydrated (e.g., with async script loading), you must now await the promise it returns: ```js // Before ReactOnRails.reactOnRailsPageLoaded(); // Code expecting all components to be hydrated // After await ReactOnRails.reactOnRailsPageLoaded(); // Code expecting all components to be hydrated ``` - If you call it in a `turbolinks:load` listener to work around the issue documented in [Turbolinks](../../building-features/turbolinks.md#async-script-loading), the listener can be safely removed. ### Script Loading Strategy Migration - If you were previously using `defer_generated_component_packs: true`, use `generated_component_packs_loading_strategy: :defer` instead - If you were previously using `defer_generated_component_packs: false`, use `generated_component_packs_loading_strategy: :sync` instead - For optimal performance with Shakapacker ≥ 8.2.0, consider using `generated_component_packs_loading_strategy: :async` ### ESM-only package The package is now published as ES Modules instead of CommonJS. In most cases it shouldn't affect your code, as bundlers will be able to handle it. However: - If you explicitly use `require('react-on-rails')`, and can't change to `import`, upgrade to Node v20.19.0+ or v22.12.0+. They allow `require` for ESM modules without any flags. Node v20.17.0+ with `--experimental-require-module` should work as well. - If you run into `TS1479: The current file is a CommonJS module whose imports will produce 'require' calls; however, the referenced file is an ECMAScript module and cannot be imported with 'require'.` TypeScript error, you'll need to [upgrade to TypeScript 5.8 and set `module` to `nodenext`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-8.html#support-for-require-of-ecmascript-modules-in---module-nodenext). Finally, if everything else fails, please contact us and we'll help you upgrade or release a dual ESM-CJS version. ### `globalThis` [`globalThis`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/globalThis) is now used in code. It should be available in browsers since 2020 and in Node, but in case your environment doesn't support it, you'll need to shim it using [globalthis](https://www.npmjs.com/package/globalthis) or [core-js](https://www.npmjs.com/package/core-js). ## Store Dependencies for Components When using Redux stores with multiple components, you need to explicitly declare store dependencies to optimize hydration. Here's how: ### The Problem If you have deferred Redux stores and components like this: ```erb <% redux_store("SimpleStore", props: @app_props_server_render, defer: true) %> <%= react_component('ReduxApp', {}, {prerender: true}) %> <%= react_component('ComponentWithNoStore', {}, {prerender: true}) %> <%= redux_store_hydration_data %> ``` By default, React on Rails assumes components depend on all previously created stores. This means: - Neither `ReduxApp` nor `ComponentWithNoStore` will hydrate until `SimpleStore` is hydrated - Since the store is deferred to the end of the page, both components are forced to wait unnecessarily ### The Solution Explicitly declare store dependencies for each component: ```erb <% redux_store("SimpleStore", props: @app_props_server_render, defer: true) %> <%= react_component('ReduxApp', {}, { prerender: true # No need to specify store_dependencies: it automatically depends on SimpleStore }) %> <%= react_component('ComponentWithNoStore', {}, { prerender: true, # Explicitly declare no store dependencies store_dependencies: [] }) %> <%= redux_store_hydration_data %> ``` This allows `ComponentWithNoStore` to hydrate immediately without waiting for `SimpleStore`, improving page performance. ================================================================================ PAGE: https://reactonrails.com/docs/upgrading/release-notes/16.2.0 SOURCE: docs/oss/upgrading/release-notes/16.2.0.md ================================================================================ # React on Rails 16.2.0 Release Notes React on Rails 16.2.0 is a major release focused on **clear separation between the open-source core and React on Rails Pro**. This release simplifies configuration by making Pro features automatic for licensed users, adds Rspack support for faster builds, and includes critical security fixes for React Server Components. ## Upgrading from 16.1.x to 16.2.0 Update your gem and npm package versions: ```ruby # Gemfile gem "react_on_rails", "16.2.0" gem "shakapacker", "9.0.0" # or 8.2.0+ for existing projects ``` ```json // package.json { "dependencies": { "react-on-rails": "16.2.0", "shakapacker": "9.0.0" } } ``` Then run `bundle install` and your package manager's install command. **Important:** The shakapacker gem and npm package versions must match exactly. ## Version Compatibility | Component | Minimum | Recommended | | ----------- | ------- | ----------- | | Ruby | 3.0 | 3.3+ | | Node.js | 18 | 22+ | | Shakapacker | 6.0 | 9.0.0+ | | React | 18 | 19+ | | Rails | 5.2 | 7.0+ | **Note:** While the gem supports Ruby 3.0+ and Node.js 18+, CI only tests against Ruby 3.2+ and Node.js 20+. Using lower versions may work but is not continuously tested. ## Breaking Changes ### 1. `config.immediate_hydration` Configuration Removed The `config.immediate_hydration` setting in `config/initializers/react_on_rails.rb` has been removed. Immediate hydration is now **automatically enabled for React on Rails Pro users** and **automatically disabled for non-Pro users**. **Migration steps:** 1. Remove any `config.immediate_hydration = true` or `config.immediate_hydration = false` lines from your initializer 2. **Pro users:** No action needed - immediate hydration is now enabled automatically 3. **Non-Pro users:** No action needed - standard hydration behavior continues **Component-level overrides still work:** ```ruby # Override for a specific component <%= react_component("MyComponent", props, immediate_hydration: false) %> # Override for a specific store <%= redux_store("MyStore", props: store_props, immediate_hydration: true) %> ``` **Note:** If a non-Pro user explicitly sets `immediate_hydration: true`, a warning will be logged and the value will be overridden to `false`. [PR 1997](https://github.com/shakacode/react_on_rails/pull/1997) by [AbanoubGhadban](https://github.com/AbanoubGhadban). ### 2. Pro-Only Methods Throw Runtime Errors Without Pro Package Several methods in the `react-on-rails` npm package now throw runtime errors if called without the Pro package. Calling these methods will throw: `"<method> requires react-on-rails-pro package"`: - `getOrWaitForComponent()` - `getOrWaitForStore()` - `getOrWaitForStoreGenerator()` - `reactOnRailsStoreLoaded()` - `streamServerRenderedReactComponent()` - `serverRenderRSCReactComponent()` **Migration (if using these methods):** ```javascript // Before import ReactOnRails from 'react-on-rails'; // After import ReactOnRails from 'react-on-rails-pro'; ``` **Note:** If you're not using any of these methods, no changes are required. ### 3. RSC Configurations Moved to Pro Gem React Server Components configurations have moved from `ReactOnRails.configure` to `ReactOnRailsPro.configure`: ```ruby # Before ReactOnRails.configure do |config| config.rsc_bundle_js_file = "rsc-bundle.js" config.react_server_client_manifest_file = "react-server-client-manifest.json" config.react_client_manifest_file = "react-client-manifest.json" end # After ReactOnRailsPro.configure do |config| config.rsc_bundle_js_file = "rsc-bundle.js" config.react_server_client_manifest_file = "react-server-client-manifest.json" config.react_client_manifest_file = "react-client-manifest.json" end ``` ### 4. Streaming View Helpers Moved to Pro Gem The following view helpers are now only available in React on Rails Pro: - `stream_react_component` - Progressive SSR using React 18+ streaming - `rsc_payload_react_component` - RSC payload rendering ### 5. Strict Version Validation at Boot Time Applications now **fail to boot** (instead of logging warnings) when `package.json` is misconfigured with: - Wrong versions - Missing packages - Semver wildcards (`^`, `~`, `>`, `<`, `*`) **Migration:** ```json // Before (will fail) { "dependencies": { "react-on-rails": "^16.2.0" } } // After (correct) { "dependencies": { "react-on-rails": "16.2.0" } } ``` [PR 1881](https://github.com/shakacode/react_on_rails/pull/1881) by [AbanoubGhadban](https://github.com/AbanoubGhadban). ### 6. Node Renderer Version Validation (Pro Only) The remote node renderer now validates gem version at request time. Version mismatches in development return `412 Precondition Failed` (production allows with warning). **Migration:** Ensure `react_on_rails_pro` gem and `@shakacode-tools/react-on-rails-pro-node-renderer` package versions match. ## New Features ### Rspack Support Added `--rspack` flag to `react_on_rails:install` generator for significantly faster builds (~20x improvement with SWC): ```bash rails generate react_on_rails:install --rspack ``` Includes a `bin/switch-bundler` utility to switch between webpack and Rspack post-installation. [PR 1852](https://github.com/shakacode/react_on_rails/pull/1852) by [justin808](https://github.com/justin808). ### Shakapacker 9.0+ Private Output Path Integration React on Rails now automatically detects and integrates with Shakapacker 9.0+ `private_output_path` configuration, eliminating manual configuration synchronization for server bundles. [PR 2028](https://github.com/shakacode/react_on_rails/pull/2028) by [justin808](https://github.com/justin808). ### CSP Nonce Support for Console Replay When Rails CSP is configured, the console replay script automatically includes the nonce attribute, allowing it to execute under restrictive CSP policies like `script-src: 'self'`. [PR 2059](https://github.com/shakacode/react_on_rails/pull/2059) by [justin808](https://github.com/justin808). ### Smart Error Messages with Actionable Solutions New intelligent Ruby-side error handling with: - Fuzzy matching for component name typos - Environment-specific debugging suggestions - Color-coded error formatting - Detailed troubleshooting guides [PR 1934](https://github.com/shakacode/react_on_rails/pull/1934) by [justin808](https://github.com/justin808). ### Service Dependency Checking for bin/dev Optional `.dev-services.yml` configuration to validate required external services (Redis, PostgreSQL, etc.) are running before `bin/dev` starts: ```yaml # .dev-services.yml services: - name: redis check: redis-cli ping start: redis-server ``` [PR 2098](https://github.com/shakacode/react_on_rails/pull/2098) by [justin808](https://github.com/justin808). ## Security ### Critical: React Server Components Vulnerabilities Fixed **Action Required:** React on Rails Pro users using RSC should upgrade immediately to get React 19.0.3 and react-on-rails-rsc 19.0.4. Upgraded React to v19.0.3 and react-on-rails-rsc to v19.0.4 to fix three security vulnerabilities: | CVE | Severity | Description | | -------------- | ------------ | --------------------------------------------------------------------- | | CVE-2025-55183 | 5.3 (Medium) | Source code exposure when server function references were stringified | | CVE-2025-55184 | 7.5 (High) | DoS via cyclic promise references causing infinite loops | | CVE-2025-67779 | 7.5 (High) | DoS via cyclic promise references causing 100% CPU consumption | [PR 2233](https://github.com/shakacode/react_on_rails/pull/2233) by [AbanoubGhadban](https://github.com/AbanoubGhadban). ### Development Dependencies Security Addressed 58 Dependabot vulnerabilities in dev/test dependencies including critical issues in webpack, nokogiri, activestorage, and rack. [PR 2261](https://github.com/shakacode/react_on_rails/pull/2261) by [ihabadham](https://github.com/ihabadham). ### Command Injection Protection Added security hardening to prevent potential command injection in package manager commands. [PR 1881](https://github.com/shakacode/react_on_rails/pull/1881) by [AbanoubGhadban](https://github.com/AbanoubGhadban). ## Bug Fixes - **Component Registration**: Fixed "component not registered" error that could occur when components were referenced before registration completed. [PR 2295](https://github.com/shakacode/react_on_rails/pull/2295) by [AbanoubGhadban](https://github.com/AbanoubGhadban) - **webpack-cli Compatibility**: Fixed compatibility with webpack-dev-server v5. [PR 2291](https://github.com/shakacode/react_on_rails/pull/2291) by [AbanoubGhadban](https://github.com/AbanoubGhadban) - **Hydration Mismatch**: Fixed errors when `reactOnRailsPageLoaded()` was called multiple times. [PR 2211](https://github.com/shakacode/react_on_rails/pull/2211) by [justin808](https://github.com/justin808) - **Rails 5.2-6.0 Compatibility**: Added polyfill for `compact_blank` method. [PR 2058](https://github.com/shakacode/react_on_rails/pull/2058) by [justin808](https://github.com/justin808) - **connection_pool 3.0+ Compatibility**: Fixed ArgumentError with newer connection_pool versions. [PR 2125](https://github.com/shakacode/react_on_rails/pull/2125) by [justin808](https://github.com/justin808) See the [CHANGELOG](https://github.com/shakacode/react_on_rails/blob/main/CHANGELOG.md) for additional bug fixes and improvements. ## Common Upgrade Issues ### "Cannot find module 'react-on-rails-pro'" **Symptom:** Application fails to start with module not found error. **Cause:** You're using Pro-only methods but haven't installed the Pro package. **Solution:** ```bash npm install react-on-rails-pro # or yarn add react-on-rails-pro # or pnpm add react-on-rails-pro ``` ### Version Mismatch Boot Failure **Symptom:** Application fails to boot with version validation error. **Cause:** `package.json` has semver wildcards or mismatched versions. **Solution:** Use exact versions matching your installed gem: ```bash # Check gem version bundle show react_on_rails # Update package.json to match (no ^, ~, or *) ``` ### Immediate Hydration Config Warning **Symptom:** Deprecation warning about `config.immediate_hydration` in logs. **Cause:** The global config option is now deprecated and has no effect. **Solution:** Remove `config.immediate_hydration` from your initializer. The setting is now automatic (enabled for Pro users, disabled for non-Pro). ## Related Resources - [Changelog](https://github.com/shakacode/react_on_rails/blob/main/CHANGELOG.md) - [Configuration Reference](../../configuration/README.md) - [React on Rails Pro](../../../pro/react-on-rails-pro.md) ================================================================================ PAGE: https://reactonrails.com/docs/upgrading/release-notes/16.3.0 SOURCE: docs/oss/upgrading/release-notes/16.3.0.md ================================================================================ # React on Rails 16.3.0 Release Notes ## Upgrading from 16.2.x to 16.3.0 Update your gem and npm package versions: ```ruby # Gemfile gem "react_on_rails", "16.3.0" ``` ```json // package.json { "dependencies": { "react-on-rails": "16.3.0" } } ``` **Pro users:** Use `react-on-rails-pro` instead of `react-on-rails` in package.json, and `react_on_rails_pro` instead of `react_on_rails` in your Gemfile. See the [Pro upgrade guide](../../../pro/updating.md) for details. Then run `bundle install` and your package manager's install command. ## Key Changes ### Simplified Shakapacker Version Handling Removed obsolete minimum version checks (6.5.1) and example generation pinning (8.2.0). The gemspec dependency `shakapacker >= 6.0` is now the only minimum version requirement, with autobundling requiring >= 7.0.0. [PR 2247](https://github.com/shakacode/react_on_rails/pull/2247). ### Bug Fixes - **Rspack configuration not applying to all environments**: Fixed `bin/switch-bundler` crashing with `Psych::AliasesNotEnabled` on YAML files with anchors/aliases, and fixed the `--rspack` generator flag only updating the `default` section. [PR 2275](https://github.com/shakacode/react_on_rails/pull/2275). - **Precompile hook not configured when Shakapacker is pre-installed**: Fixed the install generator not configuring the `precompile_hook` when Shakapacker was already installed. [PR 2280](https://github.com/shakacode/react_on_rails/pull/2280). - **`bin/dev` failing with `--route` flag**: Fixed `bin/dev` command failing with "Unknown argument" when the generator was run with a `--route` option. [PR 2273](https://github.com/shakacode/react_on_rails/pull/2273). ### Pro Changes - **License-Optional Attribution Model**: React on Rails Pro now works without a license for evaluation, development, testing, and CI/CD. A paid license is only required for production deployments. [PR 2324](https://github.com/shakacode/react_on_rails/pull/2324). - **Multiple License Plan Types**: License validation now supports plan types beyond "paid": `startup`, `nonprofit`, `education`, `oss`, and `partner`. [PR 2334](https://github.com/shakacode/react_on_rails/pull/2334). - **Node Renderer Master/Worker Exports**: Added public `master` and `worker` exports to `react-on-rails-pro-node-renderer`. [PR 2326](https://github.com/shakacode/react_on_rails/pull/2326). See the [CHANGELOG](https://github.com/shakacode/react_on_rails/blob/master/CHANGELOG.md) for the full list of changes. ================================================================================ PAGE: https://reactonrails.com/docs/upgrading/release-notes/16.4.0 SOURCE: docs/oss/upgrading/release-notes/16.4.0.md ================================================================================ # React on Rails 16.4.0 Release Notes ## Upgrading from 16.3.x to 16.4.0 Update your gem and npm package versions: ```ruby # Gemfile gem "react_on_rails", "16.4.0" ``` ```json // package.json { "dependencies": { "react-on-rails": "16.4.0" } } ``` **Pro users:** Use `react-on-rails-pro` instead of `react-on-rails` in package.json, and `react_on_rails_pro` instead of `react_on_rails` in your Gemfile. See the [Pro upgrade guide](../../../pro/updating.md) for details. Then run `bundle install` and your package manager's install command. ## Highlights This is a large release with significant improvements to the install generator, development workflow, and Pro stability. See the [CHANGELOG](https://github.com/shakacode/react_on_rails/blob/master/CHANGELOG.md) for the full list of changes. ### Generator Improvements - **TypeScript and rspack config detection**: The install generator now correctly handles TypeScript configs (`.ts`) and rspack bundler configs. [PR 2567](https://github.com/shakacode/react_on_rails/pull/2567). - **Incomplete install messaging**: The generator now warns explicitly when Shakapacker setup fails, instead of showing a misleading "Successfully Installed" banner. [PR 2613](https://github.com/shakacode/react_on_rails/pull/2613). - **`--pretend` safe dry run**: `--pretend` no longer executes real setup commands or crashes on `File.chmod`. [PR 2536](https://github.com/shakacode/react_on_rails/pull/2536). - **Clean stale webpack config on `--rspack` install**: Removes leftover `config/webpack/` files when switching to rspack. [PR 2597](https://github.com/shakacode/react_on_rails/pull/2597). ### Development Workflow - **Automatic dev asset reuse for tests**: When `bin/dev static` is running, `bundle exec rspec` automatically detects and reuses fresh development assets. [PR 2570](https://github.com/shakacode/react_on_rails/pull/2570). - **Environment-variable-driven ports**: Procfile templates now use `${PORT:-3000}` and `${SHAKAPACKER_DEV_SERVER_PORT:-3035}`, enabling multiple worktrees. [PR 2539](https://github.com/shakacode/react_on_rails/pull/2539). - **`create-react-on-rails-app --rsc`**: Single command to scaffold an RSC-ready app. [PR 2430](https://github.com/shakacode/react_on_rails/pull/2430). ### SSR and Rendering - **`server_render_js` handles non-Error throws**: Defensive error serialization now supports thrown primitives and `null` values. [PR 2599](https://github.com/shakacode/react_on_rails/pull/2599). - **Smarter duplicate registration warnings**: Re-registering the same component (common with HMR) is now silently accepted. [PR 2354](https://github.com/shakacode/react_on_rails/pull/2354). ### Pro Changes - **TanStack Router SSR**: New `createTanStackRouterRenderFunction` via `react-on-rails-pro/tanstack-router`. [PR 2516](https://github.com/shakacode/react_on_rails/pull/2516). - **CSP nonce for immediate hydration and RSC streaming**: Inline `<script>` tags now include CSP nonce attributes. [PR 2398](https://github.com/shakacode/react_on_rails/pull/2398), [PR 2418](https://github.com/shakacode/react_on_rails/pull/2418). - **License verification rake task**: New `react_on_rails_pro:verify_license` task with JSON output for CI/CD. [PR 2385](https://github.com/shakacode/react_on_rails/pull/2385). - **RSC payload template format**: Pro now renders RSC payload templates with `formats: [:text]` to prevent Rails view annotations from corrupting NDJSON. If you override `custom_rsc_payload_template`, ensure it resolves to a `.text.erb` template. [PR 2535](https://github.com/shakacode/react_on_rails/pull/2535). - **Breaking: removed legacy key-file license fallback**: `config/react_on_rails_pro_license.key` is no longer read. Move your token to the `REACT_ON_RAILS_PRO_LICENSE` environment variable. [PR 2454](https://github.com/shakacode/react_on_rails/pull/2454). ### Bug Fixes Numerous bug fixes for CSS module SSR with rspack, `bin/dev` hook resolution, generator test defaults, precompile hook coordination, and more. See the [CHANGELOG](https://github.com/shakacode/react_on_rails/blob/master/CHANGELOG.md) for details.