react_on_rails_pro 16.2.0.beta.8

data/docs/react-server-components/how-react-server-components-work.md

@@ -0,0 +1,243 @@
+# How React Server Components work
+
+React Server Components (RSC) enable server-side component execution with client-side streaming. This document explains the underlying mechanisms and technical details of how RSC works under the hood.
+
+## Bundling Process
+
+We showed in the [Create a React Server Component without SSR](./create-without-ssr.md) article how to bundle React Server Components. During bundling, we used:
+
+### RSC Webpack Loader
+
+The `react-on-rails-rsc/WebpackLoader` is a custom loader that removes the client components and their dependencies from the RSC bundle and replace them with client references that tell the rsc runtime that there is a client component entry point in this place.
+
+The RSC Webpack Loader works when it finds a file with the `'use client'` directive on top of it.
+
+```js
+// app/javascript/client/app/components/HomePage.jsx
+'use client';
+
+import Footer from './Footer';
+
+export const Header = () => {
+  return <div>Header</div>;
+};
+
+export default function HomePage() {
+  return (
+    <div>
+      <Header />
+      <div>Home Page</div>
+      <Footer />
+    </div>
+  );
+};
+```
+
+It replaces all exports of the file with the client references.
+
+> [!NOTE]
+> The code shown below represents internal implementation details of how React Server Components work under the hood. You don't need to understand these details to use React Server Components effectively in your application. This section is included for those interested in the technical implementation.
+
+
+```js
+import { registerClientReference } from "react-server-dom-webpack/server";
+
+export const Header = registerClientReference(
+  function () {
+    throw new Error(
+      "Attempted to call Header() from the server but Header is on the client. It's not possible to invoke a client function from the server, it can only be rendered as a Component or passed to props of a Client Component."
+    );
+  },
+  "file:///path/to/src/HomePage.jsx",
+  "Header"
+);
+
+export default registerClientReference(
+  function() {
+    throw new Error("Attempted to call the default export of file:///path/to/src/HomePage.jsx from the serverbut it's on the client. It's not possible to invoke a client function from the server, it can only be rendered as a Component or passed to props of aClient Component.");
+  },
+  "file:///path/to/src/HomePage.jsx",
+  "default"
+);
+```
+
+When a file is marked with `'use client'`, the RSC Webpack Loader replaces all component exports with `ClientReference` objects. The `registerClientReference` function takes three arguments:
+
+1. A function that throws an error if someone tries to call the component function directly instead of rendering it as a component
+2. A string representing the file path of the client component, which serves as part of its unique identifier
+3. A string with the export name ("default" for default exports, or the named export identifier)
+
+The second and third arguments are used to identify the client component when it needs to be hydrated in the browser.
+
+Note that all imports from the original file are removed in the transformed code. This includes both the `Footer` component import and any other dependencies that the client components may have used. The client component implementations and their dependencies are removed from the RSC bundle.
+
+### RSC Client Plugin
+
+We also used `react-on-rails-rsc/WebpackPlugin` with the client bundle. It does the following:
+
+1. Adds all files with the `'use client'` directive on top of it as entry points to the client bundle.
+2. Creates the `react-client-manifest.json` file that contains the mapping of the client components files to their corresponding webpack chunk IDs.
+
+Let's examine the `react-client-manifest.json` file.
+
+> [!NOTE]
+> The code shown below represents internal implementation details of how React Server Components work under the hood. You don't need to understand these details to use React Server Components effectively in your application. This section is included for those interested in the technical implementation.
+
+First, you need to build the client bundle by running:
+
+```bash
+CLIENT_BUNDLE_ONLY=true bin/shakapacker
+```
+
+> [!NOTE]
+> When you run `bin/dev`, the client bundle may not be written to the disk, it's served from the webpack-dev-server. That's why you need to run `CLIENT_BUNDLE_ONLY=true bin/shakapacker` to ensure the client bundle is built and written to the disk.
+
+Then, you can find the `react-client-manifest.json` file in the `public/webpack/development` or `public/webpack/production` directory, depending on the environment you are building for.
+
+Let's search for the client component `ToggleContainer` that we built before in [Add Streaming and Interactivity to RSC Page](./add-streaming-and-interactivity.md) article. You will find the following entry in the `react-client-manifest.json` file:
+
+```json
+"file:///path/to/app/javascript/components/ToggleContainer.jsx": {
+    "id": "./app/javascript/components/ToggleContainer.jsx",
+    "chunks": [
+      "client25",
+      "js/client25.js"
+    ],
+    "name": "*"
+  },
+```
+
+This entry indicates that the `ToggleContainer` client component is included in the `client25` chunk. The `js/client25.js` file contains the client-side code for the `ToggleContainer` component. You can find the `client25` chunk in the `public/webpack/<environment>/js/client25.js` file. Also, the `id` field is the Webpack module ID for the `ToggleContainer` client component. It's used by react runtime to load and hydrate the component in the browser.
+
+If you want to change the file name of the `react-client-manifest.json` file, you can do so by setting the `clientManifestFilename` option in the `react-on-rails-rsc/WebpackPlugin` plugin as follows:
+
+```js
+const { RSCWebpackPlugin } = require('react-on-rails-rsc/WebpackPlugin');
+
+config.plugins.push(new RSCWebpackPlugin({
+  isServer: false,
+  clientManifestFilename: 'client-components-webpack-manifest.json',
+}));
+```
+
+And because React on Rails Pro uploads the `react-client-manifest.json` file to the renderer while uploading the server bundle and it expects it to be named `react-client-manifest.json`, you need to tell React on Rails Pro that the name is changed to `client-components-webpack-manifest.json`.
+
+```ruby
+# config/initializers/react_on_rails.rb
+ReactOnRails.configure do |config|
+  config.react_client_manifest_file = "client-components-webpack-manifest.json"
+end
+```
+
+## React Server Component Payload (RSC Payload)
+
+The React Server Component Payload (RSC Payload) is a mechanism that allows you to pass the rendered server components from the server to the client. You can use the `rsc_payload_react_component` helper function to embed the RSC payload of any component in your Rails views. Let's try to embed the RSC payload of the `ReactServerComponentPage` component in the `app/views/pages/react_server_component_page_rsc_payload.html.erb` view.
+
+```erb
+<%= rsc_payload_react_component("ReactServerComponentPage") %>
+```
+
+Add the route to the `app/config/routes.rb` file.
+
+```ruby
+# config/routes.rb
+get "/react_server_component_page_rsc_payload", to: "pages#react_server_component_page_rsc_payload"
+```
+
+And render the view using the `stream_view_containing_react_components` helper method.
+
+```ruby
+# app/controllers/pages_controller.rb
+class PagesController < ApplicationController
+  include ReactOnRailsPro::Stream
+
+  def react_server_component_page_rsc_payload
+    stream_view_containing_react_components(template: "pages/react_server_component_page_rsc_payload")
+  end
+end
+```
+
+When you navigate to the `http://localhost:3000/react_server_component_page_rsc_payload` page, you will see the RSC payload of the `ReactServerComponentPage` component. You will find multiple JSON objects in the response body. Each represents a chunk of the RSC payload.
+
+```json
+{
+  "html":"<RSC Payload>",
+  "consoleReplayScript":"",
+  "hasErrors":false,
+  "isShellReady":true
+}
+{
+  "html":"<RSC Payload>",
+  "consoleReplayScript":"",
+  "hasErrors":false,
+  "isShellReady":true
+}
+```
+
+The real RSC payload is embedded in the `html` field. Other fields are used by React on Rails Pro to ensure the RSC payload is rendered correctly and to replay the console logs in the browser.
+
+> [!NOTE]
+> using `html` field to refer to the RSC payload may be confusing. It will be changed later to `rscPayload`, but it's an implementation detail and you should not rely on it.
+
+The RSC payload itself is an implementation detail, you don't need to understand it to use React Server Components. But we can notice that it contains the React render tree of the `ReactServerComponentPage` component. Like this:
+
+```rsc
+1:["$","div",null,{"className":"server-component-demo","children":[["$","h2",null,{"children":"React Server Component Demo"}],["$","section",null,{"children":[["$","h3",null,{"children":"Date Calculations (using moment.js)"}]]}]]}]
+```
+
+The interesting part is how the RSC payload references the client components. Let's take a look at how it references the `ToggleContainer` client component.
+
+```rsc
+7:I["./app/javascript/components/ToggleContainer.jsx",["client25","js/client25.js"],"default"]
+```
+
+The RSC payload references client components by including:
+1. The webpack module ID of the client component (e.g. "./app/javascript/components/ToggleContainer.jsx")
+2. The webpack chunk IDs that contain the component code (e.g. ["client25","js/client25.js"])
+3. The export name being referenced (e.g. "default")
+
+This information comes from the `react-client-manifest.json` file, which maps client component paths to their corresponding webpack module and chunk IDs. That's why we needed to upload the `react-client-manifest.json` file to the renderer as it's needed to generate the RSC payload.
+
+## Automatically Generate the RSC Payload
+
+Usually, you don't need to generate the RSC payload manually. You can use the `rsc_payload_route` helper method inside the `config/routes.rb` file to automatically add the rsc route that accepts the component name as a parameter and returns the RSC payload.
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  rsc_payload_route
+end
+```
+
+You can change the path of the rsc route by passing the `path` option to the `rsc_payload_route` method.
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  rsc_payload_route path: "/flight-payload"
+end
+```
+
+In this case, ensure you pass the correct path to `registerServerComponent` function in the client bundle.
+
+```js
+// client/app/packs/client-bundle.js
+import registerServerComponent from 'react-on-rails/registerServerComponent/client';
+
+registerServerComponent({
+  rscPayloadGenerationUrlPath: "flight-payload",
+}, "ReactServerComponentPage")
+```
+
+Or if you enabled the `auto_load_bundle` option to make React on Rails automatically register react components, you can pass the path to the `rsc_payload_generation_url_path` config in React on Rails Pro configuration.
+
+```ruby
+# config/initializers/react_on_rails.rb
+ReactOnRailsPro.configure do |config|
+  config.rsc_payload_generation_url_path = "flight-payload"
+end
+```
+
+## Next Steps
+
+To learn more about how React Server Components are rendered in React on Rails Pro, including the rendering flow, bundle types, and upcoming improvements, see [React Server Components Rendering Flow](./rendering-flow.md).

data/docs/react-server-components/inside-client-components.md

@@ -0,0 +1,332 @@
+
+# Using React Server Components Inside Client Components
+
+React on Rails now supports rendering React Server Components (RSC) directly inside React Client Components. This guide explains how to use this feature effectively in your applications.
+
+## Overview
+
+React Server Components provide several benefits.However, React traditionally doesn't allow server components to be directly rendered inside client components. This feature bypasses that limitation.
+
+> [!IMPORTANT]
+> This feature should be used judiciously. It's best suited for server components whose props change very rarely, such as router routes. **Do not** use this with components whose props change frequently as it triggers HTTP requests to the server on each re-render.
+
+## Basic Usage
+
+### Before
+
+Previously, server components could only be embedded inside client components if passed as a prop from a parent server component:
+
+```tsx
+// Parent Server Component
+export default function Parent() {
+  return (
+    <ClientComponent>
+      <ServerComponent />
+    </ClientComponent>
+  );
+}
+```
+
+### After
+
+Now, you can render server components directly inside client components using the `RSCRoute` component:
+
+```tsx
+'use client';
+import RSCRoute from 'react-on-rails/RSCRoute';
+
+export default function ClientComponent() {
+  return (
+    <div>
+      <RSCRoute componentName="ServerComponent" componentProps={{ user }} />
+    </div>
+  );
+}
+```
+
+## Setup Steps
+
+### 1. Register your server components
+
+Register your server components in your Server and RSC bundles:
+
+```tsx
+// packs/server_bundle.tsx
+import registerServerComponent from 'react-on-rails/registerServerComponent/server.rsc';
+import MyServerComponent from './components/MyServerComponent';
+import AnotherServerComponent from './components/AnotherServerComponent';
+
+registerServerComponent({
+  MyServerComponent,
+  AnotherServerComponent
+});
+```
+
+> [!NOTE]
+> Server components only need to be registered in the client bundle if they will be rendered directly in Rails views using the `stream_react_component` helper. If you're only using server components inside client components via `RSCRoute`, you can skip client bundle registration entirely. In this case, it's enough to register the server component in the server and RSC bundles.
+
+### 2. Create your client component
+
+Create a client component that uses `RSCRoute` to render server components:
+
+```tsx
+// components/MyClientComponent.tsx
+'use client';
+import { useState } from 'react';
+import RSCRoute from 'react-on-rails/RSCRoute';
+
+export default function MyClientComponent({ user }) {
+  return (
+    <div>
+      <h1>Hello from Client Component</h1>
+      <RSCRoute componentName="MyServerComponent" componentProps={{ user }} />
+    </div>
+  );
+}
+```
+
+### 3. Wrap your client component
+
+Create client and server versions of your component wrapped with `wrapServerComponentRenderer`:
+
+#### Client version:
+```tsx
+// components/MyClientComponent.client.tsx
+'use client';
+import ReactOnRails from 'react-on-rails';
+import wrapServerComponentRenderer from 'react-on-rails/wrapServerComponentRenderer/client';
+import MyClientComponent from './MyClientComponent';
+
+const WrappedComponent = wrapServerComponentRenderer(MyClientComponent);
+
+ReactOnRails.register({
+  MyClientComponent: WrappedComponent
+});
+```
+
+#### Server version:
+```tsx
+// components/MyClientComponent.server.tsx
+import ReactOnRails from 'react-on-rails';
+import wrapServerComponentRenderer from 'react-on-rails/wrapServerComponentRenderer/server';
+import MyClientComponent from './MyClientComponent';
+
+const WrappedComponent = wrapServerComponentRenderer(MyClientComponent);
+
+ReactOnRails.register({
+  MyClientComponent: WrappedComponent
+});
+```
+
+### 4. Use in Rails view
+
+```erb
+<%= stream_react_component('MyClientComponent', props: { user: current_user.as_json }, prerender: true) %>
+```
+
+> [!NOTE]
+> You must use `stream_react_component` rather than `react_component` for server components or client components that use server components.
+
+## Use Cases and Examples
+
+### ❌ Bad Example - Frequently Changing Props
+
+```tsx
+'use client';
+import { useState } from 'react';
+import RSCRoute from 'react-on-rails/RSCRoute';
+
+export default function ClientComponent() {
+  const [count, setCount] = useState(0);
+
+  return (
+    <div>
+      <button onClick={() => setCount(count + 1)}>Increment</button>
+      <label>Count: {count}</label>
+      {/* BAD EXAMPLE: Server Component props change with each button click */}
+      <RSCRoute componentName="ServerComponent" componentProps={{ count }} />
+    </div>
+  );
+}
+```
+
+> [!WARNING]
+> This implementation will make a server request on every state change, significantly impacting performance.
+
+### ✅ Good Example - Router Integration
+
+```tsx
+'use client';
+import { Routes, Route, Link } from 'react-router-dom';
+import RSCRoute from 'react-on-rails/RSCRoute';
+import AnotherClientComponent from './AnotherClientComponent';
+
+export default function AppRouter({ user }) {
+  return (
+    <>
+      <nav>
+        <Link to="/">Home</Link>
+        <Link to="/about">About</Link>
+        <Link to="/client-component">Client Component</Link>
+      </nav>
+      <Routes>
+        {/* Mix client and server components in your router */}
+        <Route path="/client-component" element={<AnotherClientComponent />} />
+        {/* GOOD EXAMPLE: Server Component props rarely change */}
+        <Route path="/about" element={<RSCRoute componentName="About" componentProps={{ user }} />} />
+        <Route path="/" element={<RSCRoute componentName="Home" componentProps={{ user }} />} />
+      </Routes>
+    </>
+  );
+}
+```
+
+## Advanced Usage
+
+### Nested Routes with Server Components
+
+The framework supports nesting client and server components to arbitrary depth:
+
+```tsx
+'use client';
+import { Routes, Route } from 'react-router-dom';
+import RSCRoute from 'react-on-rails/RSCRoute';
+import ServerRouteLayout from './ServerRouteLayout';
+import ClientRouteLayout from './ClientRouteLayout';
+
+export default function AppRouter() {
+  return (
+    <Routes>
+      <Route path="/main-server-route" element={<ServerRouteLayout />}>
+        <Route path="/server-subroute" element={<RSCRoute componentName="MyServerComponent" />} />
+        <Route path="/client-subroute" element={<ClientSubcomponent />} />
+      </Route>
+      <Route path="/main-client-route" element={<ClientRouteLayout />}>
+        <Route path="/client-subroute" element={<ClientSubcomponent />} />
+        <Route path="/server-subroute" element={<RSCRoute componentName="MyServerComponent" />} />
+      </Route>
+    </Routes>
+  );
+}
+```
+
+### Using `Outlet` in Server Components
+
+To use React Router's `Outlet` in server components, create a client version:
+
+```tsx
+// ./components/Outlet.tsx
+'use client';
+export { Outlet as default } from 'react-router-dom';
+```
+
+Then use it in your server components:
+
+```tsx
+// ./components/ServerRouteLayout.tsx
+import Outlet from './Outlet';
+
+export default function ServerRouteLayout() {
+  return (
+    <div>
+      <h1>Server Route Layout</h1>
+      <Outlet />
+    </div>
+  );
+}
+```
+
+## Auto-Loading Bundles
+
+If you're using the `auto_load_bundle: true` option in your React on Rails configuration, you don't need to manually register components using `ReactOnRails.register`. However, you still need to:
+
+1. Create both client and server wrappers for your components
+2. Properly import the environment-specific implementations of `wrapServerComponentRenderer`
+
+## Component Lifecycle
+
+When using server components inside client components:
+
+1. **During Initial SSR**:
+   - The server component is rendered on the server
+   - Its payload is embedded directly in the HTML response
+   - No additional HTTP requests are needed for hydration
+
+2. **During Client Navigation**:
+   - When a user navigates to a new route client-side
+   - The client makes an HTTP request to fetch the server component payload
+   - The route is rendered with the fetched server component
+
+3. **During State Changes**:
+   - If a server component's props change, a new HTTP request is made
+   - The component is re-rendered with the new props
+   - This is why you should avoid frequently changing props
+
+## Performance Considerations
+
+- Page responsiveness is improved because RSC payloads are embedded in the HTML and no additional HTTP requests are needed for hydration
+- Client navigation to new routes with server components requires an HTTP request
+- Avoid changing server component props frequently
+- Consider using suspense boundaries for loading states during navigation
+
+## Common Patterns
+
+### Using a Loading State
+
+```tsx
+'use client';
+import { Suspense } from 'react';
+import RSCRoute from 'react-on-rails/RSCRoute';
+
+export default function ClientComponent({ user }) {
+  return (
+    <div>
+      <Suspense fallback={<div>Loading server component...</div>}>
+        <RSCRoute componentName="ServerComponent" componentProps={{ user }} />
+      </Suspense>
+    </div>
+  );
+}
+```
+
+### Conditional Rendering
+
+```tsx
+'use client';
+import { useState } from 'react';
+import { Suspense } from 'react';
+import RSCRoute from 'react-on-rails/RSCRoute';
+
+export default function ClientComponent({ user }) {
+  const [showServerComponent, setShowServerComponent] = useState(false);
+  
+  return (
+    <div>
+      <button onClick={() => setShowServerComponent(!showServerComponent)}>
+        {showServerComponent ? 'Hide' : 'Show'} Server Component
+      </button>
+      
+      {showServerComponent && (
+        <Suspense fallback={<div>Loading...</div>}>
+          <RSCRoute componentName="ServerComponent" componentProps={{ user }} />
+        </Suspense>
+      )}
+    </div>
+  );
+}
+```
+
+> [!NOTE]
+> When conditionally rendering server components, an HTTP request will be made when the component becomes visible.
+
+## Best Practices
+
+1. **Use for rarely changing components**: Server components are ideal for routes, layouts, and content that doesn't change frequently.
+
+2. **Always wrap in Suspense**: Server components may load asynchronously, especially after client navigation.
+
+3. **Pass stable props**: Avoid passing state variables that change frequently as props to server components.
+
+4. **Use for data-heavy components**: Components that need to fetch data from databases or APIs are good candidates for server components.
+
+By following these guidelines, you can effectively leverage React Server Components while maintaining optimal performance.