docs/oss/getting-started/quick-start.md
Get your first React component running in Rails in 15 minutes
[!NOTE] Summary for AI agents: Use this page when the user wants the shortest path to a working React on Rails install in a new Rails app. For adding React to an existing app, use Install into an Existing Rails App instead. For a guided walkthrough, use the Tutorial.
This guide will have you rendering React components in your Rails app as quickly as possible. We'll skip the theory for now and focus on getting something working.
Before starting, make sure you have:
bin/dev)💡 Don't have a Rails app? Run
rails new my_react_appfirst.
Add the React on Rails gem and run its installer:
# Add the gem
bundle add react_on_rails --strict
# Optional but recommended: commit or stash first so generated files show as a clean diff
# git add . && git commit -m "Prepare for React on Rails install"
# Run the installer for TypeScript
bin/rails generate react_on_rails:install --typescript
# Optional: Use Rspack for faster builds
# bin/rails generate react_on_rails:install --typescript --rspack
# For JavaScript instead of TypeScript, omit --typescript
# bin/rails generate react_on_rails:install
If the generator reports dependency-install warnings (for example, JavaScript dependencies installation failed ...), run your package manager install and compile once before moving on:
npm install
# or: pnpm install
# or: yarn install
# or: bun install
bundle exec rails shakapacker:compile
Take a look at the files created by the generator.
.tsx for TypeScript, .jsx for JavaScript)client/💡 Performance Tip: Add the
--rspackflag for significantly faster builds (~20x improvement). You can also switch bundlers later withbin/switch-bundler rspack.Note on
bin/switch-bundler: This utility safely switches between webpack and rspack by updatingshakapacker.ymland managing dependencies. However, it does not modify custom webpack configuration code. If you have custom webpack plugins or loaders, you may need to update those manually to work with rspack. See Rspack documentation for details on unified configuration patterns.
Note: Ensure you have
overmindorforemaninstalled to runbin/dev.
- overmind:
brew install overmind(macOS) or see installation guide- foreman:
gem install foreman(install globally, not in your project bundle - details)
Start both Rails and the Webpack dev server:
./bin/dev
This starts both:
http://localhost:3000Open your browser and navigate to:
http://localhost:3000/hello_world
You should see a page with a React component saying "Hello World"!
🎉 Congratulations! You have React running in your Rails app.
Let's make a quick change to see hot reloading in action:
app/javascript/src/HelloWorld/ror_components/HelloWorld.client.tsx)Now let's add a React component to one of your existing Rails views:
# Create a new component directory
mkdir -p app/javascript/src/SimpleCounter/ror_components
# Create the component file
touch app/javascript/src/SimpleCounter/ror_components/SimpleCounter.tsx
Add this content to SimpleCounter.tsx:
import React, { useState } from 'react';
const SimpleCounter = ({ initialCount = 0 }) => {
const [count, setCount] = useState(initialCount);
return (
<div style={{ padding: '20px', border: '1px solid #ccc' }}>
<h3>React Counter</h3>
<p>
Current count: <strong>{count}</strong>
</p>
<button onClick={() => setCount(count + 1)}>Increment</button>
<button onClick={() => setCount(count - 1)}>Decrement</button>
<button onClick={() => setCount(0)}>Reset</button>
</div>
);
};
export default SimpleCounter;
With React on Rails auto-bundling, you don't need manual registration! Just add this to any Rails view (like app/views/application/index.html.erb):
<h1>My Rails App</h1>
<p>Here's a React component embedded in this Rails view:</p>
<%= react_component("SimpleCounter", { initialCount: 5 }, { auto_load_bundle: true }) %>
Note, your layout needs to include this in the <head> section:
<%= stylesheet_pack_tag %>
<%= javascript_pack_tag %>
That's it! React on Rails will automatically:
ror_components (configurable)🚀 Performance Tip: Auto-bundling automatically optimizes your JavaScript delivery by only loading components used on each page, significantly reducing initial bundle size compared to manual bundling.
Restart your server and visit the page - you should see your interactive counter!
In 15 minutes, you've:
Now that you have React on Rails working, here's what to explore next:
react_component:::tip Pro Upgrade Start at React on Rails Pro for the canonical route map. From there you can jump to the upgrade guide, React Server Components, streaming SSR, fragment caching, and the Node renderer. Free to evaluate — no license needed for development. :::
# Start development servers
./bin/dev
# Generate React on Rails files with TypeScript support
bin/rails generate react_on_rails:install --typescript
# Create a new component
bin/rails generate react_on_rails:component MyComponent
# Build for production (use your package manager)
pnpm run build # or: yarn run build, npm run build
app/javascript/src/[ComponentName]/ror_components/config/initializers/react_on_rails.rbconfig/shakapacker.yml🎉 Welcome to React on Rails! You're now ready to build amazing full-stack applications with the best of both Rails and React.