Skip to main content
Edit

Quick Start: npx create-react-on-rails-app

The fastest way to start a new React on Rails project. One command creates a fully configured Rails + React application with TypeScript, server-side rendering, hot module replacement, and, optionally, React Server Components (RSC).

Quick Start​

npx create-react-on-rails-app my-app
cd my-app
bin/rails db:prepare
bin/dev

On fresh apps, bin/dev will try to open http://localhost:3000 the first time the app boots successfully. The generated home page links to the example pages, the key files React on Rails created for you, and follow-on docs for OSS vs Pro, React Server Components, and the marketplace demo. The generated app also includes a step-by-step git history so you can inspect each major scaffold phase with git log --oneline --reverse.

This creates a TypeScript app by default. For JavaScript, use --template javascript. For React on Rails Pro without RSC, add --pro. The CLI installs react_on_rails_pro automatically and keeps the generated SSR example at /hello_world. For React Server Components (RSC), add --rsc. The CLI installs react_on_rails_pro automatically and the home page links to /hello_server. --rsc requires react_on_rails_pro to be installable in your environment (Pro setup docs). --pro and --rsc support both JavaScript (.jsx) and TypeScript (.tsx) templates.

Options​

# JavaScript instead of TypeScript
npx create-react-on-rails-app my-app --template javascript

# Use Rspack for ~20x faster builds
npx create-react-on-rails-app my-app --rspack

# Generate React on Rails Pro setup
npx create-react-on-rails-app my-app --pro

# Generate React Server Components setup (includes react_on_rails_pro)
npx create-react-on-rails-app my-app --rsc

# Specify package manager
npx create-react-on-rails-app my-app --package-manager pnpm

# Combine options
npx create-react-on-rails-app my-app --rspack --package-manager pnpm

# Combine RSC with Rspack
npx create-react-on-rails-app my-app --rspack --rsc

All Options​

OptionDescriptionDefault
-t, --template <type>javascript or typescripttypescript
--rspackUse Rspack instead of Webpack (~20x faster)false
--proEnable React on Rails Pro (requires react_on_rails_pro)false
--rscEnable React Server Components (requires react_on_rails_pro)false
-p, --package-manager <pm>npm or pnpmauto-detected

What It Does​

The CLI runs these steps automatically:

  1. Creates a Rails app (rails new with PostgreSQL, no default JS)
  2. Adds required gems (bundle add react_on_rails, plus react_on_rails_pro for --pro / --rsc)
  3. Runs the generator (rails generate react_on_rails:install with your selected flags)
  4. Creates educational git commits for each logical setup step

After completion, you get:

  • A Rails 7+ app with PostgreSQL
  • Shakapacker configured with Webpack (or Rspack) and HMR
  • A working HelloWorld React component (TypeScript by default)
  • A generated home page at / with links to the example pages, important project files, and Pro/RSC learning resources
  • A teaching-friendly git history that separates Rails creation, gem installation, generator output, and pnpm normalization
  • Standard Rails git scaffold files (.gitignore and .gitattributes) preserved in the generated app
  • Optional Pro setup (--pro) with Pro Node renderer wiring and the generated /hello_world example
  • Optional RSC setup (--rsc) with HelloServer route and Pro Node renderer wiring
  • Server-side rendering ready
  • Development scripts (bin/dev with hot reloading and first-run browser open)

Prerequisites​

The CLI checks for these before starting:

  • Node.js 18+
  • Ruby 3.0+
  • Rails 7.0+ (gem install rails)
  • git
  • npm or pnpm
  • PostgreSQL running locally (needed at bin/rails db:prepare, not validated by the CLI)

If any of the first five are missing, you'll get a clear error message with installation instructions.

Adding to an Existing Rails App​

If you already have a Rails app, use the generator directly instead:

bundle add react_on_rails --strict
rails generate react_on_rails:install --typescript  # TypeScript (recommended)
rails generate react_on_rails:install               # JavaScript

See Installation into an Existing Rails App for details.

What's Next?​

Now that you have React on Rails running, here are ways to level up: