Skip to content

Commit fdd60ac

Browse files
AbanoubGhadbanclaude
AbanoubGhadban
and
claude
committed
Add npm READMEs, Pro quick-start guide, and llms.txt for LLM discoverability
LLMs consistently fail to generate correct React on Rails Pro setup code because the npm packages have no READMEs, there's no single quick-start page, and the correct API names are not discoverable from training data. Changes: - Add README.md to all 3 npm packages (react-on-rails, react-on-rails-pro, react-on-rails-pro-node-renderer) with correct API examples, config options, and package relationship documentation - Fix incorrect example in Pro gem README (wrong scoped package name @shakacode-tools/... and deprecated bundlePath config key) - Add docs/getting-started/pro-quick-start.md — a single self-contained guide for setting up a Pro app from scratch using the --pro generator - Add llms.txt at repo root following the llms.txt convention, providing LLMs with correct package relationships, API names, and config keys Addresses #2465 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent b403619 commit fdd60ac

File tree

6 files changed

+647
-3
lines changed

6 files changed

+647
-3
lines changed

‎docs/getting-started/pro-quick-start.md‎

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
1+
# React on Rails Pro: Quick Start from Scratch
2+
3+
This guide walks you through creating a complete React on Rails Pro application with server-side rendering via the Node Renderer, from an empty directory to a running app.
4+
5+
**Time:** ~5 minutes
6+
7+
**Prerequisites:** Ruby 3.0+, Rails 7.0+, Node.js 18+, npm/yarn/pnpm
8+
9+
## Step 1: Create a new Rails app
10+
11+
```bash
12+
rails new my-pro-app --skip-javascript --skip-docker
13+
cd my-pro-app
14+
```
15+
16+
`--skip-javascript` is required because Shakapacker handles JavaScript bundling.
17+
18+
## Step 2: Add gems
19+
20+
```ruby
21+
# Append to Gemfile
22+
gem "shakapacker", "~> 9.5"
23+
gem "react_on_rails", "~> 16.3"
24+
gem "react_on_rails_pro", "~> 16.3"
25+
```
26+
27+
Then install:
28+
29+
```bash
30+
bundle install
31+
```
32+
33+
## Step 3: Install Shakapacker
34+
35+
```bash
36+
rails shakapacker:install
37+
```
38+
39+
## Step 4: Commit (required by generator)
40+
41+
The React on Rails generator requires a clean git working tree:
42+
43+
```bash
44+
git add -A && git commit -m "Rails app with Shakapacker"
45+
```
46+
47+
## Step 5: Install React on Rails with Pro
48+
49+
This single command sets up everything — base React on Rails, Pro configuration, Node Renderer, webpack configs, and npm packages:
50+
51+
```bash
52+
rails generate react_on_rails:install --pro
53+
```
54+
55+
The `--pro` flag creates:
56+
57+
| File | Purpose |
58+
|------|---------|
59+
| `config/initializers/react_on_rails.rb` | Base React on Rails config |
60+
| `config/initializers/react_on_rails_pro.rb` | Pro config with NodeRenderer settings |
61+
| `client/node-renderer.js` | Fastify-based Node.js SSR server entry |
62+
| `config/webpack/serverWebpackConfig.js` | Server webpack config with `target: 'node'` and `libraryTarget: 'commonjs2'` |
63+
| `app/javascript/src/HelloWorld/` | Example React component with SSR |
64+
| `app/controllers/hello_world_controller.rb` | Rails controller |
65+
| `app/views/hello_world/index.html.erb` | View using `react_component` helper |
66+
| `Procfile.dev` | All dev processes including Node Renderer |
67+
68+
Commit:
69+
70+
```bash
71+
git add -A && git commit -m "react_on_rails:install --pro"
72+
```
73+
74+
## Step 6: Start the app
75+
76+
```bash
77+
./bin/dev
78+
```
79+
80+
This starts four processes:
81+
- **Rails server** on port 3000
82+
- **Webpack dev server** (HMR) on port 3035
83+
- **Webpack SSR watcher** for server bundle
84+
- **Node Renderer** on port 3800
85+
86+
## Step 7: Visit the app
87+
88+
Open [http://localhost:3000/hello_world](http://localhost:3000/hello_world)
89+
90+
You should see the HelloWorld component rendered with SSR. View the page source to confirm pre-rendered HTML. The input field is interactive (client-side hydration).
91+
92+
## What the generator configured
93+
94+
### Rails-side (config/initializers/react_on_rails_pro.rb)
95+
96+
```ruby
97+
ReactOnRailsPro.configure do |config|
98+
config.server_renderer = "NodeRenderer"
99+
config.renderer_url = ENV.fetch("REACT_RENDERER_URL", "http://localhost:3800")
100+
config.renderer_password = ENV.fetch("RENDERER_PASSWORD", "devPassword")
101+
config.prerender_caching = true
102+
end
103+
```
104+
105+
### Node-side (client/node-renderer.js)
106+
107+
```js
108+
const { reactOnRailsProNodeRenderer } = require('react-on-rails-pro-node-renderer');
109+
110+
reactOnRailsProNodeRenderer({
111+
serverBundleCachePath: path.resolve(__dirname, './.node-renderer-bundles'),
112+
port: Number(process.env.RENDERER_PORT) || 3800,
113+
supportModules: true,
114+
workersCount: Number(process.env.NODE_RENDERER_CONCURRENCY || 3),
115+
});
116+
```
117+
118+
### Key configuration options
119+
120+
| Rails Config | Node Config | Purpose |
121+
|-------------|-------------|---------|
122+
| `config.renderer_url` | `port` | Must point to the same host:port |
123+
| `config.renderer_password` | `password` | Shared authentication secret |
124+
| `config.prerender_caching` | — | Cache SSR results in Rails cache |
125+
| `config.server_renderer` | — | Must be `"NodeRenderer"` to use the Node process |
126+
127+
## Adding React Server Components
128+
129+
To add RSC support to your Pro app:
130+
131+
```bash
132+
rails generate react_on_rails:rsc
133+
```
134+
135+
Or for a fresh app with RSC from the start:
136+
137+
```bash
138+
rails generate react_on_rails:install --rsc
139+
```
140+
141+
See the [RSC tutorial](https://www.shakacode.com/react-on-rails-pro/docs/react-server-components/tutorial/) for details.
142+
143+
## Next Steps
144+
145+
- [Configuration Reference](https://www.shakacode.com/react-on-rails-pro/docs/configuration/) — All Pro config options
146+
- [Node Renderer Configuration](https://www.shakacode.com/react-on-rails-pro/docs/node-renderer/js-configuration/) — All Node Renderer options
147+
- [Caching Guide](https://www.shakacode.com/react-on-rails-pro/docs/caching/) — Fragment and prerender caching
148+
- [Streaming SSR](https://www.shakacode.com/react-on-rails-pro/docs/streaming-server-rendering/) — Progressive rendering
149+
- [Code Splitting](https://www.shakacode.com/react-on-rails-pro/docs/code-splitting/) — Loadable components with SSR
150+
151+
## Troubleshooting
152+
153+
**"uninitialized constant ReactOnRailsPro"**: The `react_on_rails_pro` gem is not in your Gemfile. Run `bundle add react_on_rails_pro`.
154+
155+
**"You have the Pro gem installed but are using the base 'react-on-rails' package"**: Uninstall `react-on-rails` and install `react-on-rails-pro` instead. The `--pro` generator handles this automatically.
156+
157+
**Node Renderer not connecting**: Ensure the `renderer_url` in `react_on_rails_pro.rb` matches the `port` in `node-renderer.js` (default: 3800).
158+
159+
**Server bundle errors**: Ensure `serverWebpackConfig.js` has `target: 'node'` and `libraryTarget: 'commonjs2'` set. The `--pro` generator configures this automatically.

‎llms.txt‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
# React on Rails
2+
3+
> React on Rails integrates React with Ruby on Rails, providing server-side rendering (SSR), component registration, and seamless Rails view integration. React on Rails Pro adds advanced features: a high-performance Node.js rendering server, fragment caching, prerender caching, React Server Components (RSC), and streaming SSR.
4+
5+
## Package Relationships
6+
7+
React on Rails consists of Ruby gems and npm packages that must be paired correctly:
8+
9+
### Open-Source (base):
10+
- Ruby gem: `react_on_rails`
11+
- npm package: `react-on-rails`
12+
13+
### Pro (commercial, extends base):
14+
- Ruby gem: `react_on_rails_pro` (depends on `react_on_rails`)
15+
- npm package: `react-on-rails-pro` (REPLACES `react-on-rails`, do NOT use both)
16+
- npm package: `react-on-rails-pro-node-renderer` (standalone Fastify SSR server, optional)
17+
18+
IMPORTANT: When using the `react_on_rails_pro` gem, you MUST use the `react-on-rails-pro` npm package. The base `react-on-rails` npm package will be rejected at runtime.
19+
20+
## Quick Setup
21+
22+
### Base (open-source):
23+
```bash
24+
rails generate react_on_rails:install
25+
```
26+
27+
### Pro with Node Renderer:
28+
```bash
29+
bundle add react_on_rails_pro
30+
rails generate react_on_rails:install --pro
31+
```
32+
33+
### Pro with React Server Components:
34+
```bash
35+
bundle add react_on_rails_pro
36+
rails generate react_on_rails:install --rsc
37+
```
38+
39+
## Node Renderer API
40+
41+
The Node Renderer is a Fastify-based Node.js server for high-performance SSR.
42+
43+
### Correct usage:
44+
```js
45+
const { reactOnRailsProNodeRenderer } = require('react-on-rails-pro-node-renderer');
46+
47+
reactOnRailsProNodeRenderer({
48+
serverBundleCachePath: path.resolve(__dirname, '.node-renderer-bundles'),
49+
port: 3800,
50+
supportModules: true,
51+
password: process.env.RENDERER_PASSWORD,
52+
workersCount: 3,
53+
logLevel: 'info',
54+
});
55+
```
56+
57+
The function name is `reactOnRailsProNodeRenderer` (NOT `createServer` or `startRenderer`).
58+
The config key for the bundle cache directory is `serverBundleCachePath` (NOT `bundlePath`, which is deprecated).
59+
60+
### Rails-side configuration:
61+
```ruby
62+
# config/initializers/react_on_rails_pro.rb
63+
ReactOnRailsPro.configure do |config|
64+
config.server_renderer = "NodeRenderer"
65+
config.renderer_url = ENV.fetch("REACT_RENDERER_URL", "http://localhost:3800")
66+
config.renderer_password = ENV.fetch("RENDERER_PASSWORD", "devPassword")
67+
config.prerender_caching = true
68+
end
69+
```
70+
71+
Key attributes: `server_renderer`, `renderer_url`, `renderer_password`, `prerender_caching`, `ssr_timeout`, `renderer_use_fallback_exec_js`, `throw_js_errors`, `tracing`, `dependency_globs`.
72+
73+
### Webpack server config requirements (for Pro Node Renderer):
74+
```js
75+
// serverWebpackConfig.js output section
76+
libraryTarget: 'commonjs2',
77+
78+
// after output section
79+
serverWebpackConfig.target = 'node';
80+
```
81+
82+
## Client-Side Component Registration
83+
84+
```js
85+
// With base package
86+
import ReactOnRails from 'react-on-rails';
87+
ReactOnRails.register({ MyComponent });
88+
89+
// With Pro package (use this when react_on_rails_pro gem is installed)
90+
import ReactOnRails from 'react-on-rails-pro';
91+
ReactOnRails.register({ MyComponent });
92+
```
93+
94+
## Pro-Exclusive Imports
95+
96+
```js
97+
import { RSCRoute } from 'react-on-rails-pro/RSCRoute';
98+
import registerServerComponent from 'react-on-rails-pro/registerServerComponent/client';
99+
import { wrapServerComponentRenderer } from 'react-on-rails-pro/wrapServerComponentRenderer/client';
100+
```
101+
102+
## Documentation Links
103+
104+
- Docs: https://www.shakacode.com/react-on-rails/docs/
105+
- Pro Docs: https://www.shakacode.com/react-on-rails-pro/docs/
106+
- Pro Installation: https://www.shakacode.com/react-on-rails-pro/docs/installation/
107+
- Pro Configuration: https://www.shakacode.com/react-on-rails-pro/docs/configuration/
108+
- Node Renderer Basics: https://www.shakacode.com/react-on-rails-pro/docs/node-renderer/basics/
109+
- Node Renderer JS Config: https://www.shakacode.com/react-on-rails-pro/docs/node-renderer/js-configuration/
110+
- RSC Tutorial: https://www.shakacode.com/react-on-rails-pro/docs/react-server-components/tutorial/
111+
- GitHub: https://github.com/shakacode/react_on_rails

0 commit comments

Comments
 (0)