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 app. For new apps, start with
npx create-react-on-rails-app my-app; it defaults to React on Rails Pro because Pro is where React 19.2 feature support lives. For adding React to an existing app, use Install into an Existing Rails App instead.
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:
gem install rails)bin/dev)💡 Already have a Rails app? Use Install into an Existing Rails App.
Create a new React on Rails app:
npx create-react-on-rails-app my-app
cd my-app
bin/rails db:prepare
New apps use React on Rails Pro by default because Pro is where React 19.2 feature support lives. Use
--template javascript for JavaScript, --tailwind to style the generated example, --rsc for the
React Server Components example, or --standard only when you intentionally want an
open-source-only scaffold.
To try the latest release candidate, use:
npx create-react-on-rails-app@rc my-app
Take a look at the generated app history when you want to understand what the CLI changed:
git log --oneline --reverse
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 bundler dev server:
./bin/dev
This starts both:
http://localhost:3000Open your browser and navigate to:
http://localhost:3000
The generated home page links to the example pages and the files React on Rails created for you.
🎉 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)<h3>Hello, {name}!</h3> to <h3>Hello from React on Rails Pro, {name}!</h3>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.client.tsx
Add this content to SimpleCounter.client.tsx:
import React, { useState } from 'react';
interface SimpleCounterProps {
initialCount?: number;
}
const SimpleCounter = ({ initialCount = 0 }: SimpleCounterProps) => {
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 a Rails view, such as the generated home page at app/views/home/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 }) %>
The generated layouts already include these tags. If you add React on Rails to another layout, make sure the <head> section includes:
<%= 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 Features Start at React on Rails Pro for the canonical route map, or go directly to Pro pricing and sign up. From there you can jump to React Server Components, streaming SSR, fragment caching, and the Node renderer. ShakaCode Trust-Based Commercial Licensing: no token is required for development, test, CI/CD, or staging. :::
# Start development servers
./bin/dev
# Generate React on Rails files with TypeScript support
bin/rails generate react_on_rails:install --typescript
# Add a new component: create a file under a `ror_components` directory, then
# render it with `<%= react_component("MyComponent") %>` in any Rails view.
# With auto-bundling there's no generator and no manual registration step.
mkdir -p app/javascript/src/MyComponent/ror_components
touch app/javascript/src/MyComponent/ror_components/MyComponent.tsx
# 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.