📚 Comprehensive documentation improvements for enhanced developer experience #1813
Conversation
WalkthroughAdds and reorganizes extensive documentation: new docs hub pages (Quick Start, Troubleshooting, API, Advanced), planning docs, AI agent setup instructions; major README and getting-started rewrites; many formatting standardizations and small guide edits; and two doc link updates in a rake task. No code or public API changes. Changes
Sequence Diagram(s)(omitted — changes are documentation-only and do not introduce control-flow or runtime behavior) Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Suggested reviewers
Poem
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches🧪 Generate unit tests
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
📊 PR Review: Comprehensive Documentation ImprovementsThank you for this excellent documentation improvement! The visual design, content organization, and user experience enhancements are outstanding. Here's my detailed review: ✅ StrengthsContent & Organization
Documentation Quality
🚨 Critical Issues to Fix1. Broken Internal LinksSeveral links point to non-existent paths in
2. Critical TypoLine 83 in # ❌ Current (typo)
mkdir -p app/javacript/src/SimpleCounter/components
# ✅ Should be
mkdir -p app/javascript/src/SimpleCounter/components3. Version Hardcoding
bundle add react_on_rails --strict # Gets latest stable version4. Missing Step NumberQuick Start has "Step 2" but no "Step 1" - needs consistent numbering.
|
🔍 Code Review for PR #1813: Documentation Improvements📋 SummaryThis PR delivers substantial documentation improvements with 1,226 additions across 17 files, focusing on enhanced developer experience through better organization, visual design, and user-centric navigation. ✅ Strengths
🔧 Required FixesHigh Priority
Medium Priority
🛡️ Security & Performance✅ No security concerns - documentation only 📊 CLAUDE.md Compliance
🎯 Recommendation: REQUEST CHANGESThis is an outstanding documentation improvement that will significantly enhance developer experience. However, the broken links and formatting issues need to be resolved before merging. Once fixed, this will position React on Rails as having best-in-class documentation that reduces onboarding friction. 📝 Action Items
Great work on the user experience design and content organization! 🎉 |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 7
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (4)
docs/guides/auto-bundling-file-system-based-automated-bundle-generation.md (2)
121-127: Incorrect import paths in exampleBar components live under src/Bar, but the example imports from src/Foo.
Apply this diff:
import ReactOnRails from 'react-on-rails'; import FooComponentOne from '../src/Foo/FooComponentOne'; -import BarComponentOne from '../src/Foo/BarComponentOne'; -import BarComponentTwo from '../src/Foo/BarComponentTwo'; +import BarComponentOne from '../src/Bar/BarComponentOne'; +import BarComponentTwo from '../src/Bar/BarComponentTwo';
326-338: CSS Modules import style inconsistent with project configPer project config (CSS Modules namedExports: true), examples should use namespace imports.
Apply this diff in both components:
-import styles from '../HelloWorld.module.css'; +import * as styles from '../HelloWorld.module.css';-import styles from '../HeavyMarkdownEditor.module.css'; +import * as styles from '../HeavyMarkdownEditor.module.css';Also applies to: 342-345
docs/javascript/render-functions.md (1)
192-197: Inconsistent requirement wording for react_component_hashEarlier sections specify the server-side hash is under renderedHtml.componentHtml, but this block says the object must include componentHtml at the top level. Align the requirement text.
Apply this diff:
-#### Requirements - -- The render function MUST return an object -- The object MUST include a `componentHtml` key -- All other keys are optional and can be accessed in your Rails view +#### Requirements + +- The render function MUST return an object +- The object MUST include a `renderedHtml` key containing a `componentHtml` key +- All other keys are optional and can be accessed in your Rails viewdocs/getting-started.md (1)
197-204: Code example bug: JSX uses, which is an undefined component.
Should be lowercase
<h1>.- // This is a React FunctionComponent because it is wrapped in a function. - return () => <H1>{JSON.stringify(props)}</H1>; + // This is a React FunctionComponent because it is wrapped in a function. + return () => <h1>{JSON.stringify(props)}</h1>;
🧹 Nitpick comments (18)
docs/guides/tutorial.md (1)
173-173: Prefer canonical names: SQLite and PostgreSQLImprove capitalization/accuracy of DB names.
Apply this diff:
-## Swap out sqlite for postgres +## Swap out SQLite for PostgreSQLAI_AGENT_INSTRUCTIONS.md (2)
8-11: Usegem infoor rely on Bundler instead ofgem search
gem searchdoesn’t reliably show the latest version in a usable way. Prefergem infoor just letbundle add --strictpin the latest automatically.Apply this diff:
-# Get latest available versions (recommended approach) -gem search react_on_rails --remote +# Optionally check the latest version +gem info react_on_rails --remote | sed -n '1p'
61-64: Clarifybin/dev killusage in docsThe
killsubcommand exists in the generated bin/dev template (lib/generators/react_on_rails/templates/base/base/bin/dev) and is implemented by lib/react_on_rails/dev/server_manager.rb (run_from_command_line → kill_processes), but there is no top-level bin/dev in the repo root — update AI_AGENT_INSTRUCTIONS.md (lines 61–64) to state that bin/dev is generated (run the installer/generator) or replace the reference with the equivalent overmind/foreman commands.DOCUMENTATION_IMPROVEMENT_PLAN.md (1)
1-168: Add ownership and timelines to drive executionSuggest adding DRI/owner per task and target dates per phase to ensure accountability and scheduling. Link each task to a GitHub issue.
DOCS_PR_SUMMARY.md (1)
31-35: Confirm referenced files exist and ensure trailing newline
- Please verify that DOCUMENTATION_IMPROVEMENT_PLAN.md was added and is linked correctly.
- Ensure this Markdown file ends with a trailing newline (repo guideline).
Also applies to: 146-149
README.md (1)
141-148: Align prerequisites across docsREADME lists Ruby >= 3.2 and Node >= 20, while Quick Start mentions Ruby 3.0+ and Node 18+. Recommend standardizing to a single set (prefer the stricter values here).
docs/guides/auto-bundling-file-system-based-automated-bundle-generation.md (1)
469-482: Bundle size numbers are inconsistent; consider making them illustrative“1.1MB total resources (50KB component-specific code …)” vs the listed 10.0 kB; also “2.2MB total (2.7MB with markdown libs)” conflicts with line-by-line totals. Suggest softening to approximate values or correcting the math.
docs/quick-start/README.md (3)
58-61: Add language to fenced code block (markdownlint MD040)Annotate this code fence with a language, e.g., text.
Apply this diff:
-``` +```text http://localhost:3000/hello_world--- `11-14`: **Standardize prerequisites with root README** Recommend aligning to Ruby >= 3.2, Node.js >= 20, and allow any JS package manager (npm/yarn/pnpm/bun) to match the main README. Apply this diff: ```diff -- **Rails 7+** application -- **Ruby 3.0+** -- **Node.js 18+** and **Yarn** +- **Rails 7+** application +- **Ruby 3.2+** +- **Node.js 20+** +- **JavaScript package manager** (npm, yarn, pnpm, or bun)
35-40: Outdated generator output pathsThe generator creates files under app/javascript (not client/). Please update bullets accordingly.
Apply this diff:
-- React component files in `client/` -- A sample controller and view -- Webpack configuration +- React component files in `app/javascript/src/` +- A sample controller and view +- Shakapacker configurationdocs/troubleshooting/README.md (1)
291-299: Use invite link for SlackDirect workspace links may fail for users not yet invited. Prefer the invite URL used elsewhere.
Apply this diff:
-- **[React + Rails Slack](https://reactrails.slack.com)** - Real-time community support +- **[React + Rails Slack](https://invite.reactrails.com)** - Real-time community supportdocs/getting-started.md (7)
17-17: Grammar: add article “a”.-### 📚 **Want comprehensive tutorial?** +### 📚 **Want a comprehensive tutorial?**
83-86: Link text doesn’t match target; simplify phrasing.-- Configure `config/initializers/react_on_rails.rb`. You can adjust some necessary settings and defaults. See file [docs/basics/configuration.md](./guides/configuration.md) for documentation of all configuration options. +- Configure `config/initializers/react_on_rails.rb`. You can adjust necessary settings and defaults. See [Configuration](./guides/configuration.md) for documentation of all options.
74-77: Clarify command or remove trailing “#”.
bin/dev static #looks like an unfinished comment.-bin/dev static # +bin/dev static # start without HMR
101-101: Typo: remove “@” from component_name.-`@component_name` is a string and corresponds to the name you used to globally expose your React component. +`component_name` is a string and corresponds to the name you used to globally expose your React component.
112-117: Prefer Shakapacker 7 terminology: “entrypoints” over “packs”.If targeting Shakapacker 7+, use entrypoints for examples.
-// packs/hello-world-bundle.js +// entrypoints/hello-world-bundle.jsConfirm the project-wide guidance (packs vs entrypoints) to keep examples consistent with Shakapacker 7.
119-121: Keep ERB examples consistent (use props: keyword style).Earlier examples use
props: @some_props.-<%= react_component("HelloWorld", @hello_world_props) %> +<%= react_component("HelloWorld", props: @hello_world_props) %>
103-107: Capitalize Webpack.Minor terminology consistency.
-automatically creates the webpack bundle +automatically creates the Webpack bundle
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (17)
AI_AGENT_INSTRUCTIONS.md(1 hunks)DOCS_PR_SUMMARY.md(1 hunks)DOCUMENTATION_IMPROVEMENT_PLAN.md(1 hunks)README.md(3 hunks)docs/README.md(1 hunks)docs/contributor-info/pull-requests.md(1 hunks)docs/getting-started.md(7 hunks)docs/guides/auto-bundling-file-system-based-automated-bundle-generation.md(1 hunks)docs/guides/how-to-use-different-files-for-client-and-server-rendering.md(3 hunks)docs/guides/tutorial.md(2 hunks)docs/guides/upgrading-react-on-rails.md(1 hunks)docs/javascript/render-functions.md(2 hunks)docs/outdated/rails-assets-relative-paths.md(1 hunks)docs/quick-start/README.md(1 hunks)docs/troubleshooting/README.md(1 hunks)lib/tasks/generate_packs.rake(2 hunks)spec/dummy/client/README.md(1 hunks)
🧰 Additional context used
📓 Path-based instructions (3)
{Gemfile,Rakefile,**/*.{rb,rake,gemspec,ru,js,jsx,ts,tsx,json,yml,yaml,md,css,scss}}
📄 CodeRabbit inference engine (CLAUDE.md)
Ensure all committed files end with a trailing newline character
Files:
docs/javascript/render-functions.mddocs/guides/how-to-use-different-files-for-client-and-server-rendering.mdDOCUMENTATION_IMPROVEMENT_PLAN.mdlib/tasks/generate_packs.rakespec/dummy/client/README.mddocs/contributor-info/pull-requests.mddocs/guides/auto-bundling-file-system-based-automated-bundle-generation.mddocs/troubleshooting/README.mddocs/quick-start/README.mddocs/guides/upgrading-react-on-rails.mdAI_AGENT_INSTRUCTIONS.mddocs/getting-started.mdREADME.mddocs/outdated/rails-assets-relative-paths.mddocs/guides/tutorial.mddocs/README.mdDOCS_PR_SUMMARY.md
**/*.{js,jsx,ts,tsx,json,yml,yaml,md,css,scss}
📄 CodeRabbit inference engine (CLAUDE.md)
Let Prettier handle all non-Ruby file formatting; never manually format these files
Files:
docs/javascript/render-functions.mddocs/guides/how-to-use-different-files-for-client-and-server-rendering.mdDOCUMENTATION_IMPROVEMENT_PLAN.mdspec/dummy/client/README.mddocs/contributor-info/pull-requests.mddocs/guides/auto-bundling-file-system-based-automated-bundle-generation.mddocs/troubleshooting/README.mddocs/quick-start/README.mddocs/guides/upgrading-react-on-rails.mdAI_AGENT_INSTRUCTIONS.mddocs/getting-started.mdREADME.mddocs/outdated/rails-assets-relative-paths.mddocs/guides/tutorial.mddocs/README.mdDOCS_PR_SUMMARY.md
{Gemfile,Rakefile,**/*.{rb,rake,gemspec,ru}}
📄 CodeRabbit inference engine (CLAUDE.md)
{Gemfile,Rakefile,**/*.{rb,rake,gemspec,ru}}: Before every commit/push, runbundle exec rubocopand fix all violations in Ruby code
Let RuboCop handle all Ruby code formatting; never manually format Ruby files
Files:
lib/tasks/generate_packs.rake
🧠 Learnings (6)
📚 Learning: 2025-04-26T21:55:55.874Z
Learnt from: alexeyr-ci2
PR: shakacode/react_on_rails#1732
File: spec/dummy/client/app-react16/startup/ReduxSharedStoreApp.client.jsx:40-44
Timestamp: 2025-04-26T21:55:55.874Z
Learning: In the react_on_rails project, files under `app-react16` directories are copied/moved to corresponding `/app` directories during the conversion process (removing the `-react16` suffix), which affects their relative import paths at runtime.
Applied to files:
lib/tasks/generate_packs.rakedocs/guides/auto-bundling-file-system-based-automated-bundle-generation.mddocs/guides/upgrading-react-on-rails.mddocs/getting-started.mdREADME.md
📚 Learning: 2025-02-12T16:38:06.537Z
Learnt from: Romex91
PR: shakacode/react_on_rails#1697
File: package-scripts.yml:28-28
Timestamp: 2025-02-12T16:38:06.537Z
Learning: The file `node_package/lib/ReactOnRails.full.js` is autogenerated during the build process and should not be present in the repository.
Applied to files:
lib/tasks/generate_packs.rakedocs/guides/auto-bundling-file-system-based-automated-bundle-generation.mddocs/guides/upgrading-react-on-rails.mddocs/getting-started.md
📚 Learning: 2025-01-23T18:20:45.824Z
Learnt from: alexeyr-ci
PR: shakacode/react_on_rails#1687
File: spec/dummy/package.json:0-0
Timestamp: 2025-01-23T18:20:45.824Z
Learning: When adding or updating dependencies in spec/dummy/package.json, maintain version consistency with other package.json files in the codebase to avoid potential version conflicts.
Applied to files:
spec/dummy/client/README.md
📚 Learning: 2025-09-22T07:21:12.910Z
Learnt from: CR
PR: shakacode/react_on_rails#0
File: CLAUDE.md:0-0
Timestamp: 2025-09-22T07:21:12.910Z
Learning: Use Yarn only; never run npm commands
Applied to files:
spec/dummy/client/README.md
📚 Learning: 2025-09-16T08:01:11.146Z
Learnt from: justin808
PR: shakacode/react_on_rails#1770
File: lib/generators/react_on_rails/templates/base/base/app/javascript/src/HelloWorld/ror_components/HelloWorld.client.jsx:2-2
Timestamp: 2025-09-16T08:01:11.146Z
Learning: React on Rails uses webpack CSS Modules configuration with namedExports: true, which requires the import syntax `import * as style from './file.module.css'` rather than the default export pattern. This configuration enables better tree shaking and bundle size optimization for CSS modules.
Applied to files:
docs/guides/auto-bundling-file-system-based-automated-bundle-generation.mddocs/guides/upgrading-react-on-rails.mddocs/getting-started.mdREADME.md
📚 Learning: 2025-09-15T21:24:48.207Z
Learnt from: AbanoubGhadban
PR: shakacode/react_on_rails#1781
File: node_package/src/ClientSideRenderer.ts:82-95
Timestamp: 2025-09-15T21:24:48.207Z
Learning: In React on Rails, the force_load feature includes both explicit `data-force-load="true"` usage and the ability to hydrate components during the page loading state (`document.readyState === 'loading'`). Both capabilities require a Pro license, so the condition `!railsContext.rorPro && (isComponentForceLoaded || document.readyState === 'loading')` correctly gates both scenarios.
Applied to files:
docs/getting-started.mdREADME.md
🪛 markdownlint-cli2 (0.18.1)
docs/troubleshooting/README.md
11-11: Link fragments should be valid
(MD051, link-fragments)
12-12: Link fragments should be valid
(MD051, link-fragments)
13-13: Link fragments should be valid
(MD051, link-fragments)
14-14: Link fragments should be valid
(MD051, link-fragments)
15-15: Link fragments should be valid
(MD051, link-fragments)
47-47: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
126-126: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
docs/quick-start/README.md
58-58: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
docs/getting-started.md
67-67: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
140-140: Reference links and images should use a label that is defined
Missing link or image reference definition: "./guides/auto-bundling-file-system-based-automated-bundle-generation.md"
(MD052, reference-links-images)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (9)
- GitHub Check: dummy-app-integration-tests (3.4, 22)
- GitHub Check: dummy-app-integration-tests (3.2, 20)
- GitHub Check: markdown-link-check
- GitHub Check: build
- GitHub Check: rspec-package-tests (3.4, minimum)
- GitHub Check: rspec-package-tests (3.2, minimum)
- GitHub Check: rspec-package-tests (3.4, latest)
- GitHub Check: rspec-package-tests (3.2, latest)
- GitHub Check: claude-review
🔇 Additional comments (9)
docs/outdated/rails-assets-relative-paths.md (1)
126-126: Consistent heading punctuation — looks goodColon removal matches the new docs style across the repo. No content impact.
docs/guides/upgrading-react-on-rails.md (1)
277-277: Consistent heading punctuation — approvedColon removed for consistency. No behavioral/content changes.
docs/contributor-info/pull-requests.md (1)
38-38: Consistent heading punctuation — approvedColon removal aligns with style cleanup.
docs/guides/how-to-use-different-files-for-client-and-server-rendering.md (1)
31-31: Heading punctuation cleanup — approvedAll four heading tweaks are consistent with the repo-wide style changes.
Also applies to: 58-58, 60-61, 83-84
spec/dummy/client/README.md (1)
30-30: Minor copy edit — approvedColon removal reads fine and matches the broader docs polish.
README.md (1)
98-105: Quick Start links: looks good; verify external URLsThe “Quick Start / Docs / Live Demo” links read well. Please double-check the hosted URLs resolve (site deploys sometimes lag behind doc changes).
lib/tasks/generate_packs.rake (1)
86-86: Updated docs links — file exists; confirm website path resolvesFound at docs/guides/auto-bundling-file-system-based-automated-bundle-generation.md. Verify the website path resolves.
docs/troubleshooting/README.md (1)
9-15: Anchors validated — table links resolve correctlyHeadings slugify to #installation-issues, #build-issues, #runtime-issues, #server-side-rendering-issues, and #performance-issues; these match the table links in docs/troubleshooting/README.md.
docs/getting-started.md (1)
30-36: Verify link path for Shakapacker v6 “special setup”.Path
./additional-details/tips-for-usage-with-sp6.mdmay differ (e.g., naming “sp6” vs “sp-v6”). Please confirm.
| # Create new Rails app | ||
| rails new myapp --skip-javascript --database=postgresql | ||
| cd myapp | ||
|
|
||
| # Use latest version | ||
| bundle add react_on_rails --version 16.0.1 --strict | ||
|
|
||
| bin/rails generate react_on_rails:install | ||
|
|
||
| # Accept change to bin/dev | ||
|
|
||
| # Start development servers | ||
| bin/dev | ||
| ``` |
There was a problem hiding this comment.
Add Shakapacker and avoid hardcoding a specific RoR version
v16 requires Shakapacker. Also, hardcoding 16.0.1 will go stale; --strict will pin the latest for you.
Apply this diff to Scenario 1:
-# Create new Rails app
-rails new myapp --skip-javascript --database=postgresql
-cd myapp
-
-# Use latest version
-bundle add react_on_rails --version 16.0.1 --strict
-
-bin/rails generate react_on_rails:install
+# Create new Rails app
+rails new myapp --skip-javascript --database=postgresql
+cd myapp
+
+# Add required gems (pins exact latest versions)
+bundle add shakapacker --strict
+bundle add react_on_rails --strict
+
+# Install shakapacker first, then React on Rails
+bin/rails shakapacker:install
+bin/rails react_on_rails:install📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| # Create new Rails app | |
| rails new myapp --skip-javascript --database=postgresql | |
| cd myapp | |
| # Use latest version | |
| bundle add react_on_rails --version 16.0.1 --strict | |
| bin/rails generate react_on_rails:install | |
| # Accept change to bin/dev | |
| # Start development servers | |
| bin/dev | |
| ``` | |
| # Create new Rails app | |
| rails new myapp --skip-javascript --database=postgresql | |
| cd myapp | |
| # Add required gems (pins exact latest versions) | |
| bundle add shakapacker --strict | |
| bundle add react_on_rails --strict | |
| # Install shakapacker first, then React on Rails | |
| bin/rails shakapacker:install | |
| bin/rails react_on_rails:install | |
| # Accept change to bin/dev | |
| # Start development servers | |
| bin/dev |
🤖 Prompt for AI Agents
AI_AGENT_INSTRUCTIONS.md lines 19-32: The instructions currently hardcode
react_on_rails v16.0.1 and omit Shakapacker; update Scenario 1 to add the
shakapacker gem (and run its installer) because react_on_rails v16 requires
Shakapacker, and stop pinning an exact react_on_rails version—use bundle add
react_on_rails with --strict (or no explicit version) so the latest compatible
release is selected; keep the existing steps to run the react_on_rails
installer, accept the bin/dev change, and start bin/dev.
| cd /path/to/existing/app | ||
| # Use latest version | ||
| bundle add react_on_rails --version 16.0.1 --strict | ||
|
|
||
| bin/rails generate react_on_rails:install | ||
|
|
||
| # Accept change to bin/dev | ||
|
|
||
| # Start development servers | ||
| bin/dev | ||
| # Navigate to existing Rails app root | ||
|
|
||
| # Start development | ||
| bin/dev | ||
| ``` |
There was a problem hiding this comment.
Ensure Shakapacker is installed for existing apps and remove duplication
Add Shakapacker install steps and remove the duplicate/bin/dev ordering issue.
Apply this diff to Scenario 2:
-cd /path/to/existing/app
-# Use latest version
-bundle add react_on_rails --version 16.0.1 --strict
-
-bin/rails generate react_on_rails:install
-
-# Accept change to bin/dev
-
-# Start development servers
-bin/dev
-# Navigate to existing Rails app root
-
-# Start development
-bin/dev
+cd /path/to/existing/app
+# Add required gems (pins exact latest versions)
+bundle add shakapacker --strict
+bundle add react_on_rails --strict
+
+# Install shakapacker first, then React on Rails
+bin/rails shakapacker:install
+bin/rails react_on_rails:install
+
+# Accept change to bin/dev
+
+# Start development servers
+bin/dev📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| cd /path/to/existing/app | |
| # Use latest version | |
| bundle add react_on_rails --version 16.0.1 --strict | |
| bin/rails generate react_on_rails:install | |
| # Accept change to bin/dev | |
| # Start development servers | |
| bin/dev | |
| # Navigate to existing Rails app root | |
| # Start development | |
| bin/dev | |
| ``` | |
| cd /path/to/existing/app | |
| # Add required gems (pins exact latest versions) | |
| bundle add shakapacker --strict | |
| bundle add react_on_rails --strict | |
| # Install shakapacker first, then React on Rails | |
| bin/rails shakapacker:install | |
| bin/rails react_on_rails:install | |
| # Accept change to bin/dev | |
| # Start development servers | |
| bin/dev |
🤖 Prompt for AI Agents
In AI_AGENT_INSTRUCTIONS.md around lines 41 to 55, the script for Scenario 2 is
missing Shakapacker installation and contains a duplicated/incorrect ordering of
bin/dev; update Scenario 2 to include Shakapacker install steps for existing
Rails apps (add installation and any required setup commands before running
generators), remove the duplicate bin/dev lines so bin/dev is only invoked once
at the end, and ensure the react_on_rails generator and bin/dev invocation occur
after Shakapacker is installed and configured.
Code Review for PR #1813: Documentation ImprovementsExcellent documentation improvements! This PR significantly enhances the React on Rails developer experience. Strengths
Critical Issues
Suggestions
Security & Testing
Overall AssessmentHigh-quality PR that makes React on Rails much more accessible. Once the installation order documentation is restored, this will be an excellent addition. Recommendation: Approve with minor changes |
There was a problem hiding this comment.
Actionable comments posted: 3
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (3)
docs/getting-started.md (3)
80-81: Link text/file path mismatch.The visible label references “docs/basics/configuration.md” while the link points to guides. Simplify the text for clarity.
-- Configure `config/initializers/react_on_rails.rb`. You can adjust some necessary settings and defaults. See file [docs/basics/configuration.md](./guides/configuration.md) for documentation of all configuration options. +- Configure `config/initializers/react_on_rails.rb`. You can adjust some necessary settings and defaults. See the [Configuration guide](./guides/configuration.md) for all configuration options.
179-181: Fix awkward phrasing (“which we using the name ...”).Improve readability and correctness.
-You have two ways to specify your React components. You can either register the React component (either function or class component) directly, or you can create a function that returns a React component, which we using the name of a "render-function". Creating a render-function allows you to: +You have two ways to specify your React components. You can either register the React component (function or class) directly, or create a function that returns a React component, which we refer to as a "render-function." Creating a render-function allows you to:
195-201: Fix JSX example: HTML tag should be lowercase (h1), notH1.As written,
H1implies a React component that isn’t defined/imported.- // This is a React FunctionComponent because it is wrapped in a function. - return () => <H1>{JSON.stringify(props)}</H1>; + // This is a React FunctionComponent because it is wrapped in a function. + return () => <h1>{JSON.stringify(props)}</h1>;
🧹 Nitpick comments (4)
docs/guides/tutorial.md (1)
173-173: Use correct product names: “SQLite” and “PostgreSQL”Recommend: “## Swap out SQLite for PostgreSQL”. If you apply this, also update the TOC link target accordingly.
docs/getting-started.md (3)
70-74: Incomplete inline comment in code block.Trailing “#” without explanation is confusing. Either remove it or add a brief description.
```bash bin/dev help bin/dev # start with hmr -bin/dev static # +bin/dev static # serve precompiled assets (no HMR)--- `51-53`: **Avoid overly specific version pin that will stale quickly.** Recommend a pessimistic constraint to allow patch updates within 16.x while keeping docs aligned with “use the latest”. ```diff - bundle add react_on_rails --version=16.0.0 --strict + bundle add react_on_rails --version "~> 16.0" --strict
116-119: Use consistentprops:syntax forreact_componentexample.Elsewhere you use
props: @some_props. Keep examples consistent.-<%= react_component("HelloWorld", @hello_world_props) %> +<%= react_component("HelloWorld", props: @hello_world_props) %>
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (7)
AI_AGENT_INSTRUCTIONS.md(1 hunks)docs/README.md(1 hunks)docs/api/README.md(1 hunks)docs/getting-started.md(7 hunks)docs/guides/advanced/README.md(1 hunks)docs/guides/tutorial.md(2 hunks)docs/quick-start/README.md(1 hunks)
✅ Files skipped from review due to trivial changes (2)
- docs/api/README.md
- docs/guides/advanced/README.md
🚧 Files skipped from review as they are similar to previous changes (3)
- AI_AGENT_INSTRUCTIONS.md
- docs/README.md
- docs/quick-start/README.md
🧰 Additional context used
📓 Path-based instructions (2)
{Gemfile,Rakefile,**/*.{rb,rake,gemspec,ru,js,jsx,ts,tsx,json,yml,yaml,md,css,scss}}
📄 CodeRabbit inference engine (CLAUDE.md)
Ensure all committed files end with a trailing newline character
Files:
docs/getting-started.mddocs/guides/tutorial.md
**/*.{js,jsx,ts,tsx,json,yml,yaml,md,css,scss}
📄 CodeRabbit inference engine (CLAUDE.md)
Let Prettier handle all non-Ruby file formatting; never manually format these files
Files:
docs/getting-started.mddocs/guides/tutorial.md
🧠 Learnings (4)
📚 Learning: 2025-04-26T21:55:55.874Z
Learnt from: alexeyr-ci2
PR: shakacode/react_on_rails#1732
File: spec/dummy/client/app-react16/startup/ReduxSharedStoreApp.client.jsx:40-44
Timestamp: 2025-04-26T21:55:55.874Z
Learning: In the react_on_rails project, files under `app-react16` directories are copied/moved to corresponding `/app` directories during the conversion process (removing the `-react16` suffix), which affects their relative import paths at runtime.
Applied to files:
docs/getting-started.md
📚 Learning: 2025-02-12T16:38:06.537Z
Learnt from: Romex91
PR: shakacode/react_on_rails#1697
File: package-scripts.yml:28-28
Timestamp: 2025-02-12T16:38:06.537Z
Learning: The file `node_package/lib/ReactOnRails.full.js` is autogenerated during the build process and should not be present in the repository.
Applied to files:
docs/getting-started.md
📚 Learning: 2025-09-16T08:01:11.146Z
Learnt from: justin808
PR: shakacode/react_on_rails#1770
File: lib/generators/react_on_rails/templates/base/base/app/javascript/src/HelloWorld/ror_components/HelloWorld.client.jsx:2-2
Timestamp: 2025-09-16T08:01:11.146Z
Learning: React on Rails uses webpack CSS Modules configuration with namedExports: true, which requires the import syntax `import * as style from './file.module.css'` rather than the default export pattern. This configuration enables better tree shaking and bundle size optimization for CSS modules.
Applied to files:
docs/getting-started.md
📚 Learning: 2025-09-15T21:24:48.207Z
Learnt from: AbanoubGhadban
PR: shakacode/react_on_rails#1781
File: node_package/src/ClientSideRenderer.ts:82-95
Timestamp: 2025-09-15T21:24:48.207Z
Learning: In React on Rails, the force_load feature includes both explicit `data-force-load="true"` usage and the ability to hydrate components during the page loading state (`document.readyState === 'loading'`). Both capabilities require a Pro license, so the condition `!railsContext.rorPro && (isComponentForceLoaded || document.readyState === 'loading')` correctly gates both scenarios.
Applied to files:
docs/getting-started.md
🪛 markdownlint-cli2 (0.18.1)
docs/getting-started.md
58-58: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (8)
- GitHub Check: build-dummy-app-webpack-test-bundles (3.4, 22)
- GitHub Check: rspec-package-tests (3.4, minimum)
- GitHub Check: rspec-package-tests (3.2, latest)
- GitHub Check: markdown-link-check
- GitHub Check: build
- GitHub Check: rspec-package-tests (3.2, minimum)
- GitHub Check: rspec-package-tests (3.4, latest)
- GitHub Check: claude-review
🔇 Additional comments (4)
docs/guides/tutorial.md (1)
25-25: Resolved: pluralization fix looks goodHeader corrected to “Table of Contents.”
docs/getting-started.md (3)
62-66: Thanks for fixing the malformed fenced code block.The backticks/language spec are now correct, resolving the earlier MD040 issue.
137-140: Thanks for converting the reference-style link to an inline link.This addresses the previous MD052 warning.
28-36: Fix broken intra-doc link in docs/getting-started.mdMissing image link: ../images/bundle-splitting-hello-world.png -> images/bundle-splitting-hello-world.png (file not found). Add the image to repo or update the link to the correct path.
⛔ Skipped due to learnings
Learnt from: justin808 PR: shakacode/react_on_rails#1770 File: lib/generators/react_on_rails/templates/base/base/app/javascript/src/HelloWorld/ror_components/HelloWorld.client.jsx:2-2 Timestamp: 2025-09-16T08:01:11.146Z Learning: React on Rails uses webpack CSS Modules configuration with namedExports: true, which requires the import syntax `import * as style from './file.module.css'` rather than the default export pattern. This configuration enables better tree shaking and bundle size optimization for CSS modules.
| ### 📚 **Want comprehensive tutorial?** | ||
|
|
||
| **→ [Complete Tutorial](./guides/tutorial.md)** - Step-by-step with Redux and routing |
There was a problem hiding this comment.
Grammar: add missing article (“a”).
Update the heading to read naturally.
-### 📚 **Want comprehensive tutorial?**
+### 📚 **Want a comprehensive tutorial?**📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ### 📚 **Want comprehensive tutorial?** | |
| **→ [Complete Tutorial](./guides/tutorial.md)** - Step-by-step with Redux and routing | |
| ### 📚 **Want a comprehensive tutorial?** | |
| **→ [Complete Tutorial](./guides/tutorial.md)** - Step-by-step with Redux and routing |
🤖 Prompt for AI Agents
In docs/getting-started.md around lines 17 to 19, the heading "Want
comprehensive tutorial?" is missing the article "a"; update the heading to read
"Want a comprehensive tutorial?" and ensure the link and following text remain
unchanged.
| `@component_name` is a string and corresponds to the name you used to globally expose your React component. | ||
|
|
There was a problem hiding this comment.
Clarify component name (remove Ruby instance variable sigil).
Using “@component_name” here is misleading; it’s not a Ruby instance variable.
-`@component_name` is a string and corresponds to the name you used to globally expose your React component.
+The component name is a string and corresponds to the name you used to globally expose your React component.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| `@component_name` is a string and corresponds to the name you used to globally expose your React component. | |
| The component name is a string and corresponds to the name you used to globally expose your React component. |
🤖 Prompt for AI Agents
In docs/getting-started.md around lines 98 to 99, the text uses
“@component_name” which wrongly implies a Ruby instance-variable sigil; update
the wording to use a plain identifier (for example component_name or
your-component-name) and clarify that it should match the global name you
exposed for your React component (no @). Replace any occurrences of
“@component_name” with the chosen plain identifier and adjust surrounding
sentence to read that it is a string corresponding to the global name used to
expose the component.
📝 Code Review: Documentation Improvements PRThank you for this comprehensive documentation improvement effort! The modernization and user experience focus are excellent. However, I've identified several critical issues that need to be addressed before merging. 🔴 Critical Issues to Fix1. Broken Links (Blocking)Several links point to non-existent files:
2. File Reference InconsistenciesThe auto-bundling guide rename creates broken references in README.md's feature table. 🟡 Moderate Issues3. AI Agent Instructions
4. Documentation StructureSome promised guides in ✅ Notable StrengthsExcellent Improvements:
Technical Accuracy:
📋 Specific RecommendationsMust Fix Before Merge:
Should Fix:
Nice to Have:
🎯 Compliance Check✅ Follows project conventions per CLAUDE.md 🚀 VerdictConditional Approval: This is a valuable documentation improvement that will significantly help new users. However, the broken links must be fixed before merging as they will frustrate users trying to navigate the docs. Once the critical issues are resolved, this will be an excellent addition to React on Rails! Review focuses on documentation quality, technical accuracy, and user experience. |
🔍 Pull Request Review: Documentation ImprovementsThank you for this comprehensive documentation update! The improvements are substantial and well-structured. Here is my detailed review: ✅ Strengths📚 Excellent Documentation Organization
🎯 User Experience Improvements
💡 Technical Accuracy
🔧 Code Quality Issues1. Missing Trailing NewlinesPer the CLAUDE.md requirements, ALL files must end with a newline character. Please ensure all new and modified files have trailing newlines. CI will fail without this. 2. Code Improvements in lib/tasks/generate_packs.rakeThe rake task improvements are good, but consider:
📝 Suggestions for EnhancementDocumentation Suggestions
Content Consistency
|
There was a problem hiding this comment.
Actionable comments posted: 1
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (8)
docs/README.md(1 hunks)docs/additional-details/recommended-project-structure.md(1 hunks)docs/getting-started.md(7 hunks)docs/guides/rails-webpacker-react-integration-options.md(1 hunks)docs/javascript/capistrano-deployment.md(1 hunks)docs/planning/DOCS_PR_SUMMARY.md(1 hunks)docs/planning/DOCUMENTATION_IMPROVEMENT_PLAN.md(1 hunks)docs/quick-start/README.md(1 hunks)
✅ Files skipped from review due to trivial changes (3)
- docs/additional-details/recommended-project-structure.md
- docs/planning/DOCUMENTATION_IMPROVEMENT_PLAN.md
- docs/javascript/capistrano-deployment.md
🚧 Files skipped from review as they are similar to previous changes (2)
- docs/quick-start/README.md
- docs/README.md
🧰 Additional context used
📓 Path-based instructions (2)
{Gemfile,Rakefile,**/*.{rb,rake,gemspec,ru,js,jsx,ts,tsx,json,yml,yaml,md,css,scss}}
📄 CodeRabbit inference engine (CLAUDE.md)
Ensure all committed files end with a trailing newline character
Files:
docs/guides/rails-webpacker-react-integration-options.mddocs/getting-started.mddocs/planning/DOCS_PR_SUMMARY.md
**/*.{js,jsx,ts,tsx,json,yml,yaml,md,css,scss}
📄 CodeRabbit inference engine (CLAUDE.md)
Let Prettier handle all non-Ruby file formatting; never manually format these files
Files:
docs/guides/rails-webpacker-react-integration-options.mddocs/getting-started.mddocs/planning/DOCS_PR_SUMMARY.md
🧠 Learnings (4)
📚 Learning: 2025-09-16T08:01:11.146Z
Learnt from: justin808
PR: shakacode/react_on_rails#1770
File: lib/generators/react_on_rails/templates/base/base/app/javascript/src/HelloWorld/ror_components/HelloWorld.client.jsx:2-2
Timestamp: 2025-09-16T08:01:11.146Z
Learning: React on Rails uses webpack CSS Modules configuration with namedExports: true, which requires the import syntax `import * as style from './file.module.css'` rather than the default export pattern. This configuration enables better tree shaking and bundle size optimization for CSS modules.
Applied to files:
docs/guides/rails-webpacker-react-integration-options.mddocs/getting-started.md
📚 Learning: 2025-04-26T21:55:55.874Z
Learnt from: alexeyr-ci2
PR: shakacode/react_on_rails#1732
File: spec/dummy/client/app-react16/startup/ReduxSharedStoreApp.client.jsx:40-44
Timestamp: 2025-04-26T21:55:55.874Z
Learning: In the react_on_rails project, files under `app-react16` directories are copied/moved to corresponding `/app` directories during the conversion process (removing the `-react16` suffix), which affects their relative import paths at runtime.
Applied to files:
docs/guides/rails-webpacker-react-integration-options.mddocs/getting-started.md
📚 Learning: 2025-02-12T16:38:06.537Z
Learnt from: Romex91
PR: shakacode/react_on_rails#1697
File: package-scripts.yml:28-28
Timestamp: 2025-02-12T16:38:06.537Z
Learning: The file `node_package/lib/ReactOnRails.full.js` is autogenerated during the build process and should not be present in the repository.
Applied to files:
docs/getting-started.md
📚 Learning: 2025-09-15T21:24:48.207Z
Learnt from: AbanoubGhadban
PR: shakacode/react_on_rails#1781
File: node_package/src/ClientSideRenderer.ts:82-95
Timestamp: 2025-09-15T21:24:48.207Z
Learning: In React on Rails, the force_load feature includes both explicit `data-force-load="true"` usage and the ability to hydrate components during the page loading state (`document.readyState === 'loading'`). Both capabilities require a Pro license, so the condition `!railsContext.rorPro && (isComponentForceLoaded || document.readyState === 'loading')` correctly gates both scenarios.
Applied to files:
docs/getting-started.md
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (9)
- GitHub Check: dummy-app-integration-tests (3.2, 20)
- GitHub Check: dummy-app-integration-tests (3.4, 22)
- GitHub Check: rspec-package-tests (3.4, latest)
- GitHub Check: rspec-package-tests (3.4, minimum)
- GitHub Check: rspec-package-tests (3.2, minimum)
- GitHub Check: rspec-package-tests (3.2, latest)
- GitHub Check: claude-review
- GitHub Check: build
- GitHub Check: markdown-link-check
🔇 Additional comments (8)
docs/guides/rails-webpacker-react-integration-options.md (1)
145-147: Minor improvement: Fix code fence language consistency.Changing from
shtobashaligns with other command blocks in the repository's documentation and provides better syntax highlighting consistency. Good attention to detail in standardizing the documentation format.docs/planning/DOCS_PR_SUMMARY.md (1)
1-149: Well-structured documentation improvement plan with clear objectives and success metrics.This planning document effectively captures the comprehensive nature of the documentation overhaul with:
- Clear before/after analysis highlighting specific pain points and solutions
- Concrete deliverables and visual improvements that address user experience issues
- Measurable success criteria and business impact assessment
- Proper phased implementation approach
The emphasis on user-centric paths (beginner → experienced → migrating users) and self-service troubleshooting aligns well with reducing support burden while improving developer onboarding experience.
docs/getting-started.md (6)
17-19: Fix grammatical error in heading.The heading is missing the article "a" and should read naturally.
-### 📚 **Want comprehensive tutorial?** +### 📚 **Want a comprehensive tutorial?**
99-99: Remove misleading Ruby instance variable syntax.Using
@component_nameincorrectly implies a Ruby instance variable when it should refer to a plain string parameter.-`@component_name` is a string and corresponds to the name you used to globally expose your React component. +The component name is a string and corresponds to the name you used to globally expose your React component.
138-140: Fix reference-style link syntax.The link uses incorrect reference-style bracket syntax instead of inline link parentheses.
-See [Auto-Bundling: File-System-Based Automated Bundle Generation][./guides/auto-bundling-file-system-based-automated-bundle-generation.md] +See [Auto-Bundling: File-System-Based Automated Bundle Generation](./guides/auto-bundling-file-system-based-automated-bundle-generation.md)
168-168: Fix likely broken image path.The image path uses
../images/which likely results in a 404 error from the current file location indocs/getting-started.md.- +
101-141: Excellent addition: Auto-Bundling documentation with clear comparison.The new Auto-Bundling section provides excellent value by:
- Clearly contrasting manual registration vs auto-bundling approaches
- Providing concrete code examples for both patterns
- Explaining the benefits of
auto_load_bundle: true- Cross-referencing detailed documentation
This addresses a key pain point mentioned in the PR objectives by giving developers a clear path to modern React on Rails patterns while maintaining backward compatibility understanding.
234-253: Well-organized progressive learning path structure.The new "More Reading" and "Additional Resources" sections create a clear learning progression that addresses different user types mentioned in the PR objectives:
- API reference for experienced developers seeking specific information
- Tutorial for comprehensive learning
- Configuration details for advanced users
- Migration guide for existing users
This structure aligns perfectly with the documented goal of providing "multiple entry points based on user type" and reduces the information overload issue identified in the planning documents.
- Update 20+ broken links in docs/README.md to point to existing files - Fix 5 broken links in docs/quick-start/README.md - Fix image path in docs/getting-started.md (../images -> ./images) - Update Storybook URL to current domain (getstorybook.io -> storybook.js.org) - Reconcile version requirements across docs to match gemspec: - Shakapacker 6+ (7+ recommended) instead of "7+ required" - Ruby 3.0+ (required) instead of "Ruby 2.7+ supported" - Rails 5.2+ supported for consistency 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]>
📋 Code Review for Documentation Improvements PRThank you for this comprehensive documentation update! The improvements significantly enhance the developer experience. Here's my detailed review: ✅ Strengths🎯 Excellent User Journey Optimization
📚 Content Quality
🔧 Technical Accuracy
🚨 Critical Issues to Address1. Missing Newlines at End of FilesPer CLAUDE.md requirements, ALL files must end with a newline character. The following new files are missing trailing newlines:
Fix: Add a newline at the end of each file. 2. Inconsistent Code Block Language SpecifiersSeveral places use "
|
- Update internal anchor links to include emoji prefixes for proper GitHub anchor generation - Fixes 5 dead anchor links: #installation-issues, #build-issues, #runtime-issues, #server-side-rendering-issues, #performance-issues 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]>
There was a problem hiding this comment.
Actionable comments posted: 3
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
docs/getting-started.md (2)
146-158: Fix JSX: use native h1 tag instead of undefined H1 component.Avoid confusing readers with an undeclared component.
Apply this diff:
- return () => ( - <div> - Your locale is {railsContext.i18nLocale}.<br /> - Hello, {props.name}! - </div> - ); + return () => ( + <div> + Your locale is {railsContext.i18nLocale}.<br /> + <h1>Hello, {props.name}!</h1> + </div> + );
1-254: Fix docs: remove stray@component_name, correct uppercase JSX tag, and add an automated CI check
- docs/getting-started.md:99 — replace the misleading
@component_nametext with a string example (e.g.'component_name'or"HelloWorld") so it’s clear the helper expects a string, not an instance variable.- docs/getting-started.md:199 — change
return () => <H1>{JSON.stringify(props)}</H1>;to use a lowercase HTML tag (<h1>…</h1>) or a real component name if intended.- Add a CI lint step (ripgrep) to fail on lingering placeholders / bad JSX in docs, e.g.:
rg -n -F -e '@component_name' -e '' -e '
' --type=md && exit 1
🧹 Nitpick comments (10)
docs/javascript/angular-js-integration-migration.md (1)
21-21: Fix heading casing: “Storybook” (not “StoryBook”).Align the section heading with the corrected link text/brand.
Apply this diff:
-## StoryBook +## Storybookdocs/troubleshooting/README.md (3)
47-47: Use a proper heading instead of emphasis (MD036).Convert emphasized “Error …” line to a subheading for consistency.
Apply this diff:
-**Error in browser console or webpack output** +#### Error in browser console or webpack output
126-126: Use a proper heading instead of emphasis (MD036).Same issue as above in the SSR section.
Apply this diff:
-**Error during server-side rendering** +#### Error during server-side rendering
226-231: Fix bundle analysis command (manifest.json is not a valid input).webpack-bundle-analyzer expects a stats file or plugin output. Use the ANALYZE flow or point to a stats file.
Apply this diff:
-3. **Check for large dependencies:** - ```bash - yarn why package-name - webpack-bundle-analyzer public/packs/manifest.json - ``` +3. **Check for large dependencies:** + ```bash + yarn why package-name + # If your project is configured to emit stats, analyze them: + npx webpack-bundle-analyzer tmp/webpack-stats.json + # Or use the built-in analyze mode: + ANALYZE=true bin/webpack + ```docs/quick-start/README.md (2)
37-42: Align generator output list with new paths/conventions.“client/” is legacy; the guide uses app/javascript/src and ror_components. Update bullets for consistency.
Apply this diff:
-- jsx files created -- Shakapacker install -- React component files in `client/` -- A sample controller and view -- Webpack configuration +- JSX/TSX files created +- Shakapacker install +- React component files in `app/javascript/src/.../ror_components/` +- A sample controller and view +- Webpack configuration
204-209: Update “Key File Locations” to match auto-bundling conventions.Use ror_components and clarify entrypoints/registration.
Apply this diff:
-### Key File Locations - -- **Components**: `client/app/bundles/[ComponentName]/components/` -- **Registration**: `client/app/bundles/[ComponentName]/startup/registration.js` -- **Packs**: `app/javascript/packs/` -- **Config**: `config/initializers/react_on_rails.rb` -- **Webpack**: `config/shakapacker.yml` +### Key File Locations + +- **Components (auto-bundling)**: `app/javascript/src/[Feature]/ror_components/` +- **Registration (manual only)**: your entrypoints (e.g., `app/javascript/packs/hello-world-bundle.js`) +- **Entrypoints (packs)**: `app/javascript/packs/` (or `app/packs/` depending on `shakapacker.yml`) +- **Config (React on Rails)**: `config/initializers/react_on_rails.rb` +- **Config (Shakapacker)**: `config/shakapacker.yml`docs/getting-started.md (4)
69-75: Simplify dev commands; clarify comments.The three lines are confusing. Keep the primary command and optional notes.
Apply this diff:
-```bash -bin/dev help -bin/dev # start with hmr -bin/dev static # -``` +```bash +./bin/dev # Starts Rails + webpack-dev-server with HMR (per Procfile.dev) +```
81-82: Fix link text to match target path.Avoid mismatched text (“docs/basics/…”) linking to guides/.
Apply this diff:
-- Configure `config/initializers/react_on_rails.rb`. You can adjust some necessary settings and defaults. See file [docs/basics/configuration.md](./guides/configuration.md) for documentation of all configuration options. +- Configure `config/initializers/react_on_rails.rb`. You can adjust some necessary settings and defaults. See [Configuration](./guides/configuration.md) for documentation of all configuration options.
110-115: Correct example path for entrypoint file.Use a realistic Shakapacker path for packs/entrypoints.
Apply this diff:
-// packs/hello-world-bundle.js +// app/javascript/packs/hello-world-bundle.js
180-185: Fix wording: “which we call a ‘render-function’.”Minor clarity/grammar improvement.
Apply this diff:
-You can either register the React component (either function or class component) directly, or you can create a function that returns a React component, which we using the name of a "render-function". Creating a render-function allows you to: +You can either register the React component (function or class) directly, or create a function that returns a React component, which we call a "render-function". Creating a render-function allows you to:
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (5)
docs/README.md(1 hunks)docs/getting-started.md(7 hunks)docs/javascript/angular-js-integration-migration.md(1 hunks)docs/quick-start/README.md(1 hunks)docs/troubleshooting/README.md(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (1)
- docs/README.md
🧰 Additional context used
📓 Path-based instructions (2)
{Gemfile,Rakefile,**/*.{rb,rake,gemspec,ru,js,jsx,ts,tsx,json,yml,yaml,md,css,scss}}
📄 CodeRabbit inference engine (CLAUDE.md)
Ensure all committed files end with a trailing newline character
Files:
docs/javascript/angular-js-integration-migration.mddocs/getting-started.mddocs/quick-start/README.mddocs/troubleshooting/README.md
**/*.{js,jsx,ts,tsx,json,yml,yaml,md,css,scss}
📄 CodeRabbit inference engine (CLAUDE.md)
Let Prettier handle all non-Ruby file formatting; never manually format these files
Files:
docs/javascript/angular-js-integration-migration.mddocs/getting-started.mddocs/quick-start/README.mddocs/troubleshooting/README.md
🧠 Learnings (5)
📚 Learning: 2025-04-26T21:55:55.874Z
Learnt from: alexeyr-ci2
PR: shakacode/react_on_rails#1732
File: spec/dummy/client/app-react16/startup/ReduxSharedStoreApp.client.jsx:40-44
Timestamp: 2025-04-26T21:55:55.874Z
Learning: In the react_on_rails project, files under `app-react16` directories are copied/moved to corresponding `/app` directories during the conversion process (removing the `-react16` suffix), which affects their relative import paths at runtime.
Applied to files:
docs/getting-started.md
📚 Learning: 2025-09-16T08:01:11.146Z
Learnt from: justin808
PR: shakacode/react_on_rails#1770
File: lib/generators/react_on_rails/templates/base/base/app/javascript/src/HelloWorld/ror_components/HelloWorld.client.jsx:2-2
Timestamp: 2025-09-16T08:01:11.146Z
Learning: React on Rails uses webpack CSS Modules configuration with namedExports: true, which requires the import syntax `import * as style from './file.module.css'` rather than the default export pattern. This configuration enables better tree shaking and bundle size optimization for CSS modules.
Applied to files:
docs/getting-started.mddocs/quick-start/README.md
📚 Learning: 2025-02-18T13:08:01.477Z
Learnt from: AbanoubGhadban
PR: shakacode/react_on_rails#1644
File: lib/react_on_rails/helper.rb:190-197
Timestamp: 2025-02-18T13:08:01.477Z
Learning: RSC support validation in React on Rails Pro is handled through a chain of validations:
1. Pro version check in `run_stream_inside_fiber`
2. RSC support check during pack generation via `ReactOnRailsPro.configuration.enable_rsc_support`
3. RSC support validation during component registration
This makes additional validation in the helper methods unnecessary.
Applied to files:
docs/getting-started.md
📚 Learning: 2025-02-12T16:38:06.537Z
Learnt from: Romex91
PR: shakacode/react_on_rails#1697
File: package-scripts.yml:28-28
Timestamp: 2025-02-12T16:38:06.537Z
Learning: The file `node_package/lib/ReactOnRails.full.js` is autogenerated during the build process and should not be present in the repository.
Applied to files:
docs/getting-started.md
📚 Learning: 2025-09-15T21:24:48.207Z
Learnt from: AbanoubGhadban
PR: shakacode/react_on_rails#1781
File: node_package/src/ClientSideRenderer.ts:82-95
Timestamp: 2025-09-15T21:24:48.207Z
Learning: In React on Rails, the force_load feature includes both explicit `data-force-load="true"` usage and the ability to hydrate components during the page loading state (`document.readyState === 'loading'`). Both capabilities require a Pro license, so the condition `!railsContext.rorPro && (isComponentForceLoaded || document.readyState === 'loading')` correctly gates both scenarios.
Applied to files:
docs/getting-started.md
🪛 markdownlint-cli2 (0.18.1)
docs/quick-start/README.md
170-170: Heading levels should only increment by one level at a time
Expected: h3; Actual: h4
(MD001, heading-increment)
docs/troubleshooting/README.md
14-14: Link fragments should be valid
(MD051, link-fragments)
47-47: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
126-126: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (8)
- GitHub Check: dummy-app-integration-tests (3.2, 20)
- GitHub Check: dummy-app-integration-tests (3.4, 22)
- GitHub Check: rspec-package-tests (3.4, minimum)
- GitHub Check: rspec-package-tests (3.2, minimum)
- GitHub Check: rspec-package-tests (3.2, latest)
- GitHub Check: rspec-package-tests (3.4, latest)
- GitHub Check: markdown-link-check
- GitHub Check: build
🔇 Additional comments (4)
docs/javascript/angular-js-integration-migration.md (1)
23-23: Correct Storybook brand/style update.Good catch updating the URL and casing.
docs/getting-started.md (2)
17-19: Grammar: add missing article in heading.This was flagged previously; please apply.
Apply this diff:
-### 📚 **Want comprehensive tutorial?** +### 📚 **Want a comprehensive tutorial?**
99-100: Clarify component name (remove Ruby sigil).Using “@component_name” suggests a Ruby ivar; use a plain identifier.
Apply this diff:
-`@component_name` is a string and corresponds to the name you used to globally expose your React component. +The component name is a string and must match the name you globally exposed for your React component.docs/troubleshooting/README.md (1)
1-305: Trailing newlines present — no changes needed.Verified: docs/troubleshooting/README.md, docs/quick-start/README.md, docs/getting-started.md, docs/javascript/angular-js-integration-migration.md all end with a newline.
| Note, your layout needs to include this in the <head>: | ||
|
|
||
| ```erb | ||
| <%= stylesheet_pack_tag %> | ||
| <%= javascript_pack_tag %> | ||
| ``` | ||
|
|
There was a problem hiding this comment.
Fix pack tag usage in layout example.
Helpers require entrypoint names. Provide a realistic example.
Apply this diff:
-Note, your layout needs to include this in the <head>:
+Note, your layout needs to include your entrypoints in the <head> (example uses "application"):
```erb
- <%= stylesheet_pack_tag %>
- <%= javascript_pack_tag %>
+<%= stylesheet_pack_tag 'application', media: 'all' %>
+<%= javascript_pack_tag 'application' %>
<details>
<summary>🤖 Prompt for AI Agents</summary>
In docs/quick-start/README.md around lines 127 to 133, the layout example uses
stylesheet_pack_tag and javascript_pack_tag without required entrypoint names;
update the example to call the helpers with a realistic entrypoint (e.g.,
'application') and include the media attribute for the stylesheet: replace the
two tag lines with calls that pass 'application' to both helpers and add media:
'all' to the stylesheet helper so the example reflects valid usage.
</details>
<!-- fingerprinting:phantom:triton:chinchilla -->
<!-- This is an auto-generated comment by CodeRabbit -->
| - ✅ Installed and configured React on Rails | ||
| - ✅ Seen server-side rendering in action | ||
| - ✅ Experienced hot module reloading | ||
| - ✅ Created and used a custom React component with auto-bundling | ||
| - ✅ Passed props from Rails to React | ||
| - ✅ Used zero-configuration automatic bundling (no manual pack setup!) | ||
|
|
There was a problem hiding this comment.
Remove inaccurate SSR claim or show how to enable it.
The steps don't demonstrate prerendering. Either remove the SSR bullet or add a step using prerender: true.
Apply this diff to remove the claim:
- ✅ Seen server-side rendering in actionOptionally, add a short SSR example after Step 5:
+### Optional: Enable Server-Side Rendering
+
+```erb
+<%= react_component("SimpleCounter", { initialCount: 5 }, { auto_load_bundle: true, prerender: true }) %>
+```🤖 Prompt for AI Agents
In docs/quick-start/README.md around lines 149 to 155, the checklist incorrectly
claims server-side rendering (SSR) without demonstrating it; either remove the
"✅ Seen server-side rendering in action" bullet or add instructions to enable
SSR by setting prerender: true when rendering components. To fix: delete the SSR
checklist line if you want to avoid claiming it, or keep the line and add a
short example after Step 5 showing how to call react_component with prerender
enabled and auto_load_bundle true (i.e., show the erb invocation with prerender:
true) so the docs actually demonstrate prerendering.
| | Problem Area | Quick Check | Go to Section | | ||
| | -------------------- | ------------------------------------------- | -------------------------------------------- | | ||
| | **Installation** | Generator fails or components don't appear | [Installation Issues](#-installation-issues) | | ||
| | **Compilation** | Webpack errors, build failures | [Build Issues](#-build-issues) | | ||
| | **Runtime** | Components not rendering, JavaScript errors | [Runtime Issues](#-runtime-issues) | | ||
| | **Server Rendering** | SSR not working, hydration mismatches | [SSR Issues](#-server-side-rendering-issues) | | ||
| | **Performance** | Slow builds, large bundles, memory issues | [Performance Issues](#-performance-issues) | | ||
|
|
There was a problem hiding this comment.
🛠️ Refactor suggestion
Fix invalid anchor fragments in the table (MD051).
The emoji-prefixed headings generate anchors without a leading hyphen. Update links to valid fragments.
Apply this diff:
-| **Installation** | Generator fails or components don't appear | [Installation Issues](#-installation-issues) |
-| **Compilation** | Webpack errors, build failures | [Build Issues](#-build-issues) |
-| **Runtime** | Components not rendering, JavaScript errors | [Runtime Issues](#-runtime-issues) |
-| **Server Rendering** | SSR not working, hydration mismatches | [SSR Issues](#-server-side-rendering-issues) |
-| **Performance** | Slow builds, large bundles, memory issues | [Performance Issues](#-performance-issues) |
+| **Installation** | Generator fails or components don't appear | [Installation Issues](#installation-issues) |
+| **Compilation** | Webpack errors, build failures | [Build Issues](#build-issues) |
+| **Runtime** | Components not rendering, JavaScript errors | [Runtime Issues](#runtime-issues) |
+| **Server Rendering** | SSR not working, hydration mismatches | [SSR Issues](#server-side-rendering-issues) |
+| **Performance** | Slow builds, large bundles, memory issues | [Performance Issues](#performance-issues) |📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| | Problem Area | Quick Check | Go to Section | | |
| | -------------------- | ------------------------------------------- | -------------------------------------------- | | |
| | **Installation** | Generator fails or components don't appear | [Installation Issues](#-installation-issues) | | |
| | **Compilation** | Webpack errors, build failures | [Build Issues](#-build-issues) | | |
| | **Runtime** | Components not rendering, JavaScript errors | [Runtime Issues](#-runtime-issues) | | |
| | **Server Rendering** | SSR not working, hydration mismatches | [SSR Issues](#-server-side-rendering-issues) | | |
| | **Performance** | Slow builds, large bundles, memory issues | [Performance Issues](#-performance-issues) | | |
| | Problem Area | Quick Check | Go to Section | | |
| | -------------------- | ------------------------------------------- | -------------------------------------------- | | |
| | **Installation** | Generator fails or components don't appear | [Installation Issues](#installation-issues) | | |
| | **Compilation** | Webpack errors, build failures | [Build Issues](#build-issues) | | |
| | **Runtime** | Components not rendering, JavaScript errors | [Runtime Issues](#runtime-issues) | | |
| | **Server Rendering** | SSR not working, hydration mismatches | [SSR Issues](#server-side-rendering-issues) | | |
| | **Performance** | Slow builds, large bundles, memory issues | [Performance Issues](#performance-issues) | |
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
14-14: Link fragments should be valid
(MD051, link-fragments)
🤖 Prompt for AI Agents
In docs/troubleshooting/README.md around lines 9 to 16, the table's "Go to
Section" links use fragment identifiers with a leading hyphen (e.g.
[Installation Issues](#-installation-issues)) which are invalid per MD051;
remove the leading hyphen from each fragment so they match the generated anchors
(e.g. change #-installation-issues to #installation-issues, #‑build-issues to
#build-issues, #‑runtime-issues to #runtime-issues,
#‑server-side-rendering-issues to #server-side-rendering-issues, and
#‑performance-issues to #performance-issues).
- Simplify docs/README.md for GitHub users: - Direct users to website first - Keep valuable learning paths from PR #1813 - Keep popular use cases table - Add documentation categories overview - Remove duplicate content (now in introduction.md) - Reduced from 173 lines to 65 lines - Enhance introduction.md: - Add missing react_on_rails_demo_ssr_hmr example repo - Now has all 3 example repos (spec/dummy, demo SSR/HMR, live reactrails.com) Purpose: docs/README.md serves GitHub users browsing repo structure, while introduction.md serves as website homepage. Different audiences, minimal duplication.
- Simplify docs/README.md for GitHub users: - Direct users to website first - Keep valuable learning paths from PR #1813 - Keep popular use cases table - Add documentation categories overview - Remove duplicate content (now in introduction.md) - Reduced from 173 lines to 65 lines - Enhance introduction.md: - Add missing react_on_rails_demo_ssr_hmr example repo - Now has all 3 example repos (spec/dummy, demo SSR/HMR, live reactrails.com) Purpose: docs/README.md serves GitHub users browsing repo structure, while introduction.md serves as website homepage. Different audiences, minimal duplication.
- Simplify docs/README.md for GitHub users: - Direct users to website first - Keep valuable learning paths from PR #1813 - Keep popular use cases table - Add documentation categories overview - Remove duplicate content (now in introduction.md) - Reduced from 173 lines to 65 lines - Enhance introduction.md: - Add missing react_on_rails_demo_ssr_hmr example repo - Now has all 3 example repos (spec/dummy, demo SSR/HMR, live reactrails.com) Purpose: docs/README.md serves GitHub users browsing repo structure, while introduction.md serves as website homepage. Different audiences, minimal duplication.
This category index file was an orphaned remnant from PR #1813 that used a different navigation approach with category landing pages. During the IA redesign (PR #1845), similar category index files like guides/advanced/README.md were deleted as "redundant" because docs/README.md now serves as the single navigation hub. The api-reference/README.md survived by accident and is now the only category with such an index file, creating inconsistency. Changes: - Deleted docs/api-reference/README.md (7-line TOC) - Updated docs/README.md reference to point directly to view-helpers-api.md (the main API reference file) - Preserves existing folder-level link on line 50 that points to api-reference/ Rationale: Category folders don't need README indexes when the main docs hub already provides navigation. This matches the pattern established when we deleted guides/advanced/README.md.
- Simplify docs/README.md for GitHub users: - Direct users to website first - Keep valuable learning paths from PR #1813 - Keep popular use cases table - Add documentation categories overview - Remove duplicate content (now in introduction.md) - Reduced from 173 lines to 65 lines - Enhance introduction.md: - Add missing react_on_rails_demo_ssr_hmr example repo - Now has all 3 example repos (spec/dummy, demo SSR/HMR, live reactrails.com) Purpose: docs/README.md serves GitHub users browsing repo structure, while introduction.md serves as website homepage. Different audiences, minimal duplication.
This category index file was an orphaned remnant from PR #1813 that used a different navigation approach with category landing pages. During the IA redesign (PR #1845), similar category index files like guides/advanced/README.md were deleted as "redundant" because docs/README.md now serves as the single navigation hub. The api-reference/README.md survived by accident and is now the only category with such an index file, creating inconsistency. Changes: - Deleted docs/api-reference/README.md (7-line TOC) - Updated docs/README.md reference to point directly to view-helpers-api.md (the main API reference file) - Preserves existing folder-level link on line 50 that points to api-reference/ Rationale: Category folders don't need README indexes when the main docs hub already provides navigation. This matches the pattern established when we deleted guides/advanced/README.md.
1 participant
🎯 Summary
This PR consolidates and enhances React on Rails documentation with a focus on improving developer onboarding, user experience, and clarity. The changes combine the best improvements from previous documentation efforts while maintaining compatibility and accuracy.
📊 Key Improvements
🚀 New Documentation Resources
✨ Enhanced Existing Documentation
🔧 Technical Updates
auto_load_bundle: trueinstead of manual registration💡 User Experience Benefits
For New Users
For Experienced Developers
For AI Coding Agents
📈 Content Organization Improvements
🔗 Related Context
This PR consolidates improvements from multiple documentation enhancement efforts:
📋 Files Changed
New Files
AI_AGENT_INSTRUCTIONS.md- Setup guide for AI coding agentsdocs/README.md- Documentation navigation hubdocs/quick-start/README.md- 15-minute hands-on tutorialdocs/troubleshooting/README.md- Comprehensive troubleshooting guideDOCS_PR_SUMMARY.md- This documentation effort summaryEnhanced Files
README.md- Modernized main project READMEdocs/getting-started.md- Enhanced with user paths and system requirements✅ Quality Assurance
🤖 Generated with Claude Code
Co-Authored-By: Claude [email protected]
This change is
Summary by CodeRabbit