Docs: frame Redux as legacy shared-store guidance

Author: justin808

docs/oss/api-reference/generator-details.md

@@ -1,6 +1,6 @@
 # Generator Details
 
-The `react_on_rails:install` generator combined with the example pull requests of generator runs will get you up and running efficiently. There's a fair bit of setup with integrating a bundler with Rails. Most options default to off — for example, the default for `-R` is that `redux` is off. The exception is the bundler: **fresh installs now default to Rspack**, so pass `--no-rspack` (or its alias `--webpack`) if you want Webpack instead. Existing apps that already declare a bundler in `config/shakapacker.yml` are left unchanged.
+The `react_on_rails:install` generator combined with the example pull requests of generator runs will get you up and running efficiently. There's a fair bit of setup with integrating a bundler with Rails. Most options default to off. The exception is the bundler: **fresh installs now default to Rspack**, so pass `--no-rspack` (or its alias `--webpack`) if you want Webpack instead. Existing apps that already declare a bundler in `config/shakapacker.yml` are left unchanged.
 
 Run `rails generate react_on_rails:install --help` for descriptions of all available options:
 
@@ -9,7 +9,6 @@ Usage:
   rails generate react_on_rails:install [options]
 
 Options:
-  -R, [--redux], [--no-redux]                      # Install Redux package and Redux version of Hello World Example. Default: false
   -T, [--typescript], [--no-typescript]            # Generate TypeScript files and install TypeScript dependencies. Default: false
       [--rspack], [--no-rspack]                    # Use Rspack (default) as the bundler; pass --no-rspack to use Webpack
       [--webpack], [--no-webpack]                  # Use Webpack as the bundler (alias for --no-rspack)
@@ -27,13 +26,17 @@ Runtime options:
 Description:
 
 The react_on_rails:install generator integrates webpack with rails with ease. You
-can pass the redux option if you'd like to have redux setup for you automatically.
-
-* Redux
-
-    Passing the --redux generator option causes the generated Hello World example
-    to integrate the Redux state container framework. The necessary node modules
-    will be automatically included for you.
+can pass the options below to customize the generated example and supporting
+configuration.
+
+> [!WARNING]
+> The Redux installer path (`--redux` / `-R`) is a hidden legacy escape hatch, not
+> a recommended starter architecture. New apps should start with plain
+> `react_component` entries, React local state or context for island-local UI
+> state, and Rails props or server-state tools such as TanStack Query for data
+> loaded from the server. Use Redux only for an existing Redux app or an advanced
+> multi-island page where separate React roots must coordinate through one shared
+> client store.
 
 * TypeScript
 
@@ -82,9 +85,9 @@ Another good option is to create a simple test app per the [Tutorial](../getting
 
 ## Understanding the Organization of the Generated Client Code
 
-The React on Rails generator creates different directory structures depending on whether you use the `--redux` option.
+The React on Rails generator normally creates the simple component structure below. A hidden legacy Redux path remains available for existing apps and recovery work, but it is not the structure recommended for new React on Rails apps.
 
-### Default Structure (Without Redux)
+### Default Structure (Recommended, Without Redux)
 
 The basic generator creates a simple, flat structure optimized for auto-bundling:
 
@@ -104,9 +107,9 @@ app/javascript/
 
 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)
+### Legacy Redux Structure (Hidden `--redux` Path)
 
-The Redux generator creates a more structured organization with familiar Redux patterns:
+The hidden legacy Redux generator creates a more structured organization with familiar Redux patterns:
 
 ```text
 app/javascript/
@@ -130,13 +133,21 @@ app/javascript/
             └── helloWorldStore.js
 ```
 
-This structure follows Redux best practices:
+This legacy structure is useful only when you intentionally maintain Redux:
 
 - **`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
 
+If you already have a React on Rails app and intentionally need to recreate the legacy Redux example, use the direct hidden generator after the base installer has configured React on Rails:
+
+```bash
+rails generate react_on_rails:react_with_redux --typescript
+```
+
+For full install recovery of an older Redux-generated app, the hidden `react_on_rails:install --redux` option still exists, but do not use it for greenfield apps.
+
 ### TypeScript Support
 
 The generator also supports a `--typescript` option for generating TypeScript files:
@@ -206,11 +217,8 @@ For apps with custom webpack configurations, review the generated config templat
 # Rspack (default) with TypeScript
 rails generate react_on_rails:install --typescript
 
-# Webpack with Redux
-rails generate react_on_rails:install --no-rspack --redux
-
-# Explicit Rspack with TypeScript and Redux
-rails generate react_on_rails:install --rspack --typescript --redux
+# Webpack with TypeScript
+rails generate react_on_rails:install --no-rspack --typescript
 ```
 
 For more details on Rspack configuration, see the [Webpack Configuration](../core-concepts/webpack-configuration.md#rspack-vs-webpack) docs.
@@ -246,9 +254,6 @@ For production, configure your license token: `export REACT_ON_RAILS_PRO_LICENSE
 # Pro with TypeScript
 rails generate react_on_rails:install --pro --typescript
 
-# Pro with Redux
-rails generate react_on_rails:install --pro --redux
-
 # Pro with Rspack
 rails generate react_on_rails:install --pro --rspack
 ```
@@ -300,13 +305,12 @@ In addition to all Pro files:
 # RSC with TypeScript
 rails generate react_on_rails:install --rsc --typescript
 
-# RSC with Redux (generates both HelloWorldApp and HelloServer)
-rails generate react_on_rails:install --rsc --redux
-
 # RSC with Rspack
 rails generate react_on_rails:install --rsc --rspack
 ```
 
+Do not combine RSC with the hidden legacy Redux installer for new apps. Existing Redux Client Components can continue to work beside RSC when Redux access stays in Client Components; see [RSC context and state migration](../migrating/rsc-context-and-state.md#redux-toolkit).
+
 **Upgrading an existing Pro app to RSC:**
 
 For existing Pro apps, use the standalone RSC generator:

docs/oss/api-reference/javascript-api.md

@@ -48,9 +48,10 @@ The best source of docs is the `interface ReactOnRails` in [types/index.ts](http
 register(components);
 
 /**
- * Allows registration of store generators to be used by multiple React components on one Rails
- * view. Store generators are functions that take one arg, props, and return a store. Note that
- * the setStore API is different in that it's the actual store hydrated with props.
+ * Allows registration of store generators for legacy or advanced pages where multiple React
+ * roots on one Rails view share a Redux store. Store generators receive props and railsContext,
+ * then return a store. Note that the setStore API is different in that it's the actual store
+ * hydrated with props.
  * @param stores (key is store name, value is the store generator)
  */
 registerStoreGenerators(storesGenerators);

docs/oss/api-reference/redux-store-api.md

@@ -1,25 +1,31 @@
-# Redux Store
+# Redux Store API
 
 > [!WARNING]
 >
-> This Redux API is no longer recommended as it prevents dynamic code splitting for performance. Instead, you should use the standard `react_component` view helper passing in a "Render-Function."
+> This runtime API remains supported for existing apps and advanced shared-store use cases, but it is not recommended as the default state model for new React on Rails apps. Prefer the standard `react_component` view helper with props or a render-function unless multiple React islands must coordinate through one client store.
 
 > [!IMPORTANT]
 >
 > **Script Loading Requirement:** If you use Redux shared stores with inline component registration (registering components in view templates with `<script>ReactOnRails.register({ MyComponent })</script>`), you **must use `defer: true`** in your `javascript_pack_tag` instead of `async: true`. With async loading, the bundle may execute before inline scripts, causing component registration failures. See the [Streaming Server Rendering documentation](../building-features/streaming-server-rendering.md#important-redux-shared-store-caveat) for details and alternatives.
 
-You don't need to use the `redux_store` api to use Redux. This API was set up to support multiple calls to `react_component` on one page that all talk to the same Redux store.
+You don't need to use the `redux_store` API to use Redux inside a single React root. This API was set up to support multiple calls to `react_component` on one page that all talk to the same Redux store.
 
-If you are only rendering one React component on a page, as is typical to do a "Single Page App" in React, then you should _probably_ pass the props to your React component in a "Render-Function."
+If you are rendering one React component on a page, pass props to that component through `react_component` and keep local UI state inside that React tree. A render-function is also a better fit when you need `railsContext`, routing setup, or custom hydration behavior for one root.
 
-Consider using the `redux_store` helper for the two following use cases:
+Choose state ownership before reaching for `redux_store`:
+
+- **Local island state:** use React Hooks or React Context inside one `react_component` root.
+- **Server state:** use Rails controller props for initial data, then Rails JSON endpoints, GraphQL, or a server-state cache such as [TanStack Query](../building-features/tanstack-query.md) for data that belongs on the server.
+- **Multi-island shared client state:** use `redux_store` when separate React roots on one Rails page must read and update the same client-side state.
+
+Consider using the `redux_store` helper for the following advanced use cases:
 
 1. You want to have multiple React components accessing the same store at once.
 2. You want to place the props to hydrate the client side stores at the very end of your HTML, probably server rendered, so that the browser can render all earlier HTML first. This is particularly useful if your props will be large. However, you're probably better off using [React on Rails Pro](../../pro/react-on-rails-pro.md) if you're at all concerned about performance.
 
-## Multiple React Components on a Page with One Store
+## Multiple React Islands on a Page with One Store
 
-You may wish to have 2 React components share the same the Redux store. For example, if your navbar is a React component, you may want it to use the same store as your component in the main area of the page. You may even want multiple React components in the main area, which allows for greater modularity. Also, you may want this to work with Turbolinks to minimize reloading the JavaScript.
+You may wish to have two separate React roots share the same Redux store. For example, if your navbar is a React component, you may want it to use the same store as your component in the main area of the page. You may even want multiple React components in the main area, which allows for greater modularity. Also, you may want this to work with Turbo or Turbolinks to minimize reloading the JavaScript.
 
 A good example of this would be something like a notifications counter in a header. As each notification is read in the body of the page, you would like to update the header. If both the header and body share the same Redux store, then this is trivial. Otherwise, we have to rely on other solutions, such as the header polling the server to see how many unread notifications exist.
 

docs/oss/building-features/react-and-redux.md

@@ -1,12 +1,14 @@
-# Communication between React Components and Redux Reducers
+# Legacy Redux Reducer Guidance
+
+Redux remains supported for existing React on Rails apps and advanced pages that need one client store shared across multiple React roots. For new apps, prefer local component state for island-specific UI, Rails props plus server-state tools for server-owned data, and reach for Redux only when those smaller patterns do not fit.
 
 ## Communication Between Components
 
 See [Sharing State Between Components](https://react.dev/learn/sharing-state-between-components).
 
 ## Redux Reducers
 
-The `helloWorld/reducers/index.jsx` example that results from running the generator with the Redux option may be slightly confusing because of its simplicity. For clarity, what follows is a more fleshed-out example of what a reducer might look like:
+The `helloWorld/reducers/index.jsx` example from the hidden legacy Redux generator may be slightly confusing because of its simplicity. For clarity, what follows is a more fleshed-out example of what a reducer might look like:
 
 ```javascript
 import usersReducer from './usersReducer';

docs/oss/building-features/react-router.md

@@ -37,9 +37,34 @@ React Router v6 offers multiple routing approaches. For React on Rails, we recom
 
 **Note on Data Mode:** React Router's Data Mode (with loaders/actions) is designed for SPAs where the client handles data fetching. Since React on Rails uses Rails controllers to load data and pass it as props to React components, Data Mode would create duplicate data loading. Stick with Declarative Mode to leverage React on Rails' server-side data loading pattern.
 
-## Basic Client-Side Setup with Redux
+## Basic Client-Side Setup
 
-If you're using Redux (created with `rails generate react_on_rails:install --redux`), you can add React Router by wrapping your app:
+Most React Router integrations do not need Redux. Route ordinary components inside one React root, pass initial data from Rails as props, and use your normal server-state approach for follow-up data loading.
+
+**File: `app/javascript/src/RouterApp/ror_components/RouterApp.client.jsx`**
+
+```jsx
+import React from 'react';
+import { BrowserRouter, Routes, Route } from 'react-router-dom';
+
+const Home = ({ name }) => <div>Hello, {name}!</div>;
+const About = () => <div>About</div>;
+
+const RouterApp = (props) => (
+  <BrowserRouter>
+    <Routes>
+      <Route path="/" element={<Home {...props} />} />
+      <Route path="/about" element={<About />} />
+    </Routes>
+  </BrowserRouter>
+);
+
+export default RouterApp;
+```
+
+## Legacy Client-Side Setup with Redux
+
+If you're maintaining an app that already uses Redux, including the hidden legacy Redux generator output, you can add React Router by wrapping your app:
 
 **File: `app/javascript/src/HelloWorldApp/ror_components/HelloWorldApp.client.jsx`**
 
@@ -76,7 +101,7 @@ export default HelloWorldApp;
 
 **Key points:**
 
-- `<Provider>` wraps `<BrowserRouter>` so all routes have Redux access
+- In Redux-backed legacy apps, `<Provider>` wraps `<BrowserRouter>` so all routes have Redux access
 - Use `<Routes>` and `<Route>` (not `<Switch>` from React Router v5)
 - Use `element` prop to specify components (not `component` or `render` props from v5)
 - Routes are automatically matched by best fit, not render order

docs/oss/core-concepts/auto-bundling-file-system-based-automated-bundle-generation.md

@@ -728,7 +728,7 @@ As of version 13.3.4, bundles inside directories that match `config.components_s
 ## Redux Store Auto-Registration
 
 > [!NOTE]
-> Most applications use React components without Redux. If you don't use Redux stores, you can skip this section entirely.
+> Most applications use React components without Redux. If you don't maintain a legacy Redux app or an advanced multi-island shared store, you can skip this section entirely.
 
 In addition to components, React on Rails can automatically register Redux stores based on file system conventions. This eliminates manual `ReactOnRails.registerStore()` calls and generates individual packs for each store. The feature works the same way as component auto-registration.
 

docs/oss/core-concepts/how-react-on-rails-works.md

@@ -8,7 +8,7 @@ Ensure these generated bundle files are in your `.gitignore`, as you never want
 
 Inside your Rails views, you can now use the `react_component` helper method provided by React on Rails. You can pass props directly to the React component helper.
 
-Optionally, you can also initialize a Redux store with the view or controller helper `redux_store` so that the Redux store can be shared amongst multiple React components.
+For legacy or advanced shared-store pages, you can also initialize a Redux store with the view or controller helper `redux_store` so that separate React roots can coordinate through one client store.
 
 ## Client-Side Rendering vs. Server-Side Rendering
 

docs/oss/core-concepts/render-functions-and-railscontext.md

@@ -3,7 +3,7 @@
 ## Render-Functions
 
 When you use a render-function to create React components (or `renderedHtml` on the server), or you
-use shared Redux stores, you get two params passed to your function that creates a React component:
+register legacy or advanced shared Redux stores, React on Rails passes two params to the function it calls:
 
 1. `props`: Props that you pass in the view helper of either `react_component` or `redux_store`
 2. `railsContext`: Rails contextual information, such as the current pathname. You can customize
@@ -78,7 +78,7 @@ reduxStore = MyReduxStore(props, railsContext);
 > You never make these calls. React on Rails makes these calls when it does either client or server rendering. You will define functions that take these 2 params and return a React component or a Redux Store. Naturally, you do not have to use second parameter, `railsContext`, if you do not need it. If you don't take a second parameter, then you're probably defining a React function component and you will simply return a React Element, often just JSX.
 
 > [!NOTE]
-> See [Redux Store](../api-reference/redux-store-api.md#multiple-react-components-on-a-page-with-one-store) on how to set up Redux stores that allow multiple components to talk to the same store.
+> See [Redux Store](../api-reference/redux-store-api.md#multiple-react-islands-on-a-page-with-one-store) on how to set up Redux stores that allow multiple React roots to talk to the same store.
 
 The `railsContext` has: (see the implementation in [ReactOnRails::Helper](https://github.com/shakacode/react_on_rails/blob/main/react_on_rails/lib/react_on_rails/helper.rb), method `rails_context` for the definitive list).
 

docs/oss/getting-started/quick-start.md

@@ -190,7 +190,7 @@ Now that you have React on Rails working, here's what to explore next:
 
 ### Advanced Features
 
-1. **[Redux Integration](../building-features/react-and-redux.md)** - Manage application state
+1. **[Redux Integration](../building-features/react-and-redux.md)** - Maintain legacy or advanced shared-store integrations
 2. **[React Router](../building-features/react-router.md)** - Client-side routing
 
 ### Pro Features