Skip to content

Commit 60d3c68

Browse files
ihabadhamihabadham
committed
Create introduction.md and remove redundant overview
- Add docs/introduction.md as unified homepage - Explains what React on Rails is and why to use it - Clear when to use / when not to use decision guide - Three clear paths: Quick Start, Installation, Tutorial - Built from actual docs (overview, doctrine, system requirements) - Added community stat (thousands of production sites) - Delete docs/core-concepts/react-on-rails-overview.md - Content consolidated into introduction.md - Outdated prerequisites (Rails >=5 vs current Rails 7+) - Creates confusion with two similar entry points - Update links to overview.md: - docs/home.md: Overview → Introduction - docs/misc/doctrine.md: Overview → Introduction Solves Problem 1.2 (Multiple Conflicting Entry Points) from docs improvement plan. Next: Handle remaining entry point files (home.md, README.md, getting-started.md).
1 parent a87256e commit 60d3c68

File tree

4 files changed

+133
-32
lines changed

4 files changed

+133
-32
lines changed

‎docs/core-concepts/react-on-rails-overview.md‎

Lines changed: 0 additions & 30 deletions
This file was deleted.

‎docs/home.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
## Details
44

5-
1. [Overview](./core-concepts/react-on-rails-overview.md)
5+
1. [Introduction](./introduction.md)
66
1. [Getting Started](./getting-started.md)
77
1. [How React on Rails Works](./core-concepts/how-react-on-rails-works.md)
88
1. [Webpack Configuration](./core-concepts/webpack-configuration.md)

‎docs/introduction.md‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
# React on Rails
2+
3+
> **Integrate React components seamlessly into your Rails application with server-side rendering, hot reloading, and more.**
4+
5+
React on Rails integrates Rails with React, providing a high-performance framework for server-side rendering (SSR) and seamless component integration via [Shakapacker](https://github.com/shakacode/shakapacker).
6+
7+
## What is React on Rails?
8+
9+
React on Rails bridges the gap between Ruby on Rails and React, allowing you to:
10+
11+
- Render React components directly from Rails views with the `react_component` helper
12+
- Pass props from Rails to React without building a separate API
13+
- Enable server-side rendering for better SEO and initial page load performance
14+
- Use hot module replacement (HMR) for fast development iterations
15+
- Integrate with Redux, React Router, and the modern React ecosystem
16+
17+
Unlike a separate SPA approach, React on Rails lets you leverage Rails conventions while progressively enhancing your UI with React components.
18+
19+
## Why React on Rails?
20+
21+
**Key Benefits:**
22+
23+
1. **No Separate API Required** - Pass data directly from Rails views to React components
24+
2. **Server-Side Rendering** - Built-in SSR support for SEO and performance (not available in Shakapacker alone)
25+
3. **Rails Integration** - Works with Rails conventions, asset pipeline, and existing apps
26+
4. **Modern Tooling** - Full Webpack, HMR, and NPM ecosystem support via Shakapacker
27+
5. **Progressive Enhancement** - Mix Rails views with React components on the same page
28+
29+
## When to Use React on Rails
30+
31+
**Choose React on Rails if:**
32+
33+
- ✅ You have an existing Rails application
34+
- ✅ You want React's component model and ecosystem
35+
- ✅ You need server-side rendering for SEO or performance
36+
- ✅ You want to avoid building and maintaining a separate API
37+
- ✅ You value Rails conventions and want tight integration
38+
39+
**Consider alternatives if:**
40+
41+
- ❌ You're building a standalone SPA with a separate API backend
42+
43+
## Getting Started
44+
45+
Choose your path based on your situation:
46+
47+
### 🚀 New to React on Rails?
48+
49+
**[15-Minute Quick Start →](./getting-started/quick-start.md)**
50+
51+
Get your first component running in minutes. Perfect for exploring React on Rails quickly.
52+
53+
### 📦 Adding to an Existing Rails App?
54+
55+
**[Installation Guide →](./getting-started/installation-into-an-existing-rails-app.md)**
56+
57+
Detailed integration instructions for existing Rails applications with Shakapacker.
58+
59+
### 📚 Want a Comprehensive Tutorial?
60+
61+
**[Complete Tutorial →](./getting-started/tutorial.md)**
62+
63+
Step-by-step walkthrough building a full app with Redux, routing, and deployment.
64+
65+
### 👀 Learn by Example?
66+
67+
- **[Spec/Dummy App](https://github.com/shakacode/react_on_rails/tree/master/spec/dummy)** - Simple example in this repo
68+
- **[Live Demo with Source](https://github.com/shakacode/react-webpack-rails-tutorial)** - Full production app at [reactrails.com](https://reactrails.com)
69+
70+
## Popular Use Cases
71+
72+
Find guidance for your specific scenario:
73+
74+
| I want to... | Go here |
75+
| ----------------------------------- | -------------------------------------------------------------------------------------- |
76+
| **Add React to existing Rails app** | [Installation Guide](./getting-started/installation-into-an-existing-rails-app.md) |
77+
| **Enable server-side rendering** | [SSR Guide](./core-concepts/react-server-rendering.md) |
78+
| **Set up hot reloading** | [HMR Setup](./building-features/hmr-and-hot-reloading-with-the-webpack-dev-server.md) |
79+
| **Use Redux with Rails** | [Redux Integration](./building-features/react-and-redux.md) |
80+
| **Deploy to production** | [Deployment Guide](./deployment/deployment.md) |
81+
| **Troubleshoot issues** | [Troubleshooting](./deployment/troubleshooting.md) |
82+
83+
## Core Concepts
84+
85+
Before building features, understand these fundamentals:
86+
87+
- **[How React on Rails Works](./core-concepts/how-react-on-rails-works.md)** - Architecture overview
88+
- **[Auto-Bundling](./core-concepts/auto-bundling-file-system-based-automated-bundle-generation.md)** - Automatic component registration and bundle generation
89+
- **[Client vs Server Rendering](./core-concepts/client-vs-server-rendering.md)** - When to use each
90+
- **[Webpack Configuration](./core-concepts/webpack-configuration.md)** - Customizing your build
91+
92+
## Philosophy
93+
94+
React on Rails follows the **[Rails Doctrine](https://rubyonrails.org/doctrine)** and extends it to modern JavaScript development:
95+
96+
- **Convention over Configuration** - Sensible defaults for JavaScript tooling with Rails
97+
- **Optimize for Programmer Happiness** - Hot reloading, ES6+, CSS modules, NPM ecosystem
98+
- **Value Integrated Systems** - Tight Rails integration beats separate microservices for most apps
99+
100+
Read the full **[React on Rails Doctrine](./misc/doctrine.md)** for our design philosophy.
101+
102+
## System Requirements
103+
104+
- **Rails 7+** (Rails 5.2+ supported)
105+
- **Ruby 3.0+**
106+
- **Node.js 18+**
107+
- **Shakapacker 6+** (7+ recommended for React on Rails v16)
108+
109+
## Need Help?
110+
111+
### Community Support
112+
113+
- **Active Community** - [Thousands of production sites use React on Rails](https://publicwww.com/websites/%22react-on-rails%22++-undeveloped.com+depth%3Aall/)
114+
- **[React on Rails Discussions](https://github.com/shakacode/react_on_rails/discussions)** - Ask questions and share knowledge
115+
- **[React + Rails Slack](https://reactrails.slack.com)** - Real-time community help
116+
- **[GitHub Issues](https://github.com/shakacode/react_on_rails/issues)** - Report bugs
117+
118+
### Professional Support
119+
120+
- **[React on Rails Pro](https://www.shakacode.com/react-on-rails-pro/)** - Advanced features (React Server Components, Suspense SSR, streaming)
121+
- **[ShakaCode Consulting](mailto:react_on_rails@shakacode.com)** - Expert help with React on Rails projects
122+
123+
## External Resources
124+
125+
- **[Shakapacker Documentation](https://github.com/shakacode/shakapacker)** - Webpack integration for Rails (required)
126+
- **[React Documentation](https://react.dev)** - Official React documentation
127+
- **[Rails Guides](https://guides.rubyonrails.org)** - Ruby on Rails documentation
128+
129+
---
130+
131+
**Ready to start?** Pick your path above and let's build something great! 🚀

‎docs/misc/doctrine.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ By Justin Gordon, January 26, 2016
44

55
This document is an extension and complement to [The Rails Doctrine](http://rubyonrails.org/doctrine/). If you haven't read that document, I suggest you do so first.
66

7-
To paraphrase the [React on Rails Overview](../core-concepts/react-on-rails-overview.md), the project objective is to provide an opinionated and optimal framework for integrating **Ruby on Rails** with modern JavaScript tooling and libraries.
7+
To paraphrase the [React on Rails Introduction](../introduction.md), the project objective is to provide an opinionated and optimal framework for integrating **Ruby on Rails** with modern JavaScript tooling and libraries.
88

99
When considering what goes into **react_on_rails**, we ask ourselves, is the functionality related to the intersection of using Rails and with modern JavaScript? A good example is view helper integration of React components on a Rails view. If the answer is yes, then the functionality belongs right here.
1010

0 commit comments

Comments
 (0)