React-Rails, the Rails gem that tells you to move to React on Rails

The README opens with a migration notice

The first substantive paragraph of this project's own documentation advises moving off the project. It says that while ShakaCode will continue to support the gem, you might consider migrating to React on Rails, or to React on Rails Pro with proper Node rendering.

The reason given is that React on Rails code receives much more active development and testing, and two examples follow. The first is a concrete code comparison: the ReactRailsUJS implementation in react_ujs/index.js against the ReactOnRails Node package, which is written in TypeScript. The same paragraph notes that React on Rails has work underway for the latest React features, React Server Components among them.

There is a migration document with a why section and a step section, plus an anchor for an LLM-assisted migration prompt. A project that ships its own exit instructions tells you something about how its authors see its future, and that belongs in any evaluation before you write code.

The version number lives in three places

Working out which React-Rails you have takes more than one lookup. The README is headed v3. The npm package inside the repository, react_ujs, is version 3.3.1. The GitHub releases list is a different story: the three most recent are v2.6.2 from 2022-04-06, v2.6.0 from 2019-07-27 and v2.5.0 from 2019-03-31.

So the 3.x line was never cut as GitHub releases. There is also a 2.7 line, with its documentation kept on a separate 2.7-stable branch that the README links at the top, and the upgrading guide covers two hops, 2.7 to 3.0 and 2.3 to 2.4. A VERSIONS.md file sits in the repository root for the longer history.

Practically, read your version from the gemspec in your own bundle rather than from a tag list. Anyone upgrading a project today will find that the release page describes a build from four years ago.

Shakapacker 7, Propshaft, Sprockets 4 and 3

The gem's pitch is that it fits whichever asset setup you already have, and the feature list names Shakapacker v7, Propshaft, and Sprockets 4.x and 3.x as supported. Language choice is open too: JSX, ES6, TypeScript and CoffeeScript are all listed as usable.

The documentation is split along the same lines. The getting started guide has one section for Shakapacker and another for the asset pipeline, and the Shakapacker side covers component name, file naming, TypeScript support and testing a component. The asset pipeline side adds a custom JSX transformer with its own transform plugin options, plus a page on React.js versions.

That is the trade in one paragraph. Flexibility across four pipeline generations means more configuration surface, and the choice of which section you need is made before you write any component.

Server-side rendering and UJS are separate contracts

Two distinct mechanisms share the name of the gem's JavaScript half, and the documentation keeps them apart. Server-side rendering has its own page with configuration, JavaScript state and a custom server renderer, which is where you decide what runs in Ruby before the browser takes over.

UJS is the browser side, with pages for mounting and unmounting, event handling and a getConstructor hook. The npm package that ships it is described in its own package.json as Rails UJS for the react-rails gem, with react_ujs/index.js as its main entry.

Keeping the two apart is what makes the component generator and the view helper usable. A Rails view renders a component, the server renderer produces markup when you have configured one, and UJS takes over interaction in the browser. If you only want static markup on the first page, the SSR page is the part to read; if you want a live component, the UJS pages are.

The npm half is one entry point built by webpack

The JavaScript side is small enough to read in one sitting. react_ujs sits at version 3.3.1, declares react_ujs/index.js as its main entry, ships only the react_ujs directory, and builds with a single script:

"scripts": {
  "build": "cd react_ujs && webpack"
}

Its runtime dependencies are react and react-dom, both pinned at ^18.2.0, with webpack ^5.74.0 and webpack-cli ^5.0.1 as the build tools. The repository also declares [email protected] as its package manager and carries a yarn.lock.

Two things are worth noting. The React 18 floor in those dependencies is a hard constraint on what you can install alongside the gem, and the React < 18 warning on the common errors page is the same constraint seen from the other side. Second, a build step driven by yarn 1 in a repository that also has a Gemfile means two toolchains and two lock files to keep in step.

Five failure modes the project names itself

There is a common errors page, and it is the most useful page in the documentation because it lists what breaks rather than what works. Five entries are indexed there. The first is a warning about not being able to resolve 'react-dom/client' in React versions below 18. The second is an Undefined Set error. The third is Using TheRubyRacer, which is a JavaScript runtime problem on the Ruby side. The fourth is HMR, meaning hot module reloading. The fifth is tests placed in a component directory.

That list tells you the shape of the project's rough edges: a version boundary on React, an odd error from a Set, a legacy JS engine, and the ordinary friction of hot reload and component-level testing.

The UJS pages also cover getConstructor and mounting and unmounting.

The generator emits JBuilder and camelized props

There is a component generator with its own documentation page, and three of its sections tell you what it produces. One covers using it with JBuilder. One is called Camelize Props, which is the bridge between Ruby naming and JavaScript prop naming. The third covers changing component templates, so the generated files can match your own conventions instead of the gem's defaults.

Alongside that sit controller actions, a view helper and a page on writing your own view helper. The helper is what lets a Rails template drop a component into a page, and the controller action is what lets you return component data on its own.

For a worked example, the README links a separate application repository, BookOfGreg's react-rails-example-app, which is a faster way to see the whole arrangement than reading the four pages in isolation.

Support runs through ShakaCode, docs split two ways

The project is released under Apache-2.0. Alongside a React + Rails Slack with a #react-rails channel, the README carries a ShakaCode section offering consulting for Rails teams using React and Webpack, with infrastructure and CI cost work alongside, and it names Justin Gordon as the creator of React on Rails and Shakapacker.

Documentation lives in two places, and knowing which one to open saves time. The docs/ directory in the repository holds the getting started guide, the view helper, UJS, server-side rendering, controller actions, the component generator, upgrading, the migration guide and the common errors page. The project wiki is then described as carrying a significant amount of additional information, including instructional articles and answers to questions.

Around the code there is a conventional contributor surface: CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, CHANGELOG.md, a Guardfile, rubocop with a todo file, and check_for_uncommitted_files.sh. Appraisals sits next to a gemfiles/ directory, and there is a separate LintingGemfile with its own lock file, so the repository carries more than one dependency set. The last push was on 2026-07-31, so the code is still moving even though the release tags are not.

Editorial conclusion

Stay on React-Rails if your application already renders React through it and a migration would touch more files than the improvement is worth, and pin your version from the gemspec rather than from the GitHub release list, which stops at 2.6.2. Start on React on Rails if you are building something new, because the comparison in the README points at TypeScript in the Node package and work on React Server Components. Verify first which asset pipeline you have, since Shakapacker v7, Propshaft and Sprockets 3.x and 4.x are separate documented paths.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. reactjs/react-rails on GitHub
4. README
5. Releases