Phase 1: Update documentation and CHANGELOG for Pro feature separation

AbanoubGhadban · AbanoubGhadban · commit 78d5717b5416 · 2025-10-23T12:00:20.000+03:00
- Updated CHANGELOG.md with breaking changes for RSC configs and streaming helpers - Updated react_on_rails_pro/CHANGELOG.md to document additions to Pro gem - Moved RSC configuration documentation to Pro gem docs - Added Pro-only view helpers section consolidating all Pro helpers - Added prominent Pro feature notices to streaming documentation - Removed inaccurate claims about error behavior Related to #1874
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -73,6 +73,37 @@ To migrate to React on Rails Pro:
 
 **Note:** If you're not using any of the Pro-only methods listed above, no changes are required.
 
+- **Pro-Specific Configurations Moved to Pro Gem**: The following React Server Components (RSC) configurations have been moved from `ReactOnRails.configure` to `ReactOnRailsPro.configure`:
+  - `rsc_bundle_js_file` - Path to the RSC bundle file
+  - `react_server_client_manifest_file` - Path to the React server client manifest
+  - `react_client_manifest_file` - Path to the React client manifest
+
+  **Migration:** If you're using RSC features, move these configurations from your `ReactOnRails.configure` block to `ReactOnRailsPro.configure`:
+
+  ```ruby
+  # Before
+  ReactOnRails.configure do |config|
+    config.rsc_bundle_js_file = "rsc-bundle.js"
+    config.react_server_client_manifest_file = "react-server-client-manifest.json"
+    config.react_client_manifest_file = "react-client-manifest.json"
+  end
+
+  # After
+  ReactOnRailsPro.configure do |config|
+    config.rsc_bundle_js_file = "rsc-bundle.js"
+    config.react_server_client_manifest_file = "react-server-client-manifest.json"
+    config.react_client_manifest_file = "react-client-manifest.json"
+  end
+  ```
+
+  See the [React on Rails Pro Configuration docs](https://github.com/shakacode/react_on_rails/blob/master/react_on_rails_pro/docs/configuration.md) for more details.
+
+- **Streaming View Helpers Moved to Pro Gem**: The following view helpers have been removed from the open-source gem and are now only available in React on Rails Pro:
+  - `stream_react_component` - Progressive SSR using React 18+ streaming
+  - `rsc_payload_react_component` - RSC payload rendering
+
+  These helpers are now defined exclusively in the `react-on-rails-pro` gem.
+
 ### [16.1.1] - 2025-09-24
 
 #### Bug Fixes
diff --git a/docs/api-reference/configuration.md b/docs/api-reference/configuration.md
@@ -104,30 +104,21 @@ ReactOnRails.configure do |config|
   # you should include a name that matches your bundle name in your Webpack config.
   config.server_bundle_js_file = "server-bundle.js"
 
-  # When using React on Rails Pro with RSC support enabled, these configuration options work together:
-  #
-  # 1. In RORP, set `config.enable_rsc_support = true` in your react_on_rails_pro.rb initializer
-  #
-  # 2. The `rsc_bundle_js_file` (typically "rsc-bundle.js") contains only server components and
-  #    references to client components. It's generated using the RSC Webpack Loader which transforms
-  #    client components into references. This bundle is specifically used for generating RSC payloads
-  #    and is configured with the `react-server` condition.
-  config.rsc_bundle_js_file = "rsc-bundle.js"
+  ################################################################################
+  # REACT SERVER COMPONENTS (RSC) AND STREAMING CONFIGURATION
+  ################################################################################
   #
-  # 3. The `react_client_manifest_file` contains mappings for client components that need hydration.
-  #    It's generated by the React Server Components Webpack plugin and is required for client-side
-  #    hydration of components.
-  # This manifest file is automatically generated by the React Server Components Webpack plugin. Only set this if you've configured the plugin to use a different filename.
-  config.react_client_manifest_file = "react-client-manifest.json"
+  # React Server Components and Streaming SSR are React on Rails Pro features.
+  # For detailed configuration of RSC and streaming features, see:
+  # https://github.com/shakacode/react_on_rails/blob/master/react_on_rails_pro/docs/configuration.md
   #
-  # 4. The `react_server_client_manifest_file` is used during server-side rendering with RSC to
-  #    properly resolve references between server and client components.
+  # Key Pro configurations (configured in ReactOnRailsPro.configure block):
+  # - rsc_bundle_js_file: Path to RSC bundle
+  # - react_client_manifest_file: Client component manifest for RSC
+  # - react_server_client_manifest_file: Server manifest for RSC
+  # - enable_rsc_support: Enable React Server Components
   #
-  # These files are crucial when implementing React Server Components with streaming, which offers
-  # benefits like reduced JavaScript bundle sizes, faster page loading, and selective hydration
-  # of client components.
-  # This manifest file is automatically generated by the React Server Components Webpack plugin. Only set this if you've configured the plugin to use a different filename.
-  config.react_server_client_manifest_file = "react-server-client-manifest.json"
+  # See Pro documentation for complete setup instructions.
 
   ################################################################################
   # SERVER BUNDLE SECURITY AND ORGANIZATION
diff --git a/docs/api-reference/view-helpers-api.md b/docs/api-reference/view-helpers-api.md
@@ -80,21 +80,6 @@ export default (props, _railsContext) => {
 
 ---
 
-### cached_react_component and cached_react_component_hash
-
-Fragment caching is a [React on Rails Pro](https://github.com/shakacode/react_on_rails/wiki) feature. The API is the same as the above, but for 2 differences:
-
-1. The `cache_key` takes the same parameters as any Rails `cache` view helper.
-1. The **props** are passed via a block so that evaluation of the props is not done unless the cache is broken. Suppose you put your props calculation into some method called `some_slow_method_that_returns_props`:
-
-```erb
-<%= cached_react_component("App", cache_key: [@user, @post], prerender: true) do
-  some_slow_method_that_returns_props
-end %>
-```
-
----
-
 ### rails_context
 
 You can call `rails_context` or `rails_context(server_side: true|false)` from your controller or view to see what values are in the Rails Context. Pass true or false depending on whether you want to see the server-side or the client-side `rails_context`. Typically, for computing cache keys, you should leave `server_side` as the default true. When calling this from a controller method, use `helpers.rails_context`.
@@ -132,6 +117,45 @@ This is a helper method that takes any JavaScript expression and returns the out
 
 ---
 
+## Pro-Only View Helpers
+
+The following view helpers are available exclusively with [React on Rails Pro](https://www.shakacode.com/react-on-rails-pro). These require a valid React on Rails Pro license and will not be available if the Pro gem is not installed or properly licensed.
+
+### cached_react_component and cached_react_component_hash
+
+Fragment caching helpers that cache React component rendering to improve performance. The API is the same as `react_component` and `react_component_hash`, but with these differences:
+
+1. The `cache_key` takes the same parameters as any Rails `cache` view helper.
+2. The **props** are passed via a block so that evaluation of the props is not done unless the cache is broken.
+
+Example usage:
+
+```erb
+<%= cached_react_component("App", cache_key: [@user, @post], prerender: true) do
+  some_slow_method_that_returns_props
+end %>
+```
+
+### stream_react_component
+
+Progressive server-side rendering using React 18+ streaming with `renderToPipeableStream`. This enables:
+- Faster Time to First Byte (TTFB)
+- Progressive page loading with Suspense boundaries
+- Better perceived performance
+
+See the [Streaming Server Rendering guide](../building-features/streaming-server-rendering.md) for usage details.
+
+### rsc_payload_react_component
+
+Renders React Server Component (RSC) payloads in NDJSON format for client-side consumption. Used in conjunction with RSC support to enable:
+- Reduced JavaScript bundle sizes
+- Server-side data fetching
+- Selective client-side hydration
+
+See the [React on Rails Pro Configuration](https://github.com/shakacode/react_on_rails/blob/master/react_on_rails_pro/docs/configuration.md) for RSC setup.
+
+---
+
 # More details
 
 See the [lib/react_on_rails/helper.rb](https://github.com/shakacode/react_on_rails/tree/master/lib/react_on_rails/helper.rb) source.
diff --git a/react_on_rails_pro/CHANGELOG.md b/react_on_rails_pro/CHANGELOG.md
@@ -19,9 +19,21 @@ You can find the **package** version numbers from this repo's tags and below in
 ### Added
 - Added `cached_stream_react_component` helper method, similar to `cached_react_component` but for streamed components.
 - **License Validation System**: Implemented comprehensive JWT-based license validation with offline verification using RSA-256 signatures. License validation occurs at startup in both Ruby and Node.js environments. Supports required fields (`sub`, `iat`, `exp`) and optional fields (`plan`, `organization`, `iss`). FREE evaluation licenses are available for 3 months at [shakacode.com/react-on-rails-pro](https://shakacode.com/react-on-rails-pro). [PR #1857](https://github.com/shakacode/react_on_rails/pull/1857) by [AbanoubGhadban](https://github.com/AbanoubGhadban).
+- **Pro-Specific Configurations Moved from Open-Source**: The following React Server Components (RSC) configurations are now exclusively in the Pro gem and should be configured in `ReactOnRailsPro.configure`:
+  - `rsc_bundle_js_file` - Path to the RSC bundle file
+  - `react_server_client_manifest_file` - Path to the React server client manifest
+  - `react_client_manifest_file` - Path to the React client manifest
+
+  These configurations were previously available in the open-source `ReactOnRails.configure` block but have been moved to Pro where they belong since RSC is a Pro-only feature.
+- **Streaming View Helpers Now Pro-Exclusive**: The following view helpers are now defined exclusively in the Pro gem:
+  - `stream_react_component` - Progressive SSR using React 18+ streaming
+  - `rsc_payload_react_component` - RSC payload rendering
+
+  These helpers were previously in the open-source gem but have been moved to Pro as they are Pro-only features.
 
 ### Changed (Breaking)
 - `config.prerender_caching`, which controls caching for non-streaming components, now also controls caching for streamed components. To disable caching for an individual render, pass `internal_option(:skip_prerender_cache)`.
+- **Configuration Migration Required**: If you are using RSC features, you must move the RSC-related configurations from `ReactOnRails.configure` to `ReactOnRailsPro.configure` in your initializers. See the migration example in the [React on Rails CHANGELOG](https://github.com/shakacode/react_on_rails/blob/master/CHANGELOG.md#unreleased).
 
 ## [4.0.0-rc.15] - 2025-08-11
 
diff --git a/react_on_rails_pro/docs/configuration.md b/react_on_rails_pro/docs/configuration.md
@@ -121,5 +121,45 @@ ReactOnRailsPro.configure do |config|
      Rails.root.join("public", "webpack", Rails.env, "loadable-stats.json"),
      Rails.root.join("public", "webpack", Rails.env, "manifest.json")
   ]
+
+  ################################################################################
+  # REACT SERVER COMPONENTS (RSC) CONFIGURATION
+  ################################################################################
+
+  # Enable React Server Components support
+  # When enabled, React on Rails Pro will support RSC rendering and streaming
+  # Default is false
+  config.enable_rsc_support = true
+
+  # Path to the RSC bundle file (relative to webpack output directory or absolute path)
+  # The RSC bundle contains only server components and references to client components.
+  # It's generated using the RSC Webpack Loader which transforms client components into
+  # references. This bundle is specifically used for generating RSC payloads and is
+  # configured with the 'react-server' condition.
+  # Default is "rsc-bundle.js"
+  config.rsc_bundle_js_file = "rsc-bundle.js"
+
+  # Path to the React client manifest file (typically in your webpack output directory)
+  # This manifest contains mappings for client components that need hydration.
+  # It's automatically generated by the React Server Components Webpack plugin and is
+  # required for client-side hydration of components.
+  # Only set this if you've configured the plugin to use a different filename.
+  # Default is "react-client-manifest.json"
+  config.react_client_manifest_file = "react-client-manifest.json"
+
+  # Path to the React server-client manifest file (typically in your webpack output directory)
+  # This manifest is used during server-side rendering with RSC to properly resolve
+  # references between server and client components.
+  # It's automatically generated by the React Server Components Webpack plugin.
+  # Only set this if you've configured the plugin to use a different filename.
+  # Default is "react-server-client-manifest.json"
+  config.react_server_client_manifest_file = "react-server-client-manifest.json"
+
+  # These RSC configuration files are crucial when implementing React Server Components
+  # with streaming, which offers benefits like:
+  # - Reduced JavaScript bundle sizes
+  # - Faster page loading
+  # - Selective hydration of client components
+  # - Progressive rendering with Suspense boundaries
 end
 ```
