{"id":16883,"library":"react-on-rails","title":"React on Rails Client-Side Integration","description":"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.","status":"active","version":"16.6.0","language":"javascript","source_language":"en","source_url":"https://github.com/shakacode/react_on_rails","tags":["javascript","react","webpack","JavaScript","Ruby","on","Rails","typescript"],"install":[{"cmd":"npm install react-on-rails","lang":"bash","label":"npm"},{"cmd":"yarn add react-on-rails","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-on-rails","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for React component rendering.","package":"react","optional":false},{"reason":"Peer dependency for DOM manipulation and hydration.","package":"react-dom","optional":false},{"reason":"Required for accessing Pro-exclusive features and functionalities.","package":"react-on-rails-pro","optional":true}],"imports":[{"note":"Primarily designed for ESM, though CommonJS `require` might work in older bundler setups. Using `import` is the recommended modern approach.","wrong":"const ReactOnRails = require('react-on-rails');","symbol":"ReactOnRails","correct":"import ReactOnRails from 'react-on-rails';"},{"note":"Use this import path for a smaller bundle size when server-side rendering (SSR) utilities are not required, typically in client-side entry points.","wrong":"import ReactOnRailsClient from 'react-on-rails';","symbol":"client-only build","correct":"import ReactOnRailsClient from 'react-on-rails/client';"},{"note":"For importing type definitions only, use the dedicated `/types` subpath to avoid bundling runtime code.","wrong":"import { ReactOnRails } from 'react-on-rails';","symbol":"TypeScript types","correct":"import type { ReactOnRails } from 'react-on-rails/types';"}],"quickstart":{"code":"import React from 'react';\nimport ReactOnRails from 'react-on-rails';\n\ninterface HelloWorldProps {\n  name: string;\n}\n\nconst HelloWorld: React.FC<HelloWorldProps> = ({ name }) => {\n  return (\n    <div>\n      <h1>Hello from React, {name}!</h1>\n      <p>This component is registered with React on Rails.</p>\n    </div>\n  );\n};\n\n// This line registers the component for client-side and server-side rendering.\n// It makes 'HelloWorld' available to the `react_component` Rails helper.\nReactOnRails.register({ HelloWorld });\n\nconsole.log('HelloWorld component registered successfully.');\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=16.6.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=16.4.0"},{"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.","message":"Incorrectly configured bundler (Webpack/Rspack) for TypeScript or ESM projects can lead to issues with asset compilation or server-side rendering.","severity":"gotcha","affected_versions":">=16.4.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","cause":"The `ReactOnRails` object was not correctly imported or required in your JavaScript/TypeScript entry point, or the script failed to load.","error":"ReferenceError: ReactOnRails is not defined"},{"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.","cause":"You are attempting to use the `immediate_hydration` option, which was removed in version 16.6.0 of `react-on-rails`.","error":"Unknown configuration option `immediate_hydration`"},{"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.","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.","error":"Component 'MyComponent' is not registered"},{"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.","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.","error":"Error: Could not find server bundle"}],"ecosystem":"npm","meta_description":null}