shakacode · ihabadham · Oct 7, 2025 · Oct 8, 2025 · Oct 8, 2025 · Oct 8, 2025
diff --git a/docs/README.md b/docs/README.md
@@ -1,14 +1,8 @@
 # React on Rails Documentation
 
-> **Integrate React components seamlessly into your Rails application with server-side rendering, hot reloading, and more.**
+> For the best experience, visit our **[documentation website](https://www.shakacode.com/react-on-rails/docs/)**.
 
-## 🚀 Quick Start
-
-New to React on Rails? Start here for the fastest path to success:
-
-**→ [15-Minute Quick Start Guide](./getting-started/quick-start.md)**
-
-Already have Rails + Shakapacker? **→ [Add to existing app guide](./getting-started/installation-into-an-existing-rails-app.md)**
+Browsing on GitHub? This guide will help you navigate the documentation.
 
 ## 📚 Learning Paths
 
@@ -18,17 +12,17 @@ Choose your journey based on your experience level:
 
 Perfect if you're new to React on Rails
 
-1. **[Quick Start](./getting-started/quick-start.md)** - Get your first component running
-2. **[Core Concepts](./getting-started.md)** - Understand the basics
-3. **[Tutorial](./getting-started/tutorial.md)** - Build something useful
+1. **[Introduction](./introduction.md)** - What is React on Rails and why use it?
+2. **[Quick Start](./getting-started/quick-start.md)** - Get your first component running in 15 minutes
+3. **[Tutorial](./getting-started/tutorial.md)** - Build a complete app with Redux and routing
 
 ### ⚡ **Experienced Developer Path**
 
-Jump to what you need
+Jump straight to what you need
 
-- **[Installation Guide](./getting-started/installation-into-an-existing-rails-app.md)** - Detailed setup
-- **[API Reference](./api-reference/README.md)** - Quick lookup
-- **[Advanced Features](./guides/advanced/README.md)** - SSR, Redux, Router
+- **[Installation Guide](./getting-started/installation-into-an-existing-rails-app.md)** - Add to existing Rails app
+- **[API Reference](./api-reference/view-helpers-api.md)** - View helpers, configuration, JavaScript API
+- **[Core Concepts](./core-concepts/how-react-on-rails-works.md)** - Architecture and SSR
 
 ### 🏗️ **Migrating from Other Solutions**
 
@@ -48,125 +42,23 @@ Find guidance for your specific scenario:
 | **Deploy to production**            | [Deployment Guide](./deployment/deployment.md)                                        |
 | **Troubleshoot issues**             | [Troubleshooting](./deployment/troubleshooting.md)                                    |
 
-## 📖 Complete Documentation
-
-### Core Guides
-
-- **[Getting Started](./getting-started.md)** - Installation and basic setup
-- **[Tutorial](./getting-started/tutorial.md)** - Complete walkthrough with examples
-- **[Configuration](./api-reference/configuration.md)** - All configuration options
-- **[View Helpers](./api-reference/view-helpers-api.md)** - Using `react_component` method
-
-### Features
-
-- **[Server-Side Rendering](./core-concepts/react-server-rendering.md)** - SSR setup and optimization
-- **[Auto-Bundling](./core-concepts/auto-bundling-file-system-based-automated-bundle-generation.md)** - Automatic bundle generation
-- **[Redux Integration](./building-features/react-and-redux.md)** - State management with Redux
-- **[React Router](./building-features/react-router.md)** - Client-side routing
-- **[Internationalization](./building-features/i18n.md)** - I18n support
-
-### Development
-
-- **[Hot Module Replacement](./building-features/hmr-and-hot-reloading-with-the-webpack-dev-server.md)** - Fast development workflow
-- **[Testing](./building-features/rspec-configuration.md)** - Testing React components
-- **[Debugging](./deployment/troubleshooting-build-errors.md)** - Common debugging techniques
-
-### Deployment & Performance
+## 📖 Documentation Categories
 
-- **[Deployment](./deployment/deployment.md)** - Production deployment guide
-- **[Performance](./core-concepts/webpack-configuration.md)** - Optimization techniques
-- **[Bundle Optimization](./core-concepts/webpack-configuration.md)** - Reduce bundle size
+- **[Getting Started](./getting-started/)** - Installation, quick start, tutorial
+- **[Core Concepts](./core-concepts/)** - How React on Rails works, SSR, auto-bundling
+- **[Building Features](./building-features/)** - Redux, routing, i18n, testing
+- **[API Reference](./api-reference/)** - View helpers, configuration, JavaScript API
+- **[Deployment](./deployment/)** - Production deployment and troubleshooting
+- **[Upgrading](./upgrading/)** - Version upgrade guides
+- **[Migrating](./migrating/)** - From other frameworks
+- **[Pro](./pro/)** - React on Rails Pro features
 
 ## 🆘 Need Help?
 
-### Quick Solutions
-
 - **[Troubleshooting Guide](./deployment/troubleshooting.md)** - Common issues and solutions
-- **[FAQ](./deployment/troubleshooting.md)** - Frequently asked questions
-- **[Error Messages](./deployment/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:[email protected])** - 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
+- **[React on Rails Pro](https://www.shakacode.com/react-on-rails-pro/)** - Advanced features and professional support
 
 ---
 
-## 📚 Table of Contents
-
-### API Reference
-
-- [View Helpers API](./api-reference/view-helpers-api.md)
-- [Redux Store API](./api-reference/redux-store-api.md)
-- [JavaScript API](./api-reference/javascript-api.md)
-
-### Guides
-
-#### Getting Started
-
-- [Installation](./getting-started.md)
-- [Tutorial](./getting-started/tutorial.md)
-- [Basic Configuration](./api-reference/configuration.md)
-
-#### Core Features
-
-- [Server-Side Rendering](./core-concepts/react-server-rendering.md)
-- [Component Registration](./core-concepts/render-functions-and-railscontext.md)
-- [Props and RailsContext](./core-concepts/render-functions-and-railscontext.md)
-
-#### State Management
-
-- [Redux Integration](./building-features/react-and-redux.md)
-- [Context API](./core-concepts/render-functions-and-railscontext.md)
-
-#### Routing
-
-- [React Router Setup](./building-features/react-router.md)
-- [Server-Side Routing](./core-concepts/react-server-rendering.md)
-
-#### Advanced Topics
-
-- [Webpack Configuration](./core-concepts/webpack-configuration.md)
-- [Code Splitting](./building-features/code-splitting.md)
-- [Performance Optimization](./core-concepts/webpack-configuration.md)
-
-#### Development
-
-- [Hot Module Replacement](./building-features/hmr-and-hot-reloading-with-the-webpack-dev-server.md)
-- [Testing Components](./building-features/rspec-configuration.md)
-- [Debugging](./deployment/troubleshooting-build-errors.md)
-
-#### Deployment
-
-- [Production Setup](./deployment/deployment.md)
-- [Heroku Deployment](./deployment/deployment.md)
-- [Docker Setup](./deployment/deployment.md)
-
-### Migration Guides
-
-- [Upgrading React on Rails](./upgrading/upgrading-react-on-rails.md)
-- [From react-rails gem](./migrating/migrating-from-react-rails.md)
-
-### Troubleshooting
-
-- [Common Issues](./deployment/troubleshooting.md)
-- [Error Messages](./deployment/troubleshooting-build-errors.md)
-- [Performance Issues](./deployment/troubleshooting-build-errors.md)
-
-### Contributing
-
-- [Contributing Guide](../CONTRIBUTING.md)
-- [Development Setup](../CONTRIBUTING.md)
-- [Pull Request Guidelines](../CONTRIBUTING.md)
+**💡 Tip:** For the best reading experience with full navigation and search, visit the [documentation website](https://www.shakacode.com/react-on-rails/docs/).
diff --git a/docs/advanced-topics/manual-installation-overview.md b/docs/advanced-topics/manual-installation-overview.md
diff --git a/docs/advanced-topics/rails-engine-integration.md b/docs/advanced-topics/rails-engine-integration.md
@@ -1,3 +1,5 @@
+# Integrating React on Rails with Rails Engines
+
 ## In your engine
 
 - 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`
 
 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`.
 
-# Github Issues
+## Github Issues
 
 - [Integration with an engine #342](https://github.com/shakacode/react_on_rails/issues/342)
 - [Feature: target destination option for the install generator #459](https://github.com/shakacode/react_on_rails/issues/459)

diff --git a/docs/api-reference/README.md b/docs/api-reference/README.md
diff --git a/docs/api-reference/configuration.md b/docs/api-reference/configuration.md
@@ -1,3 +1,5 @@
+# React on Rails Configuration Options
+
 Here is the full set of config options. This file is `/config/initializers/react_on_rails.rb`
 
 First, you should have a `/config/shakapacker.yml` setup.

diff --git a/docs/api-reference/generator-details.md b/docs/api-reference/generator-details.md
@@ -39,20 +39,80 @@ Then you may run
 
 Another good option is to create a simple test app per the [Tutorial](../getting-started/tutorial.md).
 
-# Understanding the Organization of the Generated Client Code
+## Understanding the Organization of the Generated Client Code
 
-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_.
+The React on Rails generator creates different directory structures depending on whether you use the `--redux` option.
 
-Inside the generated "HelloWorld" domain you will find the following folders:
+### Default Structure (Without Redux)
 
-- `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.
-- `containers`: contains "smart components" (components that have functionality and logic that is passed to child "dumb components").
-- `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.
+The basic generator creates a simple, flat structure optimized for auto-bundling:
 
-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).
+```
+app/javascript/
+└── src/
+    └── HelloWorld/
+        └── ror_components/          # Components auto-registered by React on Rails
+            ├── HelloWorld.jsx       # Your React component
+            ├── HelloWorld.module.css
+            └── HelloWorld.server.js # Optional: separate server rendering logic
+```
+
+- **`src/`**: Source directory for all React components
+- **`ror_components/`**: Directory name is configurable via `config.components_subdirectory` in `config/initializers/react_on_rails.rb`
+- **Auto-registration**: Components in `ror_components/` directories are automatically discovered and registered when using `auto_load_bundle: true`
+
+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`).
+
+### Redux Structure (With `--redux` Option)
+
+The Redux generator creates a more structured organization with familiar Redux patterns:
+
+```
+app/javascript/
+└── src/
+    └── HelloWorldApp/
+        ├── actions/                 # Redux action creators
+        │   └── helloWorldActionCreators.js
+        ├── components/              # Presentational components
+        │   ├── HelloWorld.jsx
+        │   └── HelloWorld.module.css
+        ├── constants/               # Action type constants
+        │   └── helloWorldConstants.js
+        ├── containers/              # Connected components (smart components)
+        │   └── HelloWorldContainer.js
+        ├── reducers/                # Redux reducers
+        │   └── helloWorldReducer.js
+        ├── ror_components/          # Auto-registered entry points
+        │   ├── HelloWorldApp.client.jsx
+        │   └── HelloWorldApp.server.jsx
+        └── store/                   # Redux store configuration
+            └── helloWorldStore.js
+```
+
+This structure follows Redux best practices:
+
+- **`components/`**: Presentational "dumb" components that receive data via props
+- **`containers/`**: Container "smart" components connected to Redux store
+- **`actions/`** and **`reducers/`**: Standard Redux patterns
+- **`ror_components/`**: Entry point files that initialize Redux and render the app
+
+### TypeScript Support
+
+The generator also supports a `--typescript` option for generating TypeScript files:
+
+```bash
+rails generate react_on_rails:install --typescript
+```
+
+This creates `.tsx` files instead of `.jsx` and adds TypeScript configuration.
+
+### Auto-Bundling and Component Registration
 
-## Redux
+Modern React on Rails uses auto-bundling to eliminate manual webpack configuration. Components placed in the configured `components_subdirectory` (default: `ror_components`) are automatically:
 
-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.
+1. Discovered by the generator
+2. Bundled into separate webpack entry points
+3. Registered for use with `react_component` helper
+4. Loaded on-demand when used in views
 
-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`.
+For detailed information on auto-bundling, see the [Auto-Bundling Guide](../core-concepts/auto-bundling-file-system-based-automated-bundle-generation.md).
diff --git a/docs/api-reference/redux-store-api.md b/docs/api-reference/redux-store-api.md
@@ -98,7 +98,7 @@ This method has the same API as the controller extension. **HOWEVER**, we recomm
 
 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).
 
-# More Details
+## More Details
 
 - [lib/react_on_rails/controller.rb](https://github.com/shakacode/react_on_rails/tree/master/lib/react_on_rails/controller.rb) source
 - [lib/react_on_rails/helper.rb](https://github.com/shakacode/react_on_rails/tree/master/lib/react_on_rails/helper.rb) source