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>

Author: ihabadham

docs/building-features/react-router.md

@@ -1,76 +1,183 @@
-_This article needs updating for the latest version of React Router_
-
 # Using React Router
 
-React on Rails supports the use of React Router. Client-side code doesn't need any special configuration for the React on Rails gem. Implement React Router how you normally would. Note, you might want to avoid using Turbolinks as both Turbolinks and React Router will be trying to handle the back and forward buttons. If you get this figured out, please do share with the community! Otherwise, you might have to tweak the basic settings for Turbolinks, and this may or may not be worth the effort.
+React on Rails supports React Router for client-side routing. This guide shows how to integrate React Router into your React on Rails application.
+
+**Important:** The React on Rails generator does not install React Router. You'll need to add it to your project manually.
+
+## Compatibility Note
+
+If you're using Turbo (Rails 7+) or Turbolinks (Rails 6 and earlier), be aware that both React Router and Turbo/Turbolinks handle browser navigation and the back button. These two routing systems can conflict. Consider:
+
+- Using one routing approach (either Turbo OR React Router, not both)
+- Disabling Turbo for pages using React Router with `data-turbo="false"`
+- Using code splitting instead of client-side routing for similar performance benefits
+
+If you successfully integrate both, please share your solution with the community!
+
+For more details, see [Turbo/Turbolinks Guide](../rails/turbolinks.md).
+
+## Installation
+
+First, add React Router v6 to your project:
+
+```bash
+npm install react-router-dom@^6.0.0
+# or
+yarn add react-router-dom@^6.0.0
+```
+
+**Why React Router v6?** React Router v7 has merged with Remix and uses a different architecture that may not be fully compatible with React on Rails' server-side rendering approach. We recommend v6 for stable integration. If you need v7 features, please test thoroughly and share your findings with the community.
 
-If you are working with the HelloWorldApp created by the react_on_rails generator (with `--redux` option), the code below corresponds to your Redux entry point component (typically in `src/HelloWorldApp/ror_components/`).
+React Router v6 offers multiple routing approaches. For React on Rails, we recommend **Declarative Mode** (traditional component-based routing, covered in this guide).
 
-```js
-import { BrowserRouter, Switch } from 'react-router-dom';
-import routes from './routes.jsx';
+**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.
 
-const RouterApp = (props, railsContext) => {
-  // create your hydrated store
-  const store = createStore(props);
+## Basic Client-Side Setup with Redux
+
+If you're using Redux (created with `rails generate react_on_rails:install --redux`), you can add React Router by wrapping your app:
+
+**File: `app/javascript/src/HelloWorldApp/ror_components/HelloWorldApp.client.jsx`**
+
+```jsx
+import React from 'react';
+import { Provider } from 'react-redux';
+import { BrowserRouter, Routes, Route } from 'react-router-dom';
+
+import configureStore from '../store/helloWorldStore';
+import HelloWorldContainer from '../containers/HelloWorldContainer';
+// Import other components for routing
+// import About from '../components/About';
+// import Contact from '../components/Contact';
+
+const HelloWorldApp = (props) => {
+  const store = configureStore(props);
 
   return (
     <Provider store={store}>
       <BrowserRouter>
-        <Switch>{routes}</Switch>
+        <Routes>
+          <Route path="/" element={<HelloWorldContainer />} />
+          {/* Add more routes here */}
+          {/* <Route path="/about" element={<About />} /> */}
+          {/* <Route path="/contact" element={<Contact />} /> */}
+        </Routes>
       </BrowserRouter>
     </Provider>
   );
 };
-```
 
-For a fleshed out integration of React on Rails with React Router, check out [React Webpack Rails Tutorial Code](https://github.com/shakacode/react-webpack-rails-tutorial), specifically the routing configuration in:
+export default HelloWorldApp;
+```
 
-- [react-webpack-rails-tutorial/client/app/bundles/comments/routes/routes.jsx](https://github.com/shakacode/react-webpack-rails-tutorial/blob/master/client/app/bundles/comments/routes/routes.jsx)
+**Key points:**
 
-## Server Rendering Using React Router V4
+- `<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
 
-Your Render-Function may not return an object with the property `renderedHtml`. Thus, you call
-`renderToString()` and return an object with this property.
+## Server-Side Rendering with React Router
 
-This example **only applies to server-side rendering** and should only be used in the server-side bundle.
+For server rendering, use `StaticRouter` instead of `BrowserRouter`.
 
-From the [original example in the React Router docs](https://github.com/ReactTraining/react-router/blob/v4.3.1/packages/react-router-dom/docs/guides/server-rendering.md)
+**File: `app/javascript/src/HelloWorldApp/ror_components/HelloWorldApp.server.jsx`**
 
-```javascript
+```jsx
 import React from 'react';
 import { renderToString } from 'react-dom/server';
-import { StaticRouter } from 'react-router';
+import { StaticRouter } from 'react-router-dom/server';
 import { Provider } from 'react-redux';
-import ReactOnRails from 'react-on-rails';
-
-// App.jsx from src/client/App.jsx
-import App from '../App';
-
-const ReactServerRenderer = (props, railsContext) => {
-  const context = {};
-
-  // commentStore from src/server/store/commentStore
-  const store = ReactOnRails.getStore('../store/commentStore');
+import { Routes, Route } from 'react-router-dom';
 
-  // Route Store generated from react-on-rails
+import configureStore from '../store/helloWorldStore';
+import HelloWorldContainer from '../containers/HelloWorldContainer';
+// Import other components for routing
+// import About from '../components/About';
+// import Contact from '../components/Contact';
 
+const HelloWorldApp = (props, railsContext) => {
+  const store = configureStore(props);
   const { location } = railsContext;
 
   const html = renderToString(
     <Provider store={store}>
-      <StaticRouter location={location} context={context} props={props}>
-        <App />
+      <StaticRouter location={location}>
+        <Routes>
+          <Route path="/" element={<HelloWorldContainer />} />
+          {/* Add more routes here */}
+          {/* <Route path="/about" element={<About />} /> */}
+          {/* <Route path="/contact" element={<Contact />} /> */}
+        </Routes>
       </StaticRouter>
     </Provider>,
   );
 
-  if (context.url) {
-    // Somewhere a `<Redirect>` was rendered
-    redirect(301, context.url);
-  } else {
-    // we're good, send the response
-    return { renderedHtml: html };
-  }
+  return { renderedHtml: html };
 };
+
+export default HelloWorldApp;
+```
+
+**Important changes from React Router v5:**
+
+- Import `StaticRouter` from `'react-router-dom/server'` (not `'react-router'`)
+- Use `<Routes>` and `<Route>` with `element` prop
+- `location` prop takes a string path from `railsContext`
+- No need for `match()` or `RouterContext` - simplified API
+
+## Rails Routes Configuration
+
+**Critical Step:** To support direct URL visits, browser refresh, and server-side rendering, you must configure Rails to handle all React Router paths.
+
+Add a wildcard route in your `config/routes.rb`:
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  # Your main route
+  get 'your_path', to: 'your_controller#index'
+
+  # Wildcard catch-all for React Router sub-routes
+  get 'your_path/*path', to: 'your_controller#index'
+end
+```
+
+**Example:**
+
+```ruby
+# For a HelloWorld app with React Router
+get 'hello_world', to: 'hello_world#index'
+get 'hello_world/*path', to: 'hello_world#index'
 ```
+
+This configuration ensures:
+
+- `/hello_world` → Renders your React app
+- `/hello_world/about` → Rails serves the same view, React Router handles routing
+- `/hello_world/contact` → Rails serves the same view, React Router handles routing
+- Browser refresh works on any route
+- Direct URL visits work with server-side rendering
+
+**Important:** Your React Router paths should match your Rails route structure. If Rails serves your app at `/hello_world`, your React Router routes should start with `/hello_world`:
+
+```jsx
+<Routes>
+  <Route path="/hello_world" element={<Home />} />
+  <Route path="/hello_world/about" element={<About />} />
+  <Route path="/hello_world/contact" element={<Contact />} />
+</Routes>
+```
+
+## Example Application
+
+For a complete example of React on Rails with React Router, see the [React Webpack Rails Tutorial](https://github.com/shakacode/react-webpack-rails-tutorial).
+
+For a practical example of route organization, see the [routes configuration file](https://github.com/shakacode/react-webpack-rails-tutorial/blob/master/client/app/bundles/comments/routes/routes.jsx) from the tutorial.
+
+**Note:** This tutorial uses a legacy directory structure (`client/app/bundles`) from earlier React on Rails versions. Modern projects use `app/javascript/src/` structure as shown in this guide. The React Router integration patterns remain applicable.
+
+## Additional Resources
+
+- [React Router Official Documentation](https://reactrouter.com/)
+- [React Router v6 Migration Guide](https://reactrouter.com/en/main/upgrading/v5) - If upgrading from v5
+- [React on Rails Turbo/Turbolinks Guide](../rails/turbolinks.md)

spec/dummy/client/app/components/RouterLayout.jsx

@@ -1,5 +1,5 @@
 import React from 'react';
-import { Link, Route, Switch } from 'react-router-dom';
+import { Link, Route, Routes } from 'react-router-dom';
 import RouterFirstPage from './RouterFirstPage';
 import RouterSecondPage from './RouterSecondPage';
 
@@ -21,10 +21,10 @@ const RouterLayout = () => (
       </li>
     </ul>
     <hr />
-    <Switch>
-      <Route path="/react_router/first_page" component={RouterFirstPage} />
-      <Route path="/react_router/second_page" component={RouterSecondPage} />
-    </Switch>
+    <Routes>
+      <Route path="first_page" element={<RouterFirstPage />} />
+      <Route path="second_page" element={<RouterSecondPage />} />
+    </Routes>
   </div>
 );
 

spec/dummy/client/app/routes/routes.jsx

@@ -1,6 +1,10 @@
 import React from 'react';
-import { Route } from 'react-router-dom';
+import { Routes, Route } from 'react-router-dom';
 
 import RouterLayout from '../components/RouterLayout';
 
-export default <Route path="/react_router" component={RouterLayout} />;
+export default (
+  <Routes>
+    <Route path="/react_router/*" element={<RouterLayout />} />
+  </Routes>
+);

spec/dummy/client/app/startup/RouterApp.server.jsx

@@ -1,5 +1,5 @@
 import React from 'react';
-import { StaticRouter } from 'react-router-dom';
+import { StaticRouter } from 'react-router-dom/server';
 
 import routes from '../routes/routes';
 

spec/dummy/package.json

@@ -23,7 +23,7 @@
     "react-helmet": "^6.1.0",
     "react-on-rails": "link:.yalc/react-on-rails",
     "react-redux": "^8.0.2",
-    "react-router-dom": "^5.2.0",
+    "react-router-dom": "^6.0.0",
     "redux": "^4.0.1",
     "redux-thunk": "^2.2.0",
     "regenerator-runtime": "^0.13.4"