React on Rails Client-Side Integration

16.6.0 · active · verified Wed Apr 22

react-on-rails is the client-side JavaScript package designed to integrate React applications seamlessly within a Ruby on Rails environment, specifically leveraging the Rails asset pipeline (e.g., Shakapacker, Webpack, Rspack). Currently at stable version 16.6.0, the library facilitates component registration, client-side hydration, and server-side rendering (SSR) of React components. It maintains an active release cadence with frequent updates and bug fixes, indicated by its minor and patch releases. Its primary differentiator is its tight coupling with the `react_on_rails` Ruby gem, providing a robust, opinionated solution for isomorphic React development in Rails. This includes essential functionalities like connecting React components to Redux stores and supporting advanced features such as server-side rendering, with specific capabilities for TanStack Router via its `react-on-rails-pro` offering. It's a foundational component for modern React-in-Rails development.

Common errors

```
ReferenceError: ReactOnRails is not defined
```
cause The `ReactOnRails` object was not correctly imported or required in your JavaScript/TypeScript entry point, or the script failed to load.

fix Ensure your entry file (e.g., `application.js` or `application.ts`) has `import ReactOnRails from 'react-on-rails';` at the top. Verify your asset pipeline is compiling and including this entry file.
```
Unknown configuration option `immediate_hydration`
```
cause You are attempting to use the `immediate_hydration` option, which was removed in version 16.6.0 of `react-on-rails`.

fix Remove `immediate_hydration` from your `react_on_rails` initializer (e.g., `config/initializers/react_on_rails.rb`), from any `react_component` helper calls, and from `redux_store` configurations. This option is no longer supported.
```
Component 'MyComponent' is not registered
```
cause A React component specified in `react_component` helper in a Rails view has not been registered with `ReactOnRails.register()` in your client-side JavaScript bundle.

fix Ensure `ReactOnRails.register({ MyComponent });` is called in your main JavaScript entry file after `MyComponent` has been imported. Double-check the component name for exact matching.
```
Error: Could not find server bundle
```
cause When attempting server-side rendering, the configured server bundle file is either missing, has compilation errors, or is not accessible by the Node.js renderer.

fix Verify that your server bundle (e.g., `server-bundle.js` or `server-bundle.ts`) exists, compiles without errors, and is correctly referenced in your `react_on_rails` configuration. Check `log/react_on_rails.log` for more specific errors during SSR.

Warnings

breaking The `immediate_hydration` configuration option, helper parameter, and related HTML attributes have been completely removed. Immediate hydration is now automatically managed based on your React on Rails Pro subscription status.
Fix: Remove all references to `immediate_hydration` from your React on Rails initializer, helper calls (`react_component`), and Redux store configurations. Any existing usage will lead to errors.
gotcha This npm package (`react-on-rails`) is the client-side JavaScript component and requires the `react_on_rails` Ruby gem to be installed and configured in your Rails application for full functionality.
Fix: Ensure `gem 'react_on_rails'` is present in your `Gemfile` and run `bundle install`, then typically `rails generate react_on_rails:install` to set up the Rails-side integration.
gotcha For Pro features, you must install the separate `react-on-rails-pro` npm package (and the `react_on_rails_pro` Ruby gem). The base `react-on-rails` package does not include these advanced functionalities.
Fix: If using React on Rails Pro, install `npm install react-on-rails-pro` (or `yarn add react-on-rails-pro`) and ensure `gem 'react_on_rails_pro'` is in your `Gemfile`.
gotcha Incorrectly configured bundler (Webpack/Rspack) for TypeScript or ESM projects can lead to issues with asset compilation or server-side rendering.
Fix: Use `rails generate react_on_rails:install` to ensure correct bundler configuration. For troubleshooting, run `react_on_rails:doctor` to diagnose common setup problems, especially with TypeScript or different bundlers.

Install

npm install react-on-rails npm
yarn add react-on-rails yarn
pnpm add react-on-rails pnpm

Imports

ReactOnRails
wrong:
```
const ReactOnRails = require('react-on-rails');
```
correct:
```
import ReactOnRails from 'react-on-rails';
```
Primarily designed for ESM, though CommonJS `require` might work in older bundler setups. Using `import` is the recommended modern approach.
client-only build
wrong:
```
import ReactOnRailsClient from 'react-on-rails';
```
correct:
```
import ReactOnRailsClient from 'react-on-rails/client';
```
Use this import path for a smaller bundle size when server-side rendering (SSR) utilities are not required, typically in client-side entry points.
TypeScript types
wrong:
```
import { ReactOnRails } from 'react-on-rails';
```
correct:
```
import type { ReactOnRails } from 'react-on-rails/types';
```
For importing type definitions only, use the dedicated `/types` subpath to avoid bundling runtime code.

Quickstart

This quickstart registers a simple 'HelloWorld' React component with `react-on-rails`, making it available for rendering within Rails views using the `react_component` helper, supporting both client-side hydration and server-side rendering.

import React from 'react';
import ReactOnRails from 'react-on-rails';

interface HelloWorldProps {
  name: string;
}

const HelloWorld: React.FC<HelloWorldProps> = ({ name }) => {
  return (
    <div>
      <h1>Hello from React, {name}!</h1>
      <p>This component is registered with React on Rails.</p>
    </div>
  );
};

// This line registers the component for client-side and server-side rendering.
// It makes 'HelloWorld' available to the `react_component` Rails helper.
ReactOnRails.register({ HelloWorld });

console.log('HelloWorld component registered successfully.');

view raw JSON →