You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
docs: Entry Point Consolidation and Tutorial Improvements (#1860)
* Remove orphaned docs/guides/advanced/README.md
This navigation index file was left behind after the reorganization in #1845.
The links it contained point to files now in core-concepts/, making this
index redundant.
Cleanup after PR #1845.
* Create introduction.md and remove redundant overview
- Add docs/introduction.md as unified homepage
- Explains what React on Rails is and why to use it
- Clear when to use / when not to use decision guide
- Three clear paths: Quick Start, Installation, Tutorial
- Built from actual docs (overview, doctrine, system requirements)
- Added community stat (thousands of production sites)
- Delete docs/core-concepts/react-on-rails-overview.md
- Content consolidated into introduction.md
- Outdated prerequisites (Rails >=5 vs current Rails 7+)
- Creates confusion with two similar entry points
- Update links to overview.md:
- docs/home.md: Overview → Introduction
- docs/misc/doctrine.md: Overview → Introduction
Solves Problem 1.2 (Multiple Conflicting Entry Points) from docs improvement plan.
Next: Handle remaining entry point files (home.md, README.md, getting-started.md).
* Simplify docs/README.md and enhance introduction.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.
* Update ia-redesign-live.md with Phase 3 progress
Document completion of entry point consolidation work:
- Created introduction.md
- Deleted overview.md
- Simplified docs/README.md
- Updated folder structure to reflect changes
Next: Delete home.md, handle getting-started.md
* Delete docs/home.md - replaced by introduction.md
- Was the current website homepage (29 lines of links)
- All valuable content already in introduction.md or README.md
- No unique content lost (example repos, use cases, help links all covered)
- Replaced by introduction.md as new website homepage
Updated ia-redesign-live.md to reflect completion.
Next: Extract content from getting-started.md then delete it.
* Transform getting-started.md into understanding-react-on-rails.md
Transform docs/getting-started.md (253 lines) into a focused conceptual
guide: docs/getting-started/understanding-react-on-rails.md (238 lines).
Changes:
- Removed redundant sections (Choose Starting Point, System Requirements, More Reading)
- Transformed installation section into brief conceptual overview with links
- Kept and refined: Basic Usage, Auto-Bundling, Render-Functions, Error Handling
- Added clear 'Next Steps' section with organized learning paths
- Updated link in quick-start.md to point to new file
- Deleted original docs/getting-started.md
Purpose: This is now a conceptual journey guide explaining how React on Rails
works, complementing the hands-on tutorial and quick-start guides. Addresses
user feedback that tutorial was too overwhelming and mixed audiences.
Next: Website config updates (keeping for last as requested)
* Rename understanding-react-on-rails.md to using-react-on-rails.md
Rationale:
- "understanding" is vague and confusing next to how-react-on-rails-works.md
- "using" clearly indicates practical usage guide
- Better distinction: how-react-on-rails-works.md (architecture) vs using-react-on-rails.md (practical usage)
Changes:
- Renamed docs/getting-started/understanding-react-on-rails.md → using-react-on-rails.md
- Updated link in quick-start.md
- Updated references in ia-redesign-live.md
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* Improve tutorial: extract Heroku deployment, fix versions, reorganize structure
Changes to tutorial.md:
1. Replaced Heroku deployment section (139 lines) with brief Deployment section linking to deployment guides
2. Updated versions: Ruby 2.7 → 3.0+, Rails 5.1.3 → 7.0+, RoR v13 → v16
3. Clarified Redux usage: tutorial demonstrates Redux, but basic installer uses Hooks (user choice)
4. Merged duplicate HMR sections into one cohesive section using ./bin/dev
5. Renamed "Other features" → "Going Further" with better organization:
- Server Rendering (important)
- Optional Configuration subsection (/client structure, Cloud9, RubyMine)
Changes to heroku-deployment.md:
1. Merged tutorial's detailed Heroku instructions with existing guide
2. Added note about older versions with link to current Heroku Rails 7 guide
3. Organized into clear sections: Create App, Buildpacks, Postgres, Puma, Node/Yarn, Assets, Deploy
Rationale:
- Tutorial was overwhelming with platform-specific deployment before core features
- Heroku content now in dedicated guide (reusable, maintainable)
- Clear separation: tutorial teaches React on Rails, deployment guides teach platforms
- Better progression: install → run → features → deploy → advanced
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* Delete outdated manual-installation-overview.md
Rationale:
- File has been outdated since 2018 (had "TODO: Review this file" for 7 years)
- Confused purpose: title says "Manual Installation" but subtitle says "summarizes what generator does"
- Outdated content: references /client directory, webpacker, missing auto-bundling
- No clear use case: rails generate react_on_rails:install IS the manual installation (not external CLI like create-react-app)
- Content is better covered in:
- how-react-on-rails-works.md (architecture)
- using-react-on-rails.md (usage)
- Generator source code (what files are created)
Changes:
- Deleted docs/advanced-topics/manual-installation-overview.md
- Removed link in installation-into-an-existing-rails-app.md
- Updated ia-redesign-live.md tracker
Decision discussed with team in Slack. Can be reverted if use case is identified.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* Update IA redesign plan to reflect Phase 3 completion
Mark Phase 3 as completed with notes on what actually happened vs what was planned:
- ✅ Created introduction.md (as planned)
- ✅ Transformed getting-started.md → using-react-on-rails.md (adapted from original plan)
- ✅ Simplified README.md (kept, not deleted)
- ✅ Deleted home.md (as planned)
- ✅ Added tutorial improvements (discovered during work)
- ✅ Deleted manual-installation-overview.md (discovered during work)
- ✅ Updated cross-references manually (not scripted)
Updated testing checklist to show what's complete and what's deferred to Phase 1.
* linting
* Fix MDX parsing error in quick-start.md
Escape <head> tag in prose to prevent MDX from expecting closing tag.
Changed "in the <head>:" to "in the `<head>` section:" to use inline code.
This fixes gatsby-plugin-mdx compilation error:
"Expected a closing tag for <head> before the end of paragraph"
* Fix documentation H1 headings for improved search indexing
Add missing H1 headings and improve H1 quality across 10 documentation
files to enable proper Algolia search indexing and improve accessibility.
Critical fixes (missing H1):
- configuration.md: Add "React on Rails Configuration Options"
- react-on-rails-pro.md: Change H2 to H1
- rails-engine-integration.md: Add "Integrating React on Rails with Rails Engines"
- troubleshooting-when-using-webpacker.md: Add H1 and fix structure
- troubleshooting-when-using-shakapacker.md: Add H1 and fix heading hierarchy
- credits.md: Add "React on Rails Credits and Authors"
Quality improvements (better searchability):
- images.md: "Images" → "Configuring Images and Assets with Webpack"
- foreman-issues.md: "Foreman Issues" → "Troubleshooting Foreman with React on Rails"
- updating-dependencies.md: "Updating Dependencies" → "Updating Ruby and JavaScript Dependencies"
- api-reference/README.md: "API Reference" → "React on Rails API Reference Guide"
Why: Algolia indexes H1 as primary title. Files without H1 show as
"Untitled" in search results. Generic H1s reduce searchability.
Reference: docs/planning/docs-improvement/h1-headings-audit-report.md
(local file, not tracked)
* Fix multiple H1 headings in documentation for improved search indexing
Continue fixing H1 heading issues by addressing files with multiple H1s.
Demoted duplicate H1s to H2 throughout documentation while maintaining
proper heading hierarchy (H1→H2→H3→H4).
Files changed:
- tutorial.md: Demoted 6 H1s (Table of Contents, Installation, HMR, Deployment, Going Further, Conclusion)
- rails-engine-integration.md: Changed "Github Issues" H1 to H2
- hmr-and-hot-reloading-with-the-webpack-dev-server.md: Fixed 2 H1s with proper hierarchy
- i18n.md: "Notes" H1 to H2
- react-and-redux.md: "Redux Reducers" H1 to H2
- react-router.md: "Server Rendering Using React Router V4" H1 to H2
- rspec-configuration.md: 2 H1s to H2s
- generator-details.md: "Understanding the Organization..." H1 to H2
- redux-store-api.md: "More Details" H1 to H2
- view-helpers-api.md: "More details" H1 to H2
- style.md: "Git Usage" H1 to H2
Rationale: Multiple H1s per document confuse Algolia search ranking,
screen readers, and violate accessibility standards. Each document
should have exactly one H1 as the main title.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* Restructure turbolinks.md to clarify Turbo vs legacy Turbolinks
Reorganize turbolinks.md content to clearly separate modern Turbo
(recommended) from legacy Turbolinks support. All Turbolinks v2 and v5
content is now properly nested under "Legacy Turbolinks Support" section.
Key structural changes:
- "Using Turbo" section remains at H2 level (modern, recommended approach)
- Created "Legacy Turbolinks Support" H2 section with clear deprecation notice
- Nested all Turbolinks content as H3-H5 subsections:
- Why Turbolinks? (H3)
- Requirements and "Why Not" sections (H3)
- Installation details with checklists (H3→H4→H5)
- Turbolinks 5 Specific Information (H3)
- Technical Details and Troubleshooting (H3→H4)
Content improvements:
- Added explicit support status for Turbolinks 5.x and 2.x
- Clarified auto-detection behavior for legacy versions
- Moved CSRF/MIME type technical details under proper troubleshooting section
- Updated messaging from "may be outdated" to "still supported, migrate when possible"
Rationale: Based on codebase investigation (pageLifecycle.ts, turbolinksUtils.ts),
Turbo is the recommended navigation system since 2021. All Turbolinks versions
are legacy but still supported. Original flat structure mixed modern and legacy
content without clear distinction, potentially confusing users about which system
to use.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* Modernize generator and project structure documentation
This commit updates documentation that was 9.5 years outdated, removing
references to directory structures and patterns that haven't existed since
2016 and replacing them with accurate modern (2025) guidance.
## Changes to docs/api-reference/generator-details.md
- Replace outdated structure description with accurate modern organization
- Document both non-Redux and Redux generator structures separately
- Add visual directory trees showing actual generated code locations
- Document previously undocumented --typescript option
- Remove references to non-existent app/lib folder (removed Apr 2016)
- Remove incorrect path app/javascript/app/bundles (never existed - was docs typo)
- Add auto-bundling explanation with cross-reference
- Show real component structure: src/ComponentName/ror_components/
## Changes to docs/building-features/react-router.md
- Update path reference from legacy client/app/bundles to modern src/ structure
- Clarify this example applies to --redux generator option
- Make path reference generic rather than specific to outdated structure
## Changes to docs/getting-started/project-structure.md
Complete rewrite to reflect modern React on Rails:
### Removed outdated content:
- Old bundles/ structure presented as current (was 2015-2016 pattern)
- "Moving node_modules to /client" section (tested and proven broken with Shakapacker)
- References to /client/app/assets directory (generator stopped creating in Apr 2016)
- Outdated CSS/assets management discussion
### Added modern content:
- Modern auto-bundling structure as recommended approach
- Traditional manual structure as legacy option with clear use cases
- Decision guide for choosing between approaches
- CSS Modules documentation (default in generator since modern versions)
- Real code examples from actual generator templates
- Rails Asset Pipeline as alternative approach
- Advanced global styles pattern
## Historical Context
Research revealed:
- Oct 2015: Generator created client/app/lib/middlewares/ and client/app/bundles/
- Apr 5, 2016: Docs added describing app/lib folder
- Apr 23, 2016: Generator removed these directories (18 days later!)
- Apr 2016 - Oct 2025: Docs never updated - outdated for 9.5 years
## Testing Performed
Created test app at /home/ihab/ihab/work/shakacode/test/default-structure-test/:
- Verified default generator creates src/ structure, not bundles/
- Verified CSS modules co-located with components
- Tested /client conversion: works perfectly (just move + config change)
- Tested moving node_modules to /client: FAILS with Shakapacker
- Confirmed SHAKAPACKER_CONFIG env var doesn't solve the issue
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* Update React Router documentation and spec/dummy to v6
This major update modernizes React Router integration from outdated v4/v5
to current v6 API, fixing critical gaps discovered through testing.
Documentation Changes (docs/building-features/react-router.md):
- Remove 5-year-old "needs updating" warning
- Pin React Router to v6 (^6.0.0) with explanation about v7 incompatibility
- Add critical "Rails Routes Configuration" section with wildcard routing
- Update all code examples to React Router v6 API:
* Switch → Routes
* component prop → element prop
* StaticRouter import from 'react-router-dom/server'
- Add path matching guidance (React Router paths must match Rails routes)
- Update Turbolinks → Turbo/Turbolinks with Rails version context
- Improve clarity: generator doesn't create React Router code
- Add installation instructions and compatibility notes
spec/dummy Updates (v5→v6 migration):
- client/app/routes/routes.jsx: Add Routes wrapper, wildcard path support
- client/app/components/RouterLayout.jsx: Switch→Routes, use relative paths
- client/app/startup/RouterApp.server.jsx: Update StaticRouter import location
- package.json: Upgrade react-router-dom from ^5.2.0 to ^6.0.0
- yarn.lock: Update dependencies (@remix-run/router@1.23.0)
Key Discoveries from Testing:
1. React Router v7 merged with Remix, incompatible with our SSR approach
2. Rails wildcard routing is CRITICAL but was never documented
3. Documentation examples were 9+ years misleading about generator output
4. StaticRouter import location changed in v6 (breaks without this update)
Testing:
- Created fresh test app following documentation step-by-step
- Validated client-side routing, SSR, direct URL visits, browser navigation
- Confirmed spec/dummy React Router demo works with v6 API
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* Modernize process manager documentation
Replace outdated foreman-issues.md with comprehensive process-managers.md guide.
Changes:
- Create docs/building-features/process-managers.md with modern guidance
- Documents both Overmind (recommended) and Foreman
- Explains why React on Rails needs multiple processes
- Includes authoritative explanation from Foreman's wiki about not bundling
- Shows how bin/dev works under the hood
- Move docs/building-features/foreman-issues.md to docs/outdated/
- Preserves 2017-era bug reports for historical reference
- Removes clutter from main docs (outdated/ filtered from navigation)
- Update lib/react_on_rails/dev/process_manager.rb
- Change link from our old doc to official Foreman wiki
- Users get explanation directly from authoritative source
Addresses feedback that foreman-issues.md was outdated and didn't mention
modern alternatives like Overmind (which bin/dev actually prefers).
* Move outdated code-splitting.md to outdated/ and update references
The code-splitting.md file was explicitly marked as "(Outdated)" and
directed users to contact justin@shakacode.com instead of following it.
The modern solution is React on Rails Pro's loadable-components guide.
Changes:
- Moved docs/building-features/code-splitting.md → docs/outdated/code-splitting.md
- Updated API reference to point to Pro loadable-components (appropriate for reference docs)
- Removed outdated code-splitting links from beginner guides (quick-start, using-react-on-rails)
- Updated planning doc to track the move
Rationale:
- File content from 2017 for React Router v3/v4 with ExecJS
- Uses deprecated patterns (manual renderer functions, webpack v1)
- Example uses abandoned react-s3-uploader package
- Pro's loadable-components doc (updated Sept 2022) provides modern approach
- Uses @loadable/component (React team's official recommendation)
- Both docs solve the same problem: code splitting WITH SSR
- Outdated doc itself says to contact Justin about loadable-components
Decision: Keep Pro feature out of beginner docs to avoid confusion about
whether Pro is required. Only mention in API reference where advanced
users look for specific features.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* Fix broken links to outdated/webpack.md
Two user-facing docs were linking to docs/outdated/webpack.md which is
excluded from the website, causing 404 errors.
Changes:
- docs/core-concepts/webpack-configuration.md: Updated to link to Shakapacker's
webpack customization docs (most relevant for users customizing webpack)
- docs/deployment/troubleshooting-build-errors.md: Updated to link to our own
webpack-configuration.md (keeps users in our documentation)
Context:
webpack.md was moved to outdated/ in commit e08f91d (Oct 3, 2025) because
it contained "outdated Webpack v2 content". The file references Webpack v2
patterns and links to a 2017 forum post. These two links were not updated
when the file was moved, causing broken references.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* Remove outdated documentation folder
The docs/outdated/ folder contained deprecated content that was excluded from
the website build. This content is preserved in git history and can be
accessed through previous commits if needed.
Deleted files:
- docs/outdated/code-splitting.md
- docs/outdated/converting-from-custom-webpack-config-to-rails-webpacker-config.md
- docs/outdated/deferred-rendering.md
- docs/outdated/foreman-issues.md
- docs/outdated/rails-assets-relative-paths.md
- docs/outdated/rails-assets.md
- docs/outdated/rails3.md
- docs/outdated/tips-for-usage-with-sp6.md
- docs/outdated/upgrade-webpacker-v3-to-v4.md
- docs/outdated/webpack-v1-notes.md
- docs/outdated/webpack.md
This cleanup follows the recommendation to rely on git history rather than
maintaining hidden documentation in the main branch.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* Fix failing RSpec test after process manager docs update
Updated test expectation to match the new Foreman documentation link.
In commit 6cc93c7, we updated lib/react_on_rails/dev/process_manager.rb
to link to Foreman's official wiki instead of our outdated foreman-issues.md.
The test was still expecting the old link pattern.
Change:
- Old expectation: /foreman-issues\.md/
- New expectation: /Don't-Bundle-Foreman/
This matches the new error message which now points to:
https://github.com/ddollar/foreman/wiki/Don't-Bundle-Foreman
Fixes the failing spec:
ReactOnRails::Dev::ProcessManager.show_process_manager_installation_help
displays helpful error message with installation instructions
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* Fix broken markdown links to turbolinks.md
Updated two broken links in react-router.md that were pointing to the old
location ../rails/turbolinks.md which no longer exists.
The turbolinks.md file was moved from docs/rails/ to docs/building-features/
during the PR #1845 documentation reorganization, but these links were not
updated at that time.
Changes:
- ../rails/turbolinks.md → ./turbolinks.md (same directory)
This fixes the markdown-link-check CI failure:
ERROR: 1 dead link found in docs/building-features/react-router.md !
[✖] ../rails/turbolinks.md → Status: 400
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* Enable React Router v7 future flags to silence warnings in tests
Added future flags to BrowserRouter in the dummy app to enable v7-compatible
behavior and eliminate console warnings that were causing test failures.
Changes:
- spec/dummy/client/app/startup/RouterApp.client.jsx: Added future prop with
v7_startTransition and v7_relativeSplatPath flags
Why this fixes the issue:
The dummy app integration tests were failing because selenium_logger.rb treats
JavaScript console warnings as errors. React Router v6 emits warnings about
upcoming v7 changes:
⚠️ React Router Future Flag Warning: React Router will begin wrapping state
updates in React.startTransition in v7. You can use the v7_startTransition
future flag to opt-in early.
⚠️ React Router Future Flag Warning: Relative route resolution within Splat
routes is changing in v7. You can use the v7_relativeSplatPath future flag
to opt-in early.
By enabling these flags, we:
1. Silence the warnings
2. Adopt v7-compatible behavior early
3. Demonstrate best practices for React Router v6 users
4. Align with React Router's official migration guide
Reference: https://reactrouter.com/upgrading/future
Fixes test failures:
- React Router when rendering /react_router is expected to have text "Woohoo..."
- React Router when rendering /react_router clicking links correctly renders...
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* Fix documentation issues identified in PR review
Addresses valid issues from Claude's PR review:
1. Fixed JavaScript syntax error in using-react-on-rails.md:192
- Changed semicolon to comma in object destructuring example
- Was accidentally introduced during linting commit
2. Clarified Rails version requirements in tutorial.md
- Changed "We support Rails 6 and later" to "This tutorial targets Rails 7.0+"
- Explicitly noted Rails 6 is supported but tutorial uses Rails 7
- Removed version confusion between prerequisites and tutorial steps
3. Fixed markdownlint issues
- Added language hint to code fence in using-react-on-rails.md (text)
- Added language hint to Procfile code fence in heroku-deployment.md (procfile)
These changes ensure code examples are syntactically correct and version
requirements are clear for users following the tutorial.
* typo
* Remove redundant api-reference/README.md
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.
* fix dead link
* another dead link
* Update Node.js requirement from 18+/16 to 20+ across documentation
Fixes Node version inconsistencies identified by CodeRabbit in PR #1860.
Changes:
- docs/introduction.md: 18+ → 20+
- docs/getting-started/quick-start.md: 18+ → 20+
- docs/deployment/heroku-deployment.md: 16.19.0 → 20.0.0
Rationale:
- React on Rails v16 requires Node 20+ for ESM module support
- Node 16 reached EOL in September 2023
- Node 18 reaches EOL in April 2025
- CI currently tests only Node 20 and 22
- Release notes specify Node 20.19.0+ or 22.12.0+ required
The tutorial.md (line 7) says "Updated for React on Rails v16" and
users following it would use Node 20+, so deployment guide should
match to avoid confusion.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* Fix broken React Router v6 migration guide link
The link was returning 404. Updated from the incorrect path:
- /en/main/upgrading/v5 (broken)
to the working path:
- /docs/en/v6/upgrading/v5 (verified working)
This link was added in commit 391281a when updating React Router
documentation to v6. The URL structure changed on reactrouter.com.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* Fix inconsistent link text in how-to-conditionally-server-render doc
Update link display text from 'here in docs/basics/configuration.md' to 'available here' to match the actual URL path (docs/api-reference/configuration/)
Co-authored-by: Ihab Adham <ihabadham@users.noreply.github.com>
* Document Turbo integration and immediate_hydration feature (resolve TODO)
Replace TODO from PR #1620 with comprehensive Turbo documentation covering
both free (Turbo Frames) and Pro (Turbo Streams) features.
Changes:
1. **New "Using Turbo" Section**
- Installation steps (turbo-rails gem + @hotwired/turbo-rails package)
- Basic configuration (ReactOnRails.setOptions({ turbo: true }))
- Turbo Frames usage (free, works out of the box)
- Turbo Streams usage (requires immediate_hydration: true - Pro feature)
- Complete working example with turbo_frame_tag and turbo_stream.update
- Links to v16.0 release notes, streaming docs, and spec/dummy example
2. **Migration Context**
- Note about force_load → immediate_hydration rename in v16.0
- Clear distinction between free vs Pro features
- Explanation of WHY Turbo Streams need immediate_hydration
(they don't dispatch turbo:render events, directly manipulate DOM)
3. **Improved Async Scripts Warning**
- Replaced confusing "Do not use immediate_hydration: false" warning
- New clear warning: "Async Scripts with Turbolinks Require Pro Feature"
- Explains the race condition problem
- Provides three alternatives with behavioral descriptions:
* defer (waits for full page load before hydration)
* Upgrade to Turbo (recommended)
* Use Pro for immediate_hydration: true
Technical Context:
- PR #1620 (Aug 2024) added force_load for Turbo Streams
- PR #1781 (Sep 2025) renamed to immediate_hydration + made Pro-only
- Feature still actively used (spec/dummy has working example)
- Default immediate_hydration: false causes race conditions with async scripts
Resolves TODO on line 16 left by Justin in PR #1620 comments.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* Remove confusing "(Free)" label from Turbo Basic Setup heading
The "(Free)" label in "### Basic Setup (Free)" was confusing because:
- Appears before any mention of Pro features
- Not used elsewhere in the codebase
- Readers don't know what it's contrasting with yet
- The Pro callout box later provides sufficient contrast
Changed to simply "### Basic Setup" to match patterns used in other docs
like streaming-server-rendering.md.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* Fix multiple H1 headings in client-vs-server-rendering.md
Changed second H1 to H2 for proper document structure:
- Line 21: "# Different Server-Side Rendering Code" → "## Different..."
Having multiple H1s in a document is problematic for:
- SEO (search engines expect one H1 per page)
- Accessibility (screen readers use heading hierarchy)
- Documentation systems (assume H1 is the page title)
- Navigation/table of contents generation
The second heading is a subtopic about techniques for having different
client/server code, so it should be H2 under the main page topic.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
---------
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: Ihab Adham <ihabadham@users.noreply.github.com>
**💡 Tip:** For the best reading experience with full navigation and search, visit the [documentation website](https://www.shakacode.com/react-on-rails/docs/).
Copy file name to clipboardExpand all lines: docs/advanced-topics/rails-engine-integration.md
+3-1Lines changed: 3 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,3 +1,5 @@
1
+
# Integrating React on Rails with Rails Engines
2
+
1
3
## In your engine
2
4
3
5
- At the top of `config/initializers/react_on_rails.rb`
@@ -30,7 +32,7 @@ As far as solving the assets issue, `lib/tasks/assets.rake` in `react_on_rails`
30
32
31
33
Another solution would be to detach this rake task from the `rails assets:precompile` task. This can be done by adding `REACT_ON_RAILS_PRECOMPILE=false` to your environment. If you do so, then React assets will have to be bundled separately from `rails assets:precompile`.
32
34
33
-
# Github Issues
35
+
##Github Issues
34
36
35
37
-[Integration with an engine #342](https://github.com/shakacode/react_on_rails/issues/342)
36
38
-[Feature: target destination option for the install generator #459](https://github.com/shakacode/react_on_rails/issues/459)
Copy file name to clipboardExpand all lines: docs/api-reference/generator-details.md
+70-10Lines changed: 70 additions & 10 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -39,20 +39,80 @@ Then you may run
39
39
40
40
Another good option is to create a simple test app per the [Tutorial](../getting-started/tutorial.md).
41
41
42
-
# Understanding the Organization of the Generated Client Code
42
+
##Understanding the Organization of the Generated Client Code
43
43
44
-
The generated client code follows our organization scheme. Each unique set of functionality is given its own folder inside of `app/javascript/app/bundles`. This encourages modularity of _domains_.
44
+
The React on Rails generator creates different directory structures depending on whether you use the `--redux` option.
45
45
46
-
Inside the generated "HelloWorld" domain you will find the following folders:
46
+
### Default Structure (Without Redux)
47
47
48
-
-`startup`: contains the entry point files for webpack. It defaults to a single file that is used for both server and client compilation. But if these need to be different, then you can create two Webpack configurations with separate endpoints. Since RoR v14.2 this is strongly recommended because the client can import `react-on-rails/client` instead of `react-on-rails` for decreased bundle size.
49
-
-`containers`: contains "smart components" (components that have functionality and logic that is passed to child "dumb components").
50
-
-`components`: contains "dumb components", or components that simply render their properties and call functions given to them as properties by a parent component. Ultimately, at least one of these dumb components will have a parent container component.
48
+
The basic generator creates a simple, flat structure optimized for auto-bundling:
51
49
52
-
You may also notice the `app/lib` folder. This is for any code that is common between bundles and therefore needs to be shared (for example, middleware).
50
+
```
51
+
app/javascript/
52
+
└── src/
53
+
└── HelloWorld/
54
+
└── ror_components/ # Components auto-registered by React on Rails
55
+
├── HelloWorld.jsx # Your React component
56
+
├── HelloWorld.module.css
57
+
└── HelloWorld.server.js # Optional: separate server rendering logic
58
+
```
59
+
60
+
-**`src/`**: Source directory for all React components
61
+
-**`ror_components/`**: Directory name is configurable via `config.components_subdirectory` in `config/initializers/react_on_rails.rb`
62
+
-**Auto-registration**: Components in `ror_components/` directories are automatically discovered and registered when using `auto_load_bundle: true`
63
+
64
+
For components that need different client vs. server implementations, use `.client.jsx` and `.server.jsx` suffixes (e.g., `HelloWorld.client.jsx` and `HelloWorld.server.jsx`).
65
+
66
+
### Redux Structure (With `--redux` Option)
67
+
68
+
The Redux generator creates a more structured organization with familiar Redux patterns:
This creates `.tsx` files instead of `.jsx` and adds TypeScript configuration.
108
+
109
+
### Auto-Bundling and Component Registration
53
110
54
-
## Redux
111
+
Modern React on Rails uses auto-bundling to eliminate manual webpack configuration. Components placed in the configured `components_subdirectory` (default: `ror_components`) are automatically:
55
112
56
-
If you have used the `--redux` generator option, you will notice the familiar additional redux folders in addition to the aforementioned folders. The Hello World example has also been modified to use Redux.
113
+
1. Discovered by the generator
114
+
2. Bundled into separate webpack entry points
115
+
3. Registered for use with `react_component` helper
116
+
4. Loaded on-demand when used in views
57
117
58
-
Note the organizational paradigm of "bundles". These are like application domains and are used for grouping your code into webpack bundles, in case you decide to create different bundles for deployment. This is also useful for separating out logical parts of your application. The concept is that each bundle will have it's own Redux store. If you have code that you want to reuse across bundles, including components and reducers, place them under `/client/app/lib`.
118
+
For detailed information on auto-bundling, see the [Auto-Bundling Guide](../core-concepts/auto-bundling-file-system-based-automated-bundle-generation.md).
Copy file name to clipboardExpand all lines: docs/api-reference/redux-store-api.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -98,7 +98,7 @@ This method has the same API as the controller extension. **HOWEVER**, we recomm
98
98
99
99
Place this view helper (no parameters) at the end of your shared layout so ReactOnRails will render the redux store hydration data. Since we're going to be setting up the stores in the controllers, we need to know where on the view to put the client-side rendering of this hydration data, which is a hidden div with a matching class that contains a data props. For an example, see [spec/dummy/app/views/layouts/application.html.erb](https://github.com/shakacode/react_on_rails/tree/master/spec/dummy/app/views/layouts/application.html.erb).
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4&size=40){kind=avatar}
0 commit comments