Skip to content

README.md

Latest commit

 

History

History
196 lines (136 loc) · 8.86 KB

README.md

File metadata and controls

196 lines (136 loc) · 8.86 KB

React on Rails Demo: SSR, Auto-Registration & Bundle Splitting with v15 and Rails 8

A fully working demo of React on Rails v15 on Rails 8, showcasing server-side rendering, auto-registration, and bundle splitting capabilities. This demo also demonstrates the corrected installation sequence that fixes the infamous "package.json not found" error.

React on Rails Rails React Shakapacker Auto-Registration

✅ Includes:

  • Server-Side Rendering (SSR) - React components render on the server for faster initial page loads
  • Auto-Registration - Components in file system are automatically discovered and registered
  • Bundle Splitting - Automatic code splitting for optimized loading performance (12.5KB vs 1.1MB+ bundles)
  • CSS Modules - Scoped CSS with automatic class name generation
  • Multiple Dev Modes - HMR, static, and production-like development servers
  • Rails 8 Integration - Latest Rails version with modern asset pipeline
  • Installation Fix - Corrected Shakapacker → React on Rails sequence

📂 Repo name: react_on_rails-demo-v15-ssr-auto-registration-bundle-splitting

📚 Part of the React on Rails Demo Series

⚠️ Important: Known Issue with Packs Generation

There's a bug in the react_on_rails:generate_packs task with CSS modules (see #1768).

Problem: The generator creates invalid JavaScript syntax when handling CSS modules:

// ❌ Invalid (generated)
import HelloWorld.module from '../ror_components/HelloWorld.module.css';
ReactOnRails.register({HelloWorld, HelloWorld.module});

Workaround: After running the generator, manually fix the generated files by removing CSS module imports from the server bundle:

// ✅ Fixed (manual)
import ReactOnRails from 'react-on-rails';
import HelloWorld from '../ror_components/HelloWorld.jsx';

ReactOnRails.register({HelloWorld});

This demo has been manually fixed to work correctly with SSR.

🎯 What This Demo Solves

This sample application demonstrates the critical fix for the React on Rails installation issue where generators would fail with:

ERROR: package.json not found

The Solution: Install Shakapacker BEFORE React on Rails, not after.

📚 Documentation Guide

This demo includes comprehensive documentation for both developers and AI coding agents:

🚀 Quick Start & Setup

🏗️ Technical Deep Dives

✨ Features Demonstrated

  • ✅ Auto-Registration - Zero manual ReactOnRails.register() and append_javascript_pack_tag calls needed due to File-System Based Detection - Components auto-discovered from directory structure
  • ✅ Bundle Splitting - Lightweight (12.5KB) vs Heavy (1.1MB+) component demos
  • ✅ Server-Side Rendering - Both components work with SSR enabled
  • ✅ Modern Development Tools - Enhanced bin/dev script with 3 modes
  • ✅ Production-Ready Patterns - Dynamic imports, skeleton loaders, CSS modules

🚀 Quick Start

Prerequisites: GitHub Packages Authentication

This demo uses React on Rails Pro from GitHub Packages. While RORP will be open source soon, it currently requires authentication with your Pro subscription token.

  1. Configure npm for GitHub Packages:

    npm config set @shakacode-tools:registry https://npm.pkg.github.com
npm config set //npm.pkg.github.com/:_authToken YOUR_PRO_TOKEN

  2. Configure Bundler for GitHub Packages:

    bundle config rubygems.pkg.github.com YOUR_PRO_TOKEN

Installation

# Clone the demo repository
git clone https://github.com/shakacode/react_on_rails-demo-v15-ssr-auto-registration-bundle-splitting.git
cd react_on_rails-demo-v15-ssr-auto-registration-bundle-splitting

# Install dependencies (after configuring GitHub Packages above)
bundle install && npm install

# Start development server
./bin/dev

# Visit the demo
open http://localhost:3000

Note: Without GitHub Packages authentication, bundle install and npm install will fail when trying to download react_on_rails_pro and @shakacode-tools/react-on-rails-pro-node-renderer.

🌐 Demo Components

🔧 Development Commands

  • ./bin/dev - Start development server (3 modes available)
    • ./bin/dev - HMR mode (default, may have FOUC)
    • ./bin/dev static - Static mode (no FOUC, no HMR)
    • ./bin/dev prod - Production-optimized mode (port 3001)
  • bundle exec rake react_on_rails:generate_packs - Regenerate webpack entries (now with enhanced error display)
  • ./bin/dev help - Show all available modes

🔄 Upgrading React on Rails

After upgrading to a new major version, run the generator to get latest defaults:

rails generate react_on_rails:install

Important: Review changes carefully before applying to avoid overwriting custom configurations. The generator updates:

  • bin/dev (improved development workflow)
  • webpack configurations
  • shakapacker.yml settings
  • other configuration files

🎯 Key Architectural Concepts

This demo showcases React on Rails v15's file-system-based auto-registration:

  • Magic Directory: Components in app/javascript/src/ComponentName/ror_components/ are automatically discovered
  • Auto-Generated Entries: rake react_on_rails:generate_packs creates webpack bundles
  • Zero Manual Registration: No ReactOnRails.register() calls needed
  • Bundle Splitting: Each component gets its own optimized bundle

🔗 Related Resources

📊 Performance Metrics

Component Bundle Size Dependencies Load Time Use Case
HelloWorld 12.5KB React basics Instant Lightweight UI
HeavyMarkdownEditor 1.1MB+ 58+ libraries ~200ms Rich features

Bundle Splitting Benefit: HelloWorld loads 50% faster by avoiding heavy markdown dependencies!

⭐ Why This Demo Matters

This sample application fixes a critical bug in the official React on Rails installation documentation and demonstrates production-ready patterns:

  • 🐛 Fixes Installation Bug: Corrects the "package.json not found" error with proper Shakapacker → React on Rails sequence
  • 🚀 Modern Architecture: File-system-based auto-registration eliminates manual configuration
  • 📦 Performance: Intelligent bundle splitting for optimal loading
  • 🔧 Developer Experience: Enhanced development tools with multiple testing modes

Perfect for: Learning React on Rails v15, understanding bundle splitting, or using as a reference implementation.

🔧 Troubleshooting

Socket Path Too Long Error

If you see this error:

error connecting to /private/tmp/tmux-501/overmind-react-on-rails-demo-v15... (File name too long)

Solution: The project directory name is too long for tmux socket paths. We've included a .overmind.env file with shorter paths, but if you still encounter issues:

  1. The .overmind.env file sets: OVERMIND_SOCKET=/tmp/ror-demo.sock and OVERMIND_TITLE=ror-demo
  2. Alternative: Set environment variables manually: export OVERMIND_SOCKET=/tmp/ror.sock
  3. Or use foreman instead: gem install foreman && foreman start -f Procfile.dev

⭐ Star this project if it helped you!