Improve LLM discoverability for React on Rails Pro setup

[AbanoubGhadban]

Problem

LLMs (Claude, GPT, etc.) consistently fail to generate correct React on Rails Pro setup code. After deep analysis of a real failed setup attempt, the root causes are systemic: the Pro packages are nearly invisible to LLM training pipelines, and the manual setup steps invite hallucination.

This issue documents every identified failure point and proposes concrete fixes, ordered by priority.

---

Root Causes

1. npm packages are invisible to training

The react-on-rails-pro-node-renderer npm page returns HTTP 403. There is no public README on npmjs.org. The package source is in a private GitHub repo. This means:

• No npm README in training data
• No GitHub source code in training data
• No TypeScript types visible during crawling
• Nearly zero Stack Overflow questions, blog posts, or third-party discussion

Result: LLMs hallucinate by analogy — e.g., inventing createServer (from http.createServer()) instead of the real reactOnRailsProNodeRenderer, or guessing bundlePath instead of serverBundleCachePath.

2. Three packages with confusing boundaries

An LLM must figure out the relationship between 5 packages:

Package	Type	Role
react_on_rails	gem	Base Rails integration
react_on_rails_pro	gem	Pro server rendering
react-on-rails	npm	Base JS client
react-on-rails-pro	npm	Pro JS client (replaces base)
react-on-rails-pro-node-renderer	npm	Separate SSR server

Key confusion: the base gem's version checker rejects react-on-rails npm if the Pro gem is present, requiring react-on-rails-pro instead — but there's no way to know this without hitting the runtime error. This error message is excellent for humans but LLMs never see runtime errors during training.

3. No Pro generator exists

The base react_on_rails:install generator creates a working non-Pro app, but there's no react_on_rails_pro:install generator and no --pro flag. Setting up Pro requires 5+ manual steps:

1. Run the base generator
2. Manually create config/initializers/react_on_rails_pro.rb
3. Manually create the node renderer entry script
4. Manually uncomment two lines in serverWebpackConfig.js
5. Manually add a process to Procfile.dev

Each manual step is a chance for an LLM to hallucinate details.

4. Webpack config uses "uncomment to enable" pattern

The generated serverWebpackConfig.js contains:

// If using the React on Rails Pro node server renderer, uncomment the next line
// libraryTarget: 'commonjs2',

This pattern is fragile for LLMs — they have to recognize these specific comments matter and know which ones to uncomment.

5. Configuration attribute names are not guessable

Without strong training signal, LLMs guess wrong:

• config.renderer_url gets guessed as node_renderer_url or node_server_renderer_url
• reactOnRailsProNodeRenderer() gets guessed as createServer() or startRenderer()
• serverBundleCachePath gets guessed as bundlePath

6. Docs are good but siloed

The gem bundles excellent documentation (docs/installation.md, docs/configuration.md, docs/node-renderer/basics.md). The ShakaCode website is public and indexed. But:

• Gem docs are only accessible after bundle install — LLMs don't train on installed gem contents
• The correct setup is spread across 4+ separate doc pages
• There's no single "copy this and it works" page

7. Low community signal

Essentially zero: Stack Overflow questions, blog posts, YouTube tutorials, or public GitHub repos showing a complete Pro setup. LLMs heavily weight community content — when there's none, they fall back to pattern-matching from similar packages.

---

Proposed Fixes (Priority Order)

P0 — High Impact, Low Effort

1. Make npm packages publicly visible with READMEs

Even if the packages require a license at runtime, the npmjs.org listing and README are the #1 training signal for LLMs. Add a comprehensive README.md to the react-on-rails-pro-node-renderer package distribution showing:

• The correct import: const { reactOnRailsProNodeRenderer } = require('react-on-rails-pro-node-renderer')
• A minimal working config example
• The Config interface with descriptions

Do the same for react-on-rails-pro.

2. Publish a public reference/demo repo on GitHub

A complete, working React on Rails Pro hello world app. Even one public repo with correct code is a powerful training signal. LLMs train heavily on GitHub repos.

3. Create a single "Quick Start from Scratch" doc page

One linear page on shakacode.com with every command and every file needed to go from rails new to a working Pro SSR app. Self-contained tutorials are the format LLMs pick up best.

P1 — High Impact, Medium Effort

4. Create a react_on_rails_pro:install generator (or --pro flag)

This is the highest-impact code change. If the generator creates correct files (initializer, node renderer entry, uncommented webpack config, Procfile entry), LLMs can just run it instead of guessing file contents.

P2 — Medium Impact, Low Effort

5. Add README.md to gem distribution

The gem's bundled docs/ directory is great but invisible to training. A top-level README in the gem with a quick-start example would help.

6. Write a blog post with complete setup walkthrough

A shakacode.com blog post gets indexed and enters training data. Include every command and file.

7. Auto-detect Pro in webpack config

Instead of "uncomment to enable" comments in serverWebpackConfig.js, detect if react_on_rails_pro is present and auto-set target: 'node' and libraryTarget: 'commonjs2'.

---

Evidence

This analysis comes from a real attempt where Claude (Opus 4.6) tried to set up a React on Rails Pro 16.3.0 hello world app and made these exact mistakes:

• Used createServer instead of reactOnRailsProNodeRenderer (function doesn't exist)
• Used bundlePath instead of serverBundleCachePath (deprecated)
• Used node_server_renderer_url instead of renderer_url (attribute doesn't exist)
• Missing supportModules: true in node renderer config
• Missing renderer_password / password on both sides
• Installed react-on-rails npm before discovering the Pro gem requires react-on-rails-pro npm instead

Every one of these errors traces back to the root causes above.

---

Summary

React on Rails Pro is well-documented for humans who read docs, but nearly invisible to LLM training pipelines. The fixes are mostly about making existing good documentation available in the formats and locations where LLMs actually learn — npm READMEs, public GitHub repos, and self-contained tutorials.

🤖 Generated with Claude Code

[AbanoubGhadban]

Update: Outdated claims in this issue

Several claims in this issue are now outdated since React on Rails Pro moved to the public monorepo:

1. "The package source is in a private GitHub repo" — All gems and npm packages are now in the public monorepo at shakacode/react_on_rails
2. "npm page returns HTTP 403" — Packages are now publicly accessible on npmjs.org
3. "No GitHub source code in training data" — Source is now publicly visible in the monorepo
4. "No TypeScript types visible during crawling" — Types are now publicly visible
5. "No Pro generator exists" / "no --pro flag" — The --pro and --rsc generator flags were added in Add --pro and --rsc flags to install generator #2284

The documentation fixes proposed in this issue (READMEs, quick-start guide, llms.txt) are still valid and addressed by #2466.