Skip to content

Commit a0b336b

Browse files
justin808justin808
authored
📚 Comprehensive documentation improvements for enhanced developer experience (#1813)
This PR consolidates and enhances React on Rails documentation with: **Major Documentation Updates:** - New 15-minute Quick Start Guide with modern auto-bundling patterns - Comprehensive documentation hub (docs/README.md) with clear user journey paths - Enhanced getting-started guide with prominent version requirements - Updated AI agent instructions with proper installation order **Version Requirements Standardization:** - Reconciled version specs across all docs to match gemspec exactly - Shakapacker 6+ (7+ recommended) instead of conflicting requirements - Ruby 3.0+ (required) - removed incorrect "2.7+ supported" references - Consistent Rails 5.2+ and Node.js 18+ requirements throughout **Link Infrastructure Fixes:** - Fixed 27+ broken internal links across documentation - Updated all links to point to existing files instead of non-existent ones - Fixed image paths and external URLs (Storybook domain update) - Corrected anchor links in troubleshooting guide **Content Modernization:** - Emphasized auto-bundling over manual registration throughout - Added security note about automatic props sanitization - Updated examples to use current best practices - Organized planning documents into proper subfolder structure **Technical Improvements:** - All files properly formatted with trailing newlines - Standardized code block language tags - Fixed malformed markdown syntax issues - Enhanced visual hierarchy and navigation This creates a cohesive, accurate, and navigable documentation experience that properly reflects React on Rails 16.0+ capabilities and requirements.
1 parent 7b40c80 commit a0b336b

23 files changed

+1246
-124
lines changed

‎AI_AGENT_INSTRUCTIONS.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# 🤖 AI Agent Instructions: React on Rails Setup
2+
3+
_Super concise, copy-paste instructions for AI agents to set up React on Rails in common scenarios._
4+
5+
## 🔍 **Before Starting: Check Current Versions**
6+
7+
```bash
8+
# Get latest available versions (recommended approach)
9+
gem search react_on_rails --remote
10+
```
11+
12+
Install and update gem and npm package using strict option.
13+
14+
---
15+
16+
## 🆕 Scenario 1: New Rails App with React on Rails
17+
18+
```bash
19+
# Create new Rails app
20+
rails new myapp --skip-javascript --database=postgresql
21+
cd myapp
22+
23+
# Use latest version
24+
bundle add react_on_rails --strict
25+
26+
bin/rails generate react_on_rails:install
27+
28+
# Accept change to bin/dev
29+
30+
# Start development servers
31+
bin/dev
32+
```
33+
34+
**✅ Success Check:** Visit `http://localhost:3000/hello_world` → Should see "Hello World" from React
35+
36+
---
37+
38+
## 🔄 Scenario 2: Add React on Rails to Existing Rails App
39+
40+
```bash
41+
cd /path/to/existing/app
42+
# Use latest version
43+
bundle add react_on_rails --strict
44+
45+
bin/rails generate react_on_rails:install
46+
47+
# Accept change to bin/dev
48+
49+
# Start development servers
50+
bin/dev
51+
# Navigate to existing Rails app root
52+
53+
# Start development
54+
bin/dev
55+
```
56+
57+
---
58+
59+
## 🛠️ Common Troubleshooting Commands
60+
61+
- Always run `bin/dev` to test setup, and check browser console for any JavaScript errors
62+
- `bin/dev kill` stops other conflicting processes
63+
- `bin/rake react_on_rails:doctor` for helpful information

‎README.md‎

Lines changed: 28 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@
1616
[![Build Rspec Tests](https://github.com/shakacode/react_on_rails/actions/workflows/rspec-package-specs.yml/badge.svg)](https://github.com/shakacode/react_on_rails/actions/workflows/rspec-package-specs.yml)
1717
[![Linting](https://github.com/shakacode/react_on_rails/actions/workflows/lint-js-and-ruby.yml/badge.svg)](https://github.com/shakacode/react_on_rails/actions/workflows/lint-js-and-ruby.yml)
1818

19-
# News
19+
# ⚡ What's New
2020

2121
**🚀 React on Rails v16.0 Released!** Major modernization with ESM support, enhanced React Server Components, and streamlined configuration.
2222

@@ -31,11 +31,13 @@
3131

3232
_These are the docs for React on Rails 16. To see the older docs and code: [v14](https://github.com/shakacode/react_on_rails/tree/14.0.0), [v13](https://github.com/shakacode/react_on_rails/tree/13.4.0), [v12](https://github.com/shakacode/react_on_rails/tree/12.6.0), and [v11](https://github.com/shakacode/react_on_rails/tree/11.3.0)._
3333

34-
# About
34+
# 🎯 About React on Rails
3535

36-
React on Rails integrates Rails with (server rendering of) [React](https://github.com/facebook/react).
36+
**Seamlessly integrate React components into your Rails application** with server-side rendering, hot reloading, and automatic bundle optimization.
3737

38-
This project is maintained by [ShakaCode](https://www.shakacode.com).
38+
> **"The easiest way to add React to Rails"** - Thousands of developers rely on React on Rails for production applications.
39+
40+
This project is maintained by [ShakaCode](https://www.shakacode.com) with ❤️ from the Rails and React communities.
3941

4042
## ShakaCode Upgrade Support
4143

@@ -93,30 +95,34 @@ We did this for Popmenu, [lowering Heroku costs 20-25% while getting a 73% decre
9395

9496
If you're interested, read more about [React on Rails Pro](https://www.shakacode.com/react-on-rails-pro/) and [book a call](https://meetings.hubspot.com/justingordon/30-minute-consultation).
9597

96-
# Documentation
98+
# 📚 Quick Start
99+
100+
**New to React on Rails?** Get up and running in minutes:
97101

98-
See the documentation at **[shakacode.com/react-on-rails/docs](https://www.shakacode.com/react-on-rails/docs/)** and [React on Rails Pro](https://www.shakacode.com/react-on-rails-pro/).
102+
🚀 **[15-Minute Quick Start](https://www.shakacode.com/react-on-rails/docs/quick-start/)** - Your first React component
103+
📖 **[Complete Documentation](https://www.shakacode.com/react-on-rails/docs/)** - Comprehensive guides and API reference
104+
🎮 **[Live Demo](https://reactrails.com)** - See it in action with [source code](https://github.com/shakacode/react-webpack-rails-tutorial)
99105

100106
## Project Objective
101107

102108
To provide a high-performance framework for integrating Ruby on Rails with React, especially regarding React Server-Side Rendering for better SEO and improved performance.
103109

104-
## Features and Why React on Rails?
105-
106-
Given that `shakacode/shakapacker` gem already provides basic React integration, why would you use "React on Rails"?
107-
108-
1. **Modern ESM-only package** with optimized tree-shaking for smaller bundle sizes and better performance.
109-
1. **Advanced loading strategies** with `sync`, `async`, and `defer` options for optimal performance based on your needs.
110-
1. **Automatic configuration** of what bundles are added to the page based on what React components are on the page. This results in faster browser loading time via smaller bundle sizes.
111-
1. **Keep up with the latest changes** in different versions of React. React 18+ is fully supported with enhanced React Server Components.
112-
1. **Easy prop passing** directly from your Rails view to your React components rather than having your Rails view load and then make a separate request to your API.
113-
Tight integration with [shakapacker](https://github.com/shakacode/shakapacker).
114-
1. **Server-Side Rendering (SSR)** with enhanced React Server Components support, often used for SEO crawler indexing and UX performance.
115-
1. **[Automated optimized entry-point creation and bundle inclusion](https://www.shakacode.com/react-on-rails/docs/guides/file-system-based-automated-bundle-generation/)** when placing a component on a page. With this feature, you no longer need to configure `javascript_pack_tags` and `stylesheet_pack_tags` on your layouts based on what's shown. "It just works!"
116-
1. **[Redux](https://redux.js.org/) and [React Router](https://reactrouter.com/) integration** with server-side-rendering.
117-
1. **[Internationalization (I18n) and (localization)](https://www.shakacode.com/react-on-rails/docs/guides/i18n)** support.
118-
1. **Supportive community**. This [web search shows how live public sites are using React on Rails](https://publicwww.com/websites/%22react-on-rails%22++-undeveloped.com+depth%3Aall/).
119-
1. **[ReScript Support](https://github.com/shakacode/rescript-react-on-rails-example)**.
110+
## ✨ Why React on Rails?
111+
112+
| Feature | Benefit |
113+
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
114+
| 🎯 **Smart Bundle Loading** | [Automated bundle optimization](./docs/guides/auto-bundling-file-system-based-automated-bundle-generation.md) based on components used - no more manual `javascript_pack_tags` configuration |
115+
| ⚡ **Server-Side Rendering** | Enhanced React Server Components support for better SEO and UX performance |
116+
| 🚀 **Advanced Loading** | `sync`, `async`, and `defer` options for optimal performance based on your needs |
117+
| 🔥 **Hot Module Replacement** | Instant feedback during development with tight [Shakapacker](https://github.com/shakacode/shakapacker) integration |
118+
| 📦 **Easy Props Passing** | Direct Rails → React data flow without separate API calls |
119+
| 🗺️ **Router Integration** | [React Router](https://reactrouter.com/) with SSR support |
120+
| 🏪 **State Management** | [Redux](https://redux.js.org/) integration with server-side rendering |
121+
| 🌍 **Internationalization** | [I18n and localization support](https://www.shakacode.com/react-on-rails/docs/guides/i18n) for global apps |
122+
| 🎨 **Modern React** | React 18+ with enhanced React Server Components and latest patterns |
123+
| 🦄 **ReScript Support** | [ReScript integration](https://github.com/shakacode/rescript-react-on-rails-example) for type-safe development |
124+
125+
> **Trusted by thousands** - See [real production sites](https://publicwww.com/websites/%22react-on-rails%22++-undeveloped.com+depth%3Aall/) using React on Rails
120126
121127
See [Rails/Shakapacker React Integration Options](https://www.shakacode.com/react-on-rails/docs/guides/rails-webpacker-react-integration-options) for comparisons to other gems.
122128

‎docs/README.md‎

Lines changed: 172 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
1+
# React on Rails Documentation
2+
3+
> **Integrate React components seamlessly into your Rails application with server-side rendering, hot reloading, and more.**
4+
5+
## 🚀 Quick Start
6+
7+
New to React on Rails? Start here for the fastest path to success:
8+
9+
**→ [15-Minute Quick Start Guide](./quick-start/README.md)**
10+
11+
Already have Rails + Shakapacker? **→ [Add to existing app guide](./guides/installation-into-an-existing-rails-app.md)**
12+
13+
## 📚 Learning Paths
14+
15+
Choose your journey based on your experience level:
16+
17+
### 🔰 **Beginner Path**
18+
19+
Perfect if you're new to React on Rails
20+
21+
1. **[Quick Start](./quick-start/README.md)** - Get your first component running
22+
2. **[Core Concepts](./getting-started.md)** - Understand the basics
23+
3. **[Tutorial](./guides/tutorial.md)** - Build something useful
24+
25+
### ⚡ **Experienced Developer Path**
26+
27+
Jump to what you need
28+
29+
- **[Installation Guide](./guides/installation-into-an-existing-rails-app.md)** - Detailed setup
30+
- **[API Reference](./api/README.md)** - Quick lookup
31+
- **[Advanced Features](./guides/advanced/README.md)** - SSR, Redux, Router
32+
33+
### 🏗️ **Migrating from Other Solutions**
34+
35+
- **[From react-rails](./additional-details/migrating-from-react-rails.md)** - Switch from the react-rails gem
36+
- **[Upgrading React on Rails](./guides/upgrading-react-on-rails.md)** - Version upgrade guide
37+
38+
## 🎯 Popular Use Cases
39+
40+
Find guidance for your specific scenario:
41+
42+
| I want to... | Go here |
43+
| ----------------------------------- | -------------------------------------------------------------------------- |
44+
| **Add React to existing Rails app** | [Installation Guide](./guides/installation-into-an-existing-rails-app.md) |
45+
| **Enable server-side rendering** | [SSR Guide](./guides/react-server-rendering.md) |
46+
| **Set up hot reloading** | [HMR Setup](./guides/hmr-and-hot-reloading-with-the-webpack-dev-server.md) |
47+
| **Use Redux with Rails** | [Redux Integration](./javascript/react-and-redux.md) |
48+
| **Deploy to production** | [Deployment Guide](./guides/deployment.md) |
49+
| **Troubleshoot issues** | [Troubleshooting](./troubleshooting/README.md) |
50+
51+
## 📖 Complete Documentation
52+
53+
### Core Guides
54+
55+
- **[Getting Started](./getting-started.md)** - Installation and basic setup
56+
- **[Tutorial](./guides/tutorial.md)** - Complete walkthrough with examples
57+
- **[Configuration](./guides/configuration.md)** - All configuration options
58+
- **[View Helpers](./api/view-helpers-api.md)** - Using `react_component` method
59+
60+
### Features
61+
62+
- **[Server-Side Rendering](./guides/react-server-rendering.md)** - SSR setup and optimization
63+
- **[Auto-Bundling](./guides/auto-bundling-file-system-based-automated-bundle-generation.md)** - Automatic bundle generation
64+
- **[Redux Integration](./javascript/react-and-redux.md)** - State management with Redux
65+
- **[React Router](./javascript/react-router.md)** - Client-side routing
66+
- **[Internationalization](./guides/i18n.md)** - I18n support
67+
68+
### Development
69+
70+
- **[Hot Module Replacement](./guides/hmr-and-hot-reloading-with-the-webpack-dev-server.md)** - Fast development workflow
71+
- **[Testing](./guides/rspec-configuration.md)** - Testing React components
72+
- **[Debugging](./javascript/troubleshooting-build-errors.md)** - Common debugging techniques
73+
74+
### Deployment & Performance
75+
76+
- **[Deployment](./guides/deployment.md)** - Production deployment guide
77+
- **[Performance](./guides/webpack-configuration.md)** - Optimization techniques
78+
- **[Bundle Optimization](./guides/webpack-configuration.md)** - Reduce bundle size
79+
80+
## 🆘 Need Help?
81+
82+
### Quick Solutions
83+
84+
- **[Troubleshooting Guide](./troubleshooting/README.md)** - Common issues and solutions
85+
- **[FAQ](./troubleshooting/README.md)** - Frequently asked questions
86+
- **[Error Messages](./javascript/troubleshooting-build-errors.md)** - Decode error messages
87+
88+
### Community Support
89+
90+
- **[React + Rails Slack](https://reactrails.slack.com)** - Real-time community help
91+
- **[GitHub Discussions](https://github.com/shakacode/react_on_rails/discussions)** - Ask questions
92+
- **[GitHub Issues](https://github.com/shakacode/react_on_rails/issues)** - Report bugs
93+
94+
### Professional Support
95+
96+
- **[ShakaCode Support](mailto:react_on_rails@shakacode.com)** - Professional React on Rails help
97+
- **[React on Rails Pro](https://www.shakacode.com/react-on-rails-pro/)** - Advanced features and support
98+
99+
## 🔗 External Resources
100+
101+
- **[Shakapacker Documentation](https://github.com/shakacode/shakapacker)** - Webpack integration for Rails
102+
- **[React Documentation](https://react.dev)** - Official React docs
103+
- **[Rails Guides](https://guides.rubyonrails.org)** - Ruby on Rails documentation
104+
105+
---
106+
107+
## 📚 Table of Contents
108+
109+
### API Reference
110+
111+
- [View Helpers API](./api/view-helpers-api.md)
112+
- [Redux Store API](./api/redux-store-api.md)
113+
- [JavaScript API](./api/javascript-api.md)
114+
115+
### Guides
116+
117+
#### Getting Started
118+
119+
- [Installation](./getting-started.md)
120+
- [Tutorial](./guides/tutorial.md)
121+
- [Basic Configuration](./guides/configuration.md)
122+
123+
#### Core Features
124+
125+
- [Server-Side Rendering](./guides/react-server-rendering.md)
126+
- [Component Registration](./guides/render-functions-and-railscontext.md)
127+
- [Props and RailsContext](./guides/render-functions-and-railscontext.md)
128+
129+
#### State Management
130+
131+
- [Redux Integration](./javascript/react-and-redux.md)
132+
- [Context API](./guides/render-functions-and-railscontext.md)
133+
134+
#### Routing
135+
136+
- [React Router Setup](./javascript/react-router.md)
137+
- [Server-Side Routing](./guides/react-server-rendering.md)
138+
139+
#### Advanced Topics
140+
141+
- [Webpack Configuration](./guides/webpack-configuration.md)
142+
- [Code Splitting](./javascript/code-splitting.md)
143+
- [Performance Optimization](./guides/webpack-configuration.md)
144+
145+
#### Development
146+
147+
- [Hot Module Replacement](./guides/hmr-and-hot-reloading-with-the-webpack-dev-server.md)
148+
- [Testing Components](./guides/rspec-configuration.md)
149+
- [Debugging](./javascript/troubleshooting-build-errors.md)
150+
151+
#### Deployment
152+
153+
- [Production Setup](./guides/deployment.md)
154+
- [Heroku Deployment](./guides/deployment.md)
155+
- [Docker Setup](./guides/deployment.md)
156+
157+
### Migration Guides
158+
159+
- [Upgrading React on Rails](./guides/upgrading-react-on-rails.md)
160+
- [From react-rails gem](./additional-details/migrating-from-react-rails.md)
161+
162+
### Troubleshooting
163+
164+
- [Common Issues](./troubleshooting/README.md)
165+
- [Error Messages](./javascript/troubleshooting-build-errors.md)
166+
- [Performance Issues](./javascript/troubleshooting-build-errors.md)
167+
168+
### Contributing
169+
170+
- [Contributing Guide](../CONTRIBUTING.md)
171+
- [Development Setup](../CONTRIBUTING.md)
172+
- [Pull Request Guidelines](../CONTRIBUTING.md)

‎docs/additional-details/recommended-project-structure.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ you should consider keeping your codebase mostly consistent with the defaults fo
1919

2020
1. Move the directory:
2121

22-
```sh
22+
```bash
2323
mv app/javascript client
2424
```
2525

‎docs/api/README.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# API Reference
2+
3+
Complete API documentation for React on Rails.
4+
5+
- [View Helpers API](./view-helpers-api.md)
6+
- [Redux Store API](./redux-store-api.md)
7+
- [JavaScript API](./javascript-api.md)

‎docs/contributor-info/pull-requests.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ From [How to Write a Git Commit Message](http://chris.beams.io/posts/git-commit/
3535

3636
When making doc changes, we want the change to work on both the gitbook and the regular github site. The issue is that non-doc files will not go to the gitbook site, so doc references to non doc files must use the github URL.
3737

38-
### Links to other docs:
38+
### Links to other docs
3939

4040
- When making references to source code files, use a full GitHub URL, for example:
4141
`[spec/dummy/config/initializers/react_on_rails.rb](https://github.com/shakacode/react_on_rails/tree/master/spec/dummy/config/initializers/react_on_rails.rb)`

0 commit comments

Comments
 (0)