Registry / web-framework / react-on-rails

react-on-rails

library16.6.0jsnpmunverified

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.

web-framework

npm install react-on-rails

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · REACT-ON-RAILS

react-on-rails

web-frameworkjavascriptv16.6.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

ReactOnRails

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

✗ const ReactOnRails = require('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

✓ import ReactOnRailsClient from 'react-on-rails/client';

✗ import ReactOnRailsClient from 'react-on-rails';

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

✓ import type { ReactOnRails } from 'react-on-rails/types';

✗ import { ReactOnRails } from 'react-on-rails';

For importing type definitions only, use the dedicated `/types` subpath to avoid bundling runtime code.

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.');

Debug

Known issues

breakingThe `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.

affects: >=16.6.0

gotchaThis 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.

affects: >=1.0

gotchaFor 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`.

affects: >=16.4.0

gotchaIncorrectly 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.

affects: >=16.4.0

Errors

Common errors & fixes

ReferenceError: ReactOnRails is not defined

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`

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

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

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.

Upgrade

Version history

16.6.0latest on npm

Audit

Dependencies

reactrequiredPeer dependency for React component rendering.

react-domrequiredPeer dependency for DOM manipulation and hydration.

react-on-rails-prooptionalRequired for accessing Pro-exclusive features and functionalities.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/shakacode/react_on_rails ↗

packagehttps://www.npmjs.com/package/react-on-rails ↗

homepagehttps://www.shakacode.com/react-on-rails/ ↗