Skip to main content
Edit

Install into an Existing Rails App

Use this path when you already have a Rails application and want React on Rails to generate the missing integration files for you.

note

Summary for AI agents: Use this page when the user has an existing Rails app and wants to add React. For new apps, use Quick Start. If the app still uses Webpacker, expect a two-step migration (Webpacker → Shakapacker → React on Rails). Rails 7.0+ is required (Ruby 3.3+ is incompatible with older Rails).

Preflight​

  • Rails 7.0+ is required (Ruby 3.3+ is incompatible with Rails < 7.0).
  • If your app still uses webpacker, expect this to be a two-step migration: move to shakapacker, then install React on Rails.
  • If your app is Rails 5 API-only, first convert it to a standard Rails app.
  • Commit or stash your current work if you want the generated diff to be easier to review. The generator updates files like bin/dev, config/shakapacker.yml, routes, initializers, and sample views/controllers.

1. Add the gems​

bundle add react_on_rails --strict
SHAKAPACKER_VERSION="$(bundle exec ruby -rreact_on_rails -e 'print ReactOnRails::PackerUtils.shakapacker_version')"
bundle add shakapacker --version="${SHAKAPACKER_VERSION}" --strict

Adding React on Rails first lets Bundler select a compatible Shakapacker release. Pinning that resolved version when adding Shakapacker directly prevents an older globally installed gem from replacing it.

React on Rails attempts to install the matching react-on-rails JavaScript package during the generator run. In some existing apps, dependency installation can fail (or required package-manager tooling may be unavailable), and the generator prints manual install commands. Run those commands before starting the app.

Optional: pin exact gem and npm versions yourself​

If you manage versions manually, keep the Ruby gem and npm package on the same release. Pre-release gems use dots while npm uses hyphens. Replace VERSION below with the latest version from the CHANGELOG.

gem "react_on_rails", "VERSION"
npm install react-on-rails@VERSION --save-exact
# or: yarn add react-on-rails@VERSION --exact
# or: pnpm add react-on-rails@VERSION --save-exact
# or: bun add react-on-rails@VERSION --exact

2. Run the generator​

bundle exec rails generate react_on_rails:install --typescript

TypeScript is the recommended default for new integrations. If you want JavaScript instead, omit --typescript.

When you run the generator in an interactive terminal without choosing a product mode, it asks whether to enable React on Rails Pro. Press Enter or answer y to include the Node Renderer and the Pro foundation for streaming SSR and React Server Components. Pro is free for evaluation; production use requires a subscription. See the Pro upgrade guide for licensing and setup details.

The prompt never appears in CI, redirected-input scripts, or other noninteractive sessions; those runs preserve the existing open-source-only default. Pass --pro or --rsc to select Pro without a prompt. Pass --no-pro, --no-rsc, or --standard-only to select the open-source setup explicitly and suppress the prompt. Because --standard-only is an explicit open-source choice, the generator rejects combining it with --pro or --rsc.

For generator options such as --rspack, --pro, or --rsc, see the generator details.

If the generator reports dependency-install warnings (for example, JavaScript dependencies installation failed ... followed by Please run manually:), run your package manager install and then compile once before starting the app:

# pick one package manager
npm install
# or: pnpm install
# or: yarn install
# or: bun install

bundle exec rails shakapacker:compile

If you are migrating from react-rails, also run the compatibility checklist in Migrate from react-rails.

3. Start the app​

Ensure that you have overmind or foreman installed so bin/dev can run both Rails and the asset watcher.

bin/rails db:prepare
./bin/dev

If port 3000 is already in use, set an explicit port:

PORT=3001 ./bin/dev

Visit the app on the port you used. By default that is http://localhost:3000/hello_world.

What the generator changes​

The install generator typically adds or updates:

  • config/initializers/react_on_rails.rb
  • config/shakapacker.yml
  • bin/dev
  • app/javascript/packs/server-bundle.js
  • example HelloWorld component files
  • a sample route, controller, and view

Review these changes before adapting them to your actual application structure.

What's Next?​