Skip to main content

Migrate From react-rails

This migration is easiest when the app is already on a modern Rails + Shakapacker baseline.

Preflight​

Before swapping gems, check these first:

  1. Webpacker vs Shakapacker: if the app still uses webpacker, migrate to shakapacker first.
  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.

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:

bundle _2.3.26_ lock --update
bundle _2.3.26_ install

  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 installs node dependencies and also creates sample React component, Rails view/controller, and updates config/routes.rb.

  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:

      - <%= react_component('Post', { title: 'New Post' }, { prerender: true }) %>
      + <%= react_component('Post', { props: { title: 'New Post' }, prerender: true }) %>

You can also check react-rails-to-react-on-rails branch on react-rails example app for an example of migration from react-rails v3 to react_on_rails v13.4.

Practical checklist for Webpacker-era apps​

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