📚 Comprehensive documentation improvements for enhanced developer experience

AI_AGENT_INSTRUCTIONS.md

@@ -0,0 +1,63 @@
+# 🤖 AI Agent Instructions: React on Rails Setup
+
+_Super concise, copy-paste instructions for AI agents to set up React on Rails in common scenarios._
+
+## 🔍 **Before Starting: Check Current Versions**
+
+```bash
+# Get latest available versions (recommended approach)
+gem search react_on_rails --remote
+```
+
+Install and update gem and npm package using strict option.
+
+---
+
+## 🆕 Scenario 1: New Rails App with React on Rails
+
+```bash
+# Create new Rails app
+rails new myapp --skip-javascript --database=postgresql
+cd myapp
+
+# Use latest version
+bundle add react_on_rails --strict
+
+bin/rails generate react_on_rails:install
+
+# Accept change to bin/dev
+
+# Start development servers
+bin/dev
+```
+
+**✅ Success Check:** Visit `http://localhost:3000/hello_world` → Should see "Hello World" from React
+
+---
+
+## 🔄 Scenario 2: Add React on Rails to Existing Rails App
+
+```bash
+cd /path/to/existing/app
+# Use latest version
+bundle add react_on_rails --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
+```
+
+---
+
+## 🛠️ Common Troubleshooting Commands
+
+- Always run `bin/dev` to test setup, and check browser console for any JavaScript errors
+- `bin/dev kill` stops other conflicting processes
+- `bin/rake react_on_rails:doctor` for helpful information

README.md

@@ -16,7 +16,7 @@
 [![Build Rspec Tests](https://github.com/shakacode/react_on_rails/actions/workflows/rspec-package-specs.yml/badge.svg)](https://github.com/shakacode/react_on_rails/actions/workflows/rspec-package-specs.yml)
 [![Linting](https://github.com/shakacode/react_on_rails/actions/workflows/lint-js-and-ruby.yml/badge.svg)](https://github.com/shakacode/react_on_rails/actions/workflows/lint-js-and-ruby.yml)
 
-# News
+# ⚡ What's New
 
 **🚀 React on Rails v16.0 Released!** Major modernization with ESM support, enhanced React Server Components, and streamlined configuration.
 
@@ -31,11 +31,13 @@
 
 _These are the docs for React on Rails 16. To see the older docs and code: [v14](https://github.com/shakacode/react_on_rails/tree/14.0.0), [v13](https://github.com/shakacode/react_on_rails/tree/13.4.0), [v12](https://github.com/shakacode/react_on_rails/tree/12.6.0), and [v11](https://github.com/shakacode/react_on_rails/tree/11.3.0)._
 
-# About
+# 🎯 About React on Rails
 
-React on Rails integrates Rails with (server rendering of) [React](https://github.com/facebook/react).
+**Seamlessly integrate React components into your Rails application** with server-side rendering, hot reloading, and automatic bundle optimization.
 
-This project is maintained by [ShakaCode](https://www.shakacode.com).
+> **"The easiest way to add React to Rails"** - Thousands of developers rely on React on Rails for production applications.
+
+This project is maintained by [ShakaCode](https://www.shakacode.com) with ❤️ from the Rails and React communities.
 
 ## ShakaCode Upgrade Support
 
@@ -93,30 +95,34 @@ We did this for Popmenu, [lowering Heroku costs 20-25% while getting a 73% decre
 
 If you're interested, read more about [React on Rails Pro](https://www.shakacode.com/react-on-rails-pro/) and [book a call](https://meetings.hubspot.com/justingordon/30-minute-consultation).
 
-# Documentation
+# 📚 Quick Start
+
+**New to React on Rails?** Get up and running in minutes:
 
-See the documentation at **[shakacode.com/react-on-rails/docs](https://www.shakacode.com/react-on-rails/docs/)** and [React on Rails Pro](https://www.shakacode.com/react-on-rails-pro/).
+🚀 **[15-Minute Quick Start](https://www.shakacode.com/react-on-rails/docs/quick-start/)** - Your first React component
+📖 **[Complete Documentation](https://www.shakacode.com/react-on-rails/docs/)** - Comprehensive guides and API reference
+🎮 **[Live Demo](https://reactrails.com)** - See it in action with [source code](https://github.com/shakacode/react-webpack-rails-tutorial)
 
 ## Project Objective
 
 To provide a high-performance framework for integrating Ruby on Rails with React, especially regarding React Server-Side Rendering for better SEO and improved performance.
 
-## Features and Why React on Rails?
-
-Given that `shakacode/shakapacker` gem already provides basic React integration, why would you use "React on Rails"?
-
-1. **Modern ESM-only package** with optimized tree-shaking for smaller bundle sizes and better performance.
-1. **Advanced loading strategies** with `sync`, `async`, and `defer` options for optimal performance based on your needs.
-1. **Automatic configuration** of what bundles are added to the page based on what React components are on the page. This results in faster browser loading time via smaller bundle sizes.
-1. **Keep up with the latest changes** in different versions of React. React 18+ is fully supported with enhanced React Server Components.
-1. **Easy prop passing** directly from your Rails view to your React components rather than having your Rails view load and then make a separate request to your API.
-   Tight integration with [shakapacker](https://github.com/shakacode/shakapacker).
-1. **Server-Side Rendering (SSR)** with enhanced React Server Components support, often used for SEO crawler indexing and UX performance.
-1. **[Automated optimized entry-point creation and bundle inclusion](https://www.shakacode.com/react-on-rails/docs/guides/file-system-based-automated-bundle-generation/)** when placing a component on a page. With this feature, you no longer need to configure `javascript_pack_tags` and `stylesheet_pack_tags` on your layouts based on what's shown. "It just works!"
-1. **[Redux](https://redux.js.org/) and [React Router](https://reactrouter.com/) integration** with server-side-rendering.
-1. **[Internationalization (I18n) and (localization)](https://www.shakacode.com/react-on-rails/docs/guides/i18n)** support.
-1. **Supportive community**. This [web search shows how live public sites are using React on Rails](https://publicwww.com/websites/%22react-on-rails%22++-undeveloped.com+depth%3Aall/).
-1. **[ReScript Support](https://github.com/shakacode/rescript-react-on-rails-example)**.
+## ✨ Why React on Rails?
+
+| Feature                       | Benefit                                                                                                                                                                                      |
+| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 🎯 **Smart Bundle Loading**   | [Automated bundle optimization](./docs/guides/auto-bundling-file-system-based-automated-bundle-generation.md) based on components used - no more manual `javascript_pack_tags` configuration |
+| ⚡ **Server-Side Rendering**  | Enhanced React Server Components support for better SEO and UX performance                                                                                                                   |
+| 🚀 **Advanced Loading**       | `sync`, `async`, and `defer` options for optimal performance based on your needs                                                                                                             |
+| 🔥 **Hot Module Replacement** | Instant feedback during development with tight [Shakapacker](https://github.com/shakacode/shakapacker) integration                                                                           |
+| 📦 **Easy Props Passing**     | Direct Rails → React data flow without separate API calls                                                                                                                                    |
+| 🗺️ **Router Integration**     | [React Router](https://reactrouter.com/) with SSR support                                                                                                                                    |
+| 🏪 **State Management**       | [Redux](https://redux.js.org/) integration with server-side rendering                                                                                                                        |
+| 🌍 **Internationalization**   | [I18n and localization support](https://www.shakacode.com/react-on-rails/docs/guides/i18n) for global apps                                                                                   |
+| 🎨 **Modern React**           | React 18+ with enhanced React Server Components and latest patterns                                                                                                                          |
+| 🦄 **ReScript Support**       | [ReScript integration](https://github.com/shakacode/rescript-react-on-rails-example) for type-safe development                                                                               |
+
+> **Trusted by thousands** - See [real production sites](https://publicwww.com/websites/%22react-on-rails%22++-undeveloped.com+depth%3Aall/) using React on Rails
 
 See [Rails/Shakapacker React Integration Options](https://www.shakacode.com/react-on-rails/docs/guides/rails-webpacker-react-integration-options) for comparisons to other gems.
 

docs/README.md

@@ -0,0 +1,172 @@
+# React on Rails Documentation
+
+> **Integrate React components seamlessly into your Rails application with server-side rendering, hot reloading, and more.**
+
+## 🚀 Quick Start
+
+New to React on Rails? Start here for the fastest path to success:
+
+**→ [15-Minute Quick Start Guide](./quick-start/README.md)**
+
+Already have Rails + Shakapacker? **→ [Add to existing app guide](./guides/installation-into-an-existing-rails-app.md)**
+
+## 📚 Learning Paths
+
+Choose your journey based on your experience level:
+
+### 🔰 **Beginner Path**
+
+Perfect if you're new to React on Rails
+
+1. **[Quick Start](./quick-start/README.md)** - Get your first component running
+2. **[Core Concepts](./getting-started.md)** - Understand the basics
+3. **[Tutorial](./guides/tutorial.md)** - Build something useful
+
+### ⚡ **Experienced Developer Path**
+
+Jump to what you need
+
+- **[Installation Guide](./guides/installation-into-an-existing-rails-app.md)** - Detailed setup
+- **[API Reference](./api/README.md)** - Quick lookup
+- **[Advanced Features](./guides/advanced/README.md)** - SSR, Redux, Router
+
+### 🏗️ **Migrating from Other Solutions**
+
+- **[From react-rails](./additional-details/migrating-from-react-rails.md)** - Switch from the react-rails gem
+- **[Upgrading React on Rails](./guides/upgrading-react-on-rails.md)** - Version upgrade guide
+
+## 🎯 Popular Use Cases
+
+Find guidance for your specific scenario:
+
+| I want to...                        | Go here                                                                    |
+| ----------------------------------- | -------------------------------------------------------------------------- |
+| **Add React to existing Rails app** | [Installation Guide](./guides/installation-into-an-existing-rails-app.md)  |
+| **Enable server-side rendering**    | [SSR Guide](./guides/react-server-rendering.md)                            |
+| **Set up hot reloading**            | [HMR Setup](./guides/hmr-and-hot-reloading-with-the-webpack-dev-server.md) |
+| **Use Redux with Rails**            | [Redux Integration](./javascript/react-and-redux.md)                       |
+| **Deploy to production**            | [Deployment Guide](./guides/deployment.md)                                 |
+| **Troubleshoot issues**             | [Troubleshooting](./troubleshooting/README.md)                             |
+
+## 📖 Complete Documentation
+
+### Core Guides
+
+- **[Getting Started](./getting-started.md)** - Installation and basic setup
+- **[Tutorial](./guides/tutorial.md)** - Complete walkthrough with examples
+- **[Configuration](./guides/configuration.md)** - All configuration options
+- **[View Helpers](./api/view-helpers-api.md)** - Using `react_component` method
+
+### Features
+
+- **[Server-Side Rendering](./guides/react-server-rendering.md)** - SSR setup and optimization
+- **[Auto-Bundling](./guides/auto-bundling-file-system-based-automated-bundle-generation.md)** - Automatic bundle generation
+- **[Redux Integration](./javascript/react-and-redux.md)** - State management with Redux
+- **[React Router](./javascript/react-router.md)** - Client-side routing
+- **[Internationalization](./guides/i18n.md)** - I18n support
+
+### Development
+
+- **[Hot Module Replacement](./guides/hmr-and-hot-reloading-with-the-webpack-dev-server.md)** - Fast development workflow
+- **[Testing](./guides/rspec-configuration.md)** - Testing React components
+- **[Debugging](./javascript/troubleshooting-build-errors.md)** - Common debugging techniques
+
+### Deployment & Performance
+
+- **[Deployment](./guides/deployment.md)** - Production deployment guide
+- **[Performance](./guides/webpack-configuration.md)** - Optimization techniques
+- **[Bundle Optimization](./guides/webpack-configuration.md)** - Reduce bundle size
+
+## 🆘 Need Help?
+
+### Quick Solutions
+
+- **[Troubleshooting Guide](./troubleshooting/README.md)** - Common issues and solutions
+- **[FAQ](./troubleshooting/README.md)** - Frequently asked questions
+- **[Error Messages](./javascript/troubleshooting-build-errors.md)** - Decode error messages
+
+### Community Support
+
+- **[React + Rails Slack](https://reactrails.slack.com)** - Real-time community help
+- **[GitHub Discussions](https://github.com/shakacode/react_on_rails/discussions)** - Ask questions
+- **[GitHub Issues](https://github.com/shakacode/react_on_rails/issues)** - Report bugs
+
+### Professional Support
+
+- **[ShakaCode Support](mailto:react_on_rails@shakacode.com)** - Professional React on Rails help
+- **[React on Rails Pro](https://www.shakacode.com/react-on-rails-pro/)** - Advanced features and support
+
+## 🔗 External Resources
+
+- **[Shakapacker Documentation](https://github.com/shakacode/shakapacker)** - Webpack integration for Rails
+- **[React Documentation](https://react.dev)** - Official React docs
+- **[Rails Guides](https://guides.rubyonrails.org)** - Ruby on Rails documentation
+
+---
+
+## 📚 Table of Contents
+
+### API Reference
+
+- [View Helpers API](./api/view-helpers-api.md)
+- [Redux Store API](./api/redux-store-api.md)
+- [JavaScript API](./api/javascript-api.md)
+
+### Guides
+
+#### Getting Started
+
+- [Installation](./getting-started.md)
+- [Tutorial](./guides/tutorial.md)
+- [Basic Configuration](./guides/configuration.md)
+
+#### Core Features
+
+- [Server-Side Rendering](./guides/react-server-rendering.md)
+- [Component Registration](./guides/render-functions-and-railscontext.md)
+- [Props and RailsContext](./guides/render-functions-and-railscontext.md)
+
+#### State Management
+
+- [Redux Integration](./javascript/react-and-redux.md)
+- [Context API](./guides/render-functions-and-railscontext.md)
+
+#### Routing
+
+- [React Router Setup](./javascript/react-router.md)
+- [Server-Side Routing](./guides/react-server-rendering.md)
+
+#### Advanced Topics
+
+- [Webpack Configuration](./guides/webpack-configuration.md)
+- [Code Splitting](./javascript/code-splitting.md)
+- [Performance Optimization](./guides/webpack-configuration.md)
+
+#### Development
+
+- [Hot Module Replacement](./guides/hmr-and-hot-reloading-with-the-webpack-dev-server.md)
+- [Testing Components](./guides/rspec-configuration.md)
+- [Debugging](./javascript/troubleshooting-build-errors.md)
+
+#### Deployment
+
+- [Production Setup](./guides/deployment.md)
+- [Heroku Deployment](./guides/deployment.md)
+- [Docker Setup](./guides/deployment.md)
+
+### Migration Guides
+
+- [Upgrading React on Rails](./guides/upgrading-react-on-rails.md)
+- [From react-rails gem](./additional-details/migrating-from-react-rails.md)
+
+### Troubleshooting
+
+- [Common Issues](./troubleshooting/README.md)
+- [Error Messages](./javascript/troubleshooting-build-errors.md)
+- [Performance Issues](./javascript/troubleshooting-build-errors.md)
+
+### Contributing
+
+- [Contributing Guide](../CONTRIBUTING.md)
+- [Development Setup](../CONTRIBUTING.md)
+- [Pull Request Guidelines](../CONTRIBUTING.md)

docs/additional-details/recommended-project-structure.md

@@ -19,7 +19,7 @@ you should consider keeping your codebase mostly consistent with the defaults fo
 
 1. Move the directory:
 
-```sh
+```bash
 mv app/javascript client
 ```
 

docs/api/README.md

@@ -0,0 +1,7 @@
+# API Reference
+
+Complete API documentation for React on Rails.
+
+- [View Helpers API](./view-helpers-api.md)
+- [Redux Store API](./redux-store-api.md)
+- [JavaScript API](./javascript-api.md)

docs/contributor-info/pull-requests.md

@@ -35,7 +35,7 @@ From [How to Write a Git Commit Message](http://chris.beams.io/posts/git-commit/
 
 When making doc changes, we want the change to work on both the gitbook and the regular github site. The issue is that non-doc files will not go to the gitbook site, so doc references to non doc files must use the github URL.
 
-### Links to other docs:
+### Links to other docs
 
 - When making references to source code files, use a full GitHub URL, for example:
   `[spec/dummy/config/initializers/react_on_rails.rb](https://github.com/shakacode/react_on_rails/tree/master/spec/dummy/config/initializers/react_on_rails.rb)`