react_on_rails_pro 16.4.0.rc.5 → 16.4.0.rc.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2b71e54f44331a34669c58c5f6997825fe0469a96de8520d24029605134068f2
-  data.tar.gz: ec4dd8f6d56ab2097f99dcd1c51c54002c2385595890c43fc959cb8ca2cc11ab
+  metadata.gz: d8d5365a9653da4cdc8ea771167d5b26dd03602c4977d7fea747ec2a07cc6900
+  data.tar.gz: 57afd9dc58238f94d2d008cc01900596a18cb63894786cb60ce99471902500c9
 SHA512:
-  metadata.gz: 3ab4f06e700c5710649c0edf4be00398eaeddad34704325cc426c14813b5db3c2a67f2af44832d6e7830b3c4982ad4994774ca0bc24d52afb575c2c7abfd2b25
-  data.tar.gz: a2c840298e0efda608cefedc7211ff8561788aa55eabe4efc9eaf461bf85a48971eaf8247bffee247c232b1caa2689d1348e89284d95043ba039e6cbc977a016
+  metadata.gz: fb6bb5c6f0b45d62151be232c4ddf9b8343aaa086162e1f8292f9468b2902c146a5668c1b1e79753a919a6063eae8ddbf1a19ad4cb8e178734e77fb9303efa1d
+  data.tar.gz: 9da57b6e9750c1f5fe4f830b375bfd2dd7e7e07b6c2135b5e9a30ec5156f70c4e41180a8737a205150bf7b8687dfa1b16c035bb88eb03fd3d89dbdc71e25c625

data/CONTRIBUTING.md

@@ -119,7 +119,7 @@ script/ci-changes-detector origin/master
 - Push Pro changes without testing locally first
 - Modify both Pro and main gem without running full tests
 
-For comprehensive CI documentation, see [`../docs/contributor-info/ci-optimization.md`](../docs/contributor-info/ci-optimization.md) in the repository root.
+For comprehensive CI documentation, see [`../internal/contributor-info/ci-optimization.md`](../internal/contributor-info/ci-optimization.md) in the repository root.
 
 # IDE/Editor Setup
 
@@ -395,5 +395,5 @@ rake release[17.0.0,false,verdaccio]
 
 For complete documentation, see:
 
-- [Root Release Documentation](../docs/contributor-info/releasing.md)
+- [Root Release Documentation](../internal/contributor-info/releasing.md)
 - Run `rake -D release` for inline help

data/Gemfile.development_dependencies

@@ -8,7 +8,7 @@ git_source(:github) { |repo| "https://github.com/#{repo}.git" }
 
 gem "react_on_rails", path: "../"
 
-gem "shakapacker", "9.5.0"
+gem "shakapacker", "9.6.1"
 gem "bootsnap", require: false
 gem "rails", "~> 7.1"
 gem "puma", "~> 6"

data/Gemfile.lock

@@ -9,7 +9,7 @@ GIT
 PATH
   remote: ..
   specs:
-    react_on_rails (16.4.0.rc.5)
+    react_on_rails (16.4.0.rc.7)
       addressable
       connection_pool
       execjs (~> 2.5)
@@ -20,7 +20,7 @@ PATH
 PATH
   remote: .
   specs:
-    react_on_rails_pro (16.4.0.rc.5)
+    react_on_rails_pro (16.4.0.rc.7)
       addressable
       async (>= 2.6)
       connection_pool
@@ -29,7 +29,7 @@ PATH
       httpx (~> 1.5)
       jwt (~> 2.7)
       rainbow
-      react_on_rails (= 16.4.0.rc.5)
+      react_on_rails (= 16.4.0.rc.7)
 
 GEM
   remote: https://rubygems.org/
@@ -165,7 +165,7 @@ GEM
     drb (2.2.3)
     equivalent-xml (0.6.0)
       nokogiri (>= 1.4.3)
-    erb (6.0.1)
+    erb (6.0.2)
     erubi (1.13.1)
     execjs (2.10.0)
     fakefs (2.8.0)
@@ -194,8 +194,9 @@ GEM
       concurrent-ruby (~> 1.0)
     io-console (0.8.2)
     io-event (1.14.2)
-    irb (1.16.0)
+    irb (1.17.0)
       pp (>= 0.6.0)
+      prism (>= 1.3.0)
       rdoc (>= 4.0.0)
       reline (>= 0.4.2)
     jbuilder (2.12.0)
@@ -230,7 +231,8 @@ GEM
     method_source (1.1.0)
     metrics (0.15.0)
     mini_mime (1.1.5)
-    minitest (6.0.1)
+    minitest (6.0.2)
+      drb (~> 2.0)
       prism (~> 1.5)
     mize (0.4.1)
       protocol (~> 2.0)
@@ -247,11 +249,11 @@ GEM
     net-smtp (0.5.1)
       net-protocol
     nio4r (2.7.5)
-    nokogiri (1.19.0-arm64-darwin)
+    nokogiri (1.19.1-arm64-darwin)
       racc (~> 1.4)
-    nokogiri (1.19.0-x86_64-darwin)
+    nokogiri (1.19.1-x86_64-darwin)
       racc (~> 1.4)
-    nokogiri (1.19.0-x86_64-linux-gnu)
+    nokogiri (1.19.1-x86_64-linux-gnu)
       racc (~> 1.4)
     package_json (0.2.0)
     parallel (1.27.0)
@@ -262,7 +264,7 @@ GEM
     pp (0.6.3)
       prettyprint
     prettyprint (0.2.0)
-    prism (1.6.0)
+    prism (1.9.0)
     protocol (2.0.0)
       ruby_parser (~> 3.0)
     pry (0.14.2)
@@ -282,7 +284,7 @@ GEM
     puma (6.5.0)
       nio4r (~> 2.0)
     racc (1.8.1)
-    rack (3.2.4)
+    rack (3.2.5)
     rack-proxy (0.7.7)
       rack
     rack-session (2.1.1)
@@ -310,8 +312,8 @@ GEM
       activesupport (>= 5.0.0)
       minitest
       nokogiri (>= 1.6)
-    rails-html-sanitizer (1.6.2)
-      loofah (~> 2.21)
+    rails-html-sanitizer (1.7.0)
+      loofah (~> 2.25)
       nokogiri (>= 1.15.7, != 1.16.7, != 1.16.6, != 1.16.5, != 1.16.4, != 1.16.3, != 1.16.2, != 1.16.1, != 1.16.0.rc1, != 1.16.0)
     railties (7.2.3)
       actionpack (= 7.2.3)
@@ -330,7 +332,7 @@ GEM
       ffi (~> 1.0)
     rbs (3.9.5)
       logger
-    rdoc (7.1.0)
+    rdoc (7.2.0)
       erb
       psych (>= 4.0.0)
       tsort
@@ -414,9 +416,9 @@ GEM
       rexml (~> 3.2, >= 3.2.5)
       rubyzip (>= 1.2.2, < 3.0)
       websocket (~> 1.0)
-    semantic_range (3.1.0)
+    semantic_range (3.1.1)
     sexp_processor (4.17.1)
-    shakapacker (9.5.0)
+    shakapacker (9.6.1)
       activesupport (>= 5.2)
       package_json
       rack-proxy (>= 0.6.1)
@@ -483,7 +485,7 @@ GEM
     xpath (3.2.0)
       nokogiri (~> 1.8)
     yard (0.9.36)
-    zeitwerk (2.7.4)
+    zeitwerk (2.7.5)
 
 PLATFORMS
   arm64-darwin-24
@@ -531,7 +533,7 @@ DEPENDENCIES
   sass-rails
   scss_lint
   selenium-webdriver (= 4.9.0)
-  shakapacker (= 9.5.0)
+  shakapacker (= 9.6.1)
   spring
   spring-watcher-listen
   sprockets

data/README.md

@@ -191,11 +191,12 @@ High-performance standalone Node.js server for server-side rendering with connec
 **Example Configuration:**
 
 ```javascript
-// react-on-rails-pro/react-on-rails-pro-node-renderer.js
-const { reactOnRailsProNodeRenderer } = require('@shakacode-tools/react-on-rails-pro-node-renderer');
+// node-renderer.js
+const path = require('path');
+const { reactOnRailsProNodeRenderer } = require('react-on-rails-pro-node-renderer');
 
 reactOnRailsProNodeRenderer({
-  bundlePath: path.resolve(__dirname, '../app/assets/webpack'),
+  serverBundleCachePath: path.resolve(__dirname, '.node-renderer-bundles'),
   port: 3800,
   workersCount: 4,
   supportModules: true, // Required for loadable-components

data/app/helpers/react_on_rails_pro_helper.rb

@@ -314,7 +314,13 @@ module ReactOnRailsProHelper
 
     # Enqueue remaining chunks asynchronously
     @async_barrier.async do
-      rest_chunks.each { |chunk| @main_output_queue.enqueue(chunk) }
+      rest_chunks.each do |chunk|
+        break if response.stream.closed?
+
+        @main_output_queue.enqueue(chunk)
+      end
+    rescue Async::Queue::ClosedError
+      # Queue closed due to error/disconnect in another component — stop enqueuing
     end
 
     # Return first chunk directly
@@ -436,21 +442,51 @@ module ReactOnRailsProHelper
     # Start an async task on the barrier to stream all chunks
     @async_barrier.async do
       stream = yield
-      process_stream_chunks(stream, first_chunk_var, all_chunks)
-      on_complete&.call(all_chunks)
+      fully_consumed = process_stream_chunks(stream, first_chunk_var, all_chunks)
+      on_complete&.call(all_chunks) if fully_consumed
+    rescue StandardError => e
+      # Propagate the error to the calling fiber via the variable.
+      # Async::Variable can only be resolved once — if it was already resolved
+      # (first chunk was returned successfully), the assignment raises and we
+      # fall through to re-raise so barrier.wait propagates the error later.
+      begin
+        first_chunk_var.value = e
+        # Variable accepted the error — this is a pre-first-chunk failure (e.g., shell error).
+        # The caller will detect the Exception value and raise it synchronously,
+        # BEFORE the response is committed, enabling a proper HTTP redirect.
+        # Do NOT re-raise here: the caller owns the error now.
+      rescue StandardError
+        # Variable was already resolved — the first chunk was returned successfully.
+        # This is a post-first-chunk error. Re-raise so barrier.wait propagates it
+        # (the response is already committed at that point, so only JS redirect is possible).
+        raise e
+      end
     end
 
-    # Wait for and return the first chunk (blocking)
-    first_chunk_var.wait
-    first_chunk_var.value
+    # Wait for and return the first chunk (blocking).
+    # Async::Variable#wait blocks until resolved, then returns the stored value.
+    result = first_chunk_var.wait
+
+    # If the async task stored an exception (pre-first-chunk error), raise it now.
+    # This happens BEFORE response.stream.write(template_string) in
+    # stream_view_containing_react_components, so the response is NOT yet committed
+    # and rescue_from can perform a proper HTTP redirect.
+    raise result if result.is_a?(StandardError)
+
+    result
   end
 
+  # Returns true if the stream was fully consumed, false if aborted (client disconnect).
+  # When false, callers must NOT invoke on_complete to avoid caching partial data.
   def process_stream_chunks(stream, first_chunk_var, all_chunks)
     is_first = true
 
     stream.each_chunk do |chunk|
-      # Check if client disconnected before processing chunk
-      break if response.stream.closed?
+      # Client disconnected — abort without caching partial results
+      if response.stream.closed?
+        first_chunk_var.value = nil if is_first
+        return false
+      end
 
       all_chunks&.push(chunk)
 
@@ -466,6 +502,7 @@ module ReactOnRailsProHelper
 
     # Handle case where stream has no chunks
     first_chunk_var.value = nil if is_first
+    true
   end
 
   def internal_stream_react_component(component_name, options = {})

data/docs/code-splitting-loadable-components.md

@@ -284,9 +284,8 @@ reactOnRailsProNodeRenderer(config);
 ## Making HMR Work
 
 To make HMR work, it's best to disable loadable-components when using the Dev Server.
-Note: you will need access to our **private** React on Rails Pro repository to open the following links.
 
-Take a look at the code searches for ['imports-loadable'](https://github.com/shakacode/react_on_rails_pro/search?q=imports-loadable&type=code) and ['imports-hmr'](https://github.com/shakacode/react_on_rails_pro/search?q=imports-hmr&type=code)
+Take a look at the code searches for ['imports-loadable'](https://github.com/shakacode/react_on_rails/search?q=imports-loadable&type=code) and ['imports-hmr'](https://github.com/shakacode/react_on_rails/search?q=imports-hmr&type=code)
 
 The general concept is that we have a non-loadable, HMR-ready, file that substitutes for the loadable-enabled one, with the suffixes `imports-hmr.js` instead of `imports-loadable.js`
 
@@ -294,7 +293,7 @@ The general concept is that we have a non-loadable, HMR-ready, file that substit
 
 Use the [NormalModuleReplacement plugin](https://webpack.js.org/plugins/normal-module-replacement-plugin/):
 
-[code](https://github.com/shakacode/react_on_rails_pro/blob/a361f4e163b9170f180ae07ee312fb9b4c719fc3/spec/dummy/config/webpack/environment.js#L81-L91)
+[code](https://github.com/shakacode/react_on_rails/blob/master/react_on_rails_pro/spec/dummy/config/webpack/commonWebpackConfig.js#L41-L49)
 
 ```js
 if (isWebpackDevServer) {
@@ -313,17 +312,15 @@ And compare:
 
 ### Routes file
 
-Note: you will need access to our **private** React on Rails Pro repository to open the following links.
-
-- [spec/dummy/client/app/components/Loadable/routes/Routes.imports-hmr.jsx](https://github.com/shakacode/react_on_rails_pro/blob/master/spec/dummy/client/app/components/Loadable/routes/Routes.imports-hmr.jsx)
-- [spec/dummy/client/app/components/Loadable/routes/Routes.imports-loadable.jsx](https://github.com/shakacode/react_on_rails_pro/blob/master/spec/dummy/client/app/components/Loadable/routes/Routes.imports-loadable.jsx)
+- [spec/dummy/client/app/components/Loadable/routes/Routes.imports-hmr.jsx](https://github.com/shakacode/react_on_rails/blob/master/react_on_rails_pro/spec/dummy/client/app/components/Loadable/routes/Routes.imports-hmr.jsx)
+- [spec/dummy/client/app/components/Loadable/routes/Routes.imports-loadable.jsx](https://github.com/shakacode/react_on_rails/blob/master/react_on_rails_pro/spec/dummy/client/app/components/Loadable/routes/Routes.imports-loadable.jsx)
 
 ### Client-Side Startup
 
-- [spec/dummy/client/app/loadable/loadable-client.imports-hmr.js](https://github.com/shakacode/react_on_rails_pro/blob/master/spec/dummy/client/app/loadable/loadable-client.imports-hmr.js)
-- [spec/dummy/client/app/loadable/loadable-client.imports-loadable.jsx](https://github.com/shakacode/react_on_rails_pro/blob/master/spec/dummy/client/app/loadable/loadable-client.imports-loadable.jsx)
+- [spec/dummy/client/app/loadable/loadable-client.imports-hmr.jsx](https://github.com/shakacode/react_on_rails/blob/master/react_on_rails_pro/spec/dummy/client/app/loadable/loadable-client.imports-hmr.jsx)
+- [spec/dummy/client/app/loadable/loadable-client.imports-loadable.jsx](https://github.com/shakacode/react_on_rails/blob/master/react_on_rails_pro/spec/dummy/client/app/loadable/loadable-client.imports-loadable.jsx)
 
 ### Server-Side Startup
 
-- [spec/dummy/client/app/loadable/loadable-server.imports-hmr.jsx](https://github.com/shakacode/react_on_rails_pro/blob/master/spec/dummy/client/app/loadable/loadable-server.imports-hmr.jsx)
-- [spec/dummy/client/app/loadable/loadable-server.imports-loadable.jsx](https://github.com/shakacode/react_on_rails_pro/blob/master/spec/dummy/client/app/loadable/loadable-server.imports-loadable.jsx)
+- [spec/dummy/client/app/loadable/loadable-server.imports-hmr.jsx](https://github.com/shakacode/react_on_rails/blob/master/react_on_rails_pro/spec/dummy/client/app/loadable/loadable-server.imports-hmr.jsx)
+- [spec/dummy/client/app/loadable/loadable-server.imports-loadable.jsx](https://github.com/shakacode/react_on_rails/blob/master/react_on_rails_pro/spec/dummy/client/app/loadable/loadable-server.imports-loadable.jsx)

data/docs/installation.md

@@ -8,7 +8,8 @@ Check the [CHANGELOG](https://github.com/shakacode/react_on_rails/blob/master/CH
 
 ## Version Format
 
-For the below docs, find the desired `<version>` in the CHANGELOG. Note that for pre-release versions:
+For the commands below, choose versions from the CHANGELOG and replace placeholders like
+`<gem_version>` and `<npm_version>`. Note that for pre-release versions:
 
 - Gems use all periods: `16.2.0.beta.1`
 - NPM packages use dashes: `16.2.0-beta.1`
@@ -22,11 +23,15 @@ The easiest way to set up React on Rails Pro is using the generator. This automa
 For new React on Rails apps, use the `--pro` flag:
 
 ```bash
-# Add the Pro gem to your Gemfile first
-bundle add react_on_rails_pro
+# Add the Pro gem first (pin exact version)
+bundle add react_on_rails_pro --version="<gem_version>" --strict
+
+# The generator requires a clean git working tree
+git add .
+git commit -m "Prepare app for React on Rails Pro install"
 
 # Run the generator with --pro
-rails generate react_on_rails:install --pro
+bundle exec rails generate react_on_rails:install --pro
 ```
 
 This creates the Pro initializer, node-renderer.js, installs npm packages, and adds the Node Renderer to Procfile.dev.
@@ -37,17 +42,31 @@ For existing React on Rails apps, use the standalone Pro generator:
 
 ```bash
 # Add the Pro gem to your Gemfile
-bundle add react_on_rails_pro
+bundle add react_on_rails_pro --version="<gem_version>" --strict
 
 # Run the Pro generator
-rails generate react_on_rails:pro
+bundle exec rails generate react_on_rails:pro
 ```
 
 The standalone generator adds Pro-specific files and modifies your existing webpack configs (`serverWebpackConfig.js` and `ServerClientOrBoth.js`) to enable Pro features like `libraryTarget: 'commonjs2'` and `target = 'node'`.
 
 ## After Running the Generator
 
-You still need to configure your license. Set the environment variable:
+Run a quick validation, then configure your license.
+
+```bash
+bundle exec rails react_on_rails:doctor
+bin/shakapacker
+bin/dev
+```
+
+If port 3000 is already in use:
+
+```bash
+PORT=3001 bin/dev
+```
+
+Set the license environment variable:
 
 ```bash
 export REACT_ON_RAILS_PRO_LICENSE="your-license-token-here"
@@ -61,10 +80,10 @@ RSC requires React on Rails Pro and React 19.0.x. To add RSC support, use `--rsc
 
 ```bash
 # Fresh install with RSC
-rails generate react_on_rails:install --rsc
+bundle exec rails generate react_on_rails:install --rsc
 
 # Or add RSC to existing Pro app
-rails generate react_on_rails:rsc
+bundle exec rails generate react_on_rails:rsc
 ```
 
 The RSC generator creates `rscWebpackConfig.js`, adds `RSCWebpackPlugin` to both server and client webpack configs, configures `RSC_BUNDLE_ONLY` handling in `ServerClientOrBoth.js`, and sets up the RSC bundle watcher process. See [React Server Components](./react-server-components/tutorial.md) for more information.
@@ -86,7 +105,7 @@ Ensure your **Rails** app is using the **react_on_rails** gem, version 16.0.0 or
 Add the `react_on_rails_pro` gem to your **Gemfile**:
 
 ```ruby
-gem "react_on_rails_pro", "~> 16.2"
+gem "react_on_rails_pro", "= <gem_version>"
 ```
 
 Then run:
@@ -138,19 +157,19 @@ All React on Rails Pro users need to install the `react-on-rails-pro` npm packag
 ### Using npm:
 
 ```bash
-npm install react-on-rails-pro
+npm install react-on-rails-pro@<npm_version> --save-exact
 ```
 
 ### Using yarn:
 
 ```bash
-yarn add react-on-rails-pro
+yarn add react-on-rails-pro@<npm_version> --exact
 ```
 
 ### Using pnpm:
 
 ```bash
-pnpm add react-on-rails-pro
+pnpm add react-on-rails-pro@<npm_version> --save-exact
 ```
 
 ## Usage
@@ -187,13 +206,13 @@ See the [React Server Components tutorial](./react-server-components/tutorial.md
 ### Using npm:
 
 ```bash
-npm install react-on-rails-pro-node-renderer
+npm install react-on-rails-pro-node-renderer@<npm_version> --save-exact
 ```
 
 ### Using yarn:
 
 ```bash
-yarn add react-on-rails-pro-node-renderer
+yarn add react-on-rails-pro-node-renderer@<npm_version> --exact
 ```
 
 ### Add to package.json:
@@ -201,7 +220,7 @@ yarn add react-on-rails-pro-node-renderer
 ```json
 {
   "dependencies": {
-    "react-on-rails-pro-node-renderer": "^16.2.0"
+    "react-on-rails-pro-node-renderer": "<npm_version>"
   }
 }
 ```

data/docs/react-server-components/glossary.md

@@ -9,6 +9,16 @@ A React architecture that allows components to execute exclusively on the server
 - Improved initial page load
 - Better SEO
 
+<!-- H2 is intentional here: this callout must stand out above the H3 glossary entries to prevent confusion -->
+## Important: `.client.` / `.server.` File Suffixes Are Unrelated
+
+React on Rails has a separate, older concept where files can have `.client.jsx` or `.server.jsx` suffixes. These control **which webpack bundle** imports the file (client bundle vs. server bundle for SSR) and have nothing to do with React Server Components.
+
+- `Component.client.jsx` → only imported in the client (browser) bundle
+- `Component.server.jsx` → only imported in the server and the RSC bundle
+
+A `.server.jsx` file is NOT a React Server Component. A `.client.jsx` file is NOT necessarily a React Client Component. The RSC classification is determined solely by the `'use client'` directive, regardless of file suffix. These suffixes only make sense for client components, as server components exist only in the RSC bundle. See the [auto-bundling docs](../../../docs/core-concepts/auto-bundling-file-system-based-automated-bundle-generation.md#server-rendering-and-client-rendering-components) for details on file suffixes.
+
 ## Types of Components
 
 ### Server Components

data/docs/ruby-api.md

@@ -1,11 +1,9 @@
 # Ruby API
 
-Note: you will need access to our **private** React on Rails Pro repository to open the following links.
-
 ## View Helpers
 
-See the [app/helpers/react_on_rails_pro_helper.rb](https://github.com/shakacode/react_on_rails_pro/blob/master/app/helpers/react_on_rails_pro_helper.rb) source.
+See the [app/helpers/react_on_rails_pro_helper.rb](https://github.com/shakacode/react_on_rails/blob/master/react_on_rails_pro/app/helpers/react_on_rails_pro_helper.rb) source.
 
 ## Utility Methods
 
-See the [lib/react_on_rails_pro/utils.rb](https://github.com/shakacode/react_on_rails_pro/blob/master/lib/react_on_rails_pro/utils.rb) source.
+See the [lib/react_on_rails_pro/utils.rb](https://github.com/shakacode/react_on_rails/blob/master/react_on_rails_pro/lib/react_on_rails_pro/utils.rb) source.

data/docs/streaming-server-rendering.md

@@ -155,6 +155,37 @@ For example, with our `MyStreamingComponent`, the sequence might be:
 </script>
 ```
 
+## Compression Middleware Compatibility
+
+Streaming responses use `ActionController::Live`, which writes chunks to a `SizedQueue` (a destructive, non-idempotent data structure). Standard Rack compression middleware (`Rack::Deflater`, `Rack::Brotli`) works correctly with streaming **by default** — each chunk is compressed and flushed immediately, preserving low TTFB.
+
+However, if you pass an `:if` condition that calls `body.each` to check the response size, **streaming responses will deadlock**. The `:if` callback destructively consumes all chunks from the queue, leaving nothing for the compressor to read.
+
+```ruby
+# BAD — causes deadlocks with streaming responses
+config.middleware.use Rack::Deflater, if: lambda { |*, body|
+  sum = 0
+  body.each { |i| sum += i.length }  # destructive — drains the queue
+  sum > 512
+}
+```
+
+The [Rack SPEC](https://github.com/rack/rack/blob/main/SPEC.rdoc) states that `each` must only be called once and middleware must not call `each` directly unless the body responds to `to_ary`. Streaming bodies explicitly do not support `to_ary`.
+
+**Correct pattern** — check `to_ary` before iterating:
+
+```ruby
+config.middleware.use Rack::Deflater, if: lambda { |*, body|
+  # Streaming bodies don't support to_ary — always compress them.
+  # Rack::Deflater handles streaming correctly with sync flush per chunk.
+  return true unless body.respond_to?(:to_ary)
+
+  body.to_ary.sum(&:bytesize) > 512
+}
+```
+
+The same applies to `Rack::Brotli` or any middleware that accepts an `:if` callback.
+
 ## When to Use Streaming
 
 Streaming SSR is particularly valuable in specific scenarios. Here's when to consider it:

data/docs/troubleshooting.md

@@ -1,3 +1,11 @@
 # Troubleshooting
 
 For issues related to upgrading from GitHub Packages to public distribution, see the [Upgrading Guide](./updating.md).
+
+## Streaming SSR request hangs indefinitely
+
+**Symptom**: Requests to streaming pages (or RSC payload endpoints) hang forever and never complete.
+
+**Cause**: A compression middleware (`Rack::Deflater`, `Rack::Brotli`) is configured with an `:if` condition that calls `body.each` to check the response size. This destructively consumes streaming chunks from the `SizedQueue`, causing a deadlock.
+
+**Fix**: See the "Compression Middleware Compatibility" section in the [Streaming Server Rendering guide](./streaming-server-rendering.md).

data/docs/updating.md

@@ -6,7 +6,7 @@
 
 This guide is for existing React on Rails Pro customers who are:
 
-- Currently using GitHub Packages authentication (private distribution)
+- Previously using GitHub Packages authentication (private distribution)
 - On version 16.2.0-beta.x or earlier
 - Upgrading to version 16.2.0 or higher
 
@@ -198,6 +198,16 @@ export REACT_ON_RAILS_PRO_LICENSE="your-license-token-here"
 
 For complete licensing details, see [LICENSE_SETUP.md](https://github.com/shakacode/react_on_rails/blob/master/react_on_rails_pro/LICENSE_SETUP.md).
 
+### Additional Upgrade Notes
+
+#### Upgrading to 16.4.0 or later
+
+##### RSC payload template overrides
+
+React on Rails Pro now renders the built-in RSC payload template with `formats: [:text]` so Rails view annotations cannot inject HTML comments into NDJSON responses.
+
+If your app overrides `custom_rsc_payload_template`, make sure that override resolves to a text or format-neutral template path, such as `app/views/.../rsc_payload.text.erb`. Overrides that only exist as `.html.erb` templates will raise `ActionView::MissingTemplate` when the RSC payload endpoint renders.
+
 ### Verify Migration
 
 #### 1. Verify Gem Installation

data/lib/react_on_rails_pro/concerns/rsc_payload_renderer.rb

@@ -15,7 +15,20 @@ module ReactOnRailsPro
 
       stream_view_containing_react_components(
         template: custom_rsc_payload_template,
-        layout: false
+        layout: false,
+        # Render as text so Rails does not inject HTML view annotation comments
+        # into the NDJSON stream. Custom template overrides must resolve to a
+        # text or format-neutral template, not `.html.erb`.
+        formats: [:text],
+        content_type: "application/x-ndjson"
+      )
+    rescue ActionView::MissingTemplate => e
+      raise e.exception(
+        "[React on Rails Pro] RSC payload templates are now rendered with format :text. " \
+        "If you override `custom_rsc_payload_template`, make sure the override resolves to " \
+        "a text or format-neutral template (for example `rsc_payload.text.erb`) instead of " \
+        "only `.html.erb`. See react_on_rails_pro/docs/updating.md for upgrade notes.\n\n" \
+        "Original error: #{e.message}"
       )
     end
 

data/lib/react_on_rails_pro/concerns/stream.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "English"
+
 module ReactOnRailsPro
   module Stream
     extend ActiveSupport::Concern
@@ -12,6 +14,10 @@ module ReactOnRailsPro
     #
     # @param template [String] The path to the template file to be streamed.
     # @param close_stream_at_end [Boolean] Whether to automatically close the stream after rendering (default: true).
+    # @param content_type [String, nil] Optional response content type. Set after rendering but before the first
+    #   stream write, overriding any content type inferred from the template format. When using
+    #   a non-HTML `formats:` value (for example `[:text]`), pass `content_type` too unless
+    #   committing the format-derived MIME type is intentional.
     # @param render_options [Hash] Additional options to pass to `render_to_string`.
     #
     # components must be added to the view using the `stream_react_component` helper.
@@ -30,10 +36,13 @@ module ReactOnRailsPro
     #       For more details, refer to `lib/react_on_rails/helper.rb` in the react_on_rails repository.
     #
     # @see ReactOnRails::Helper#stream_react_component
-    def stream_view_containing_react_components(template:, close_stream_at_end: true, **render_options)
+    def stream_view_containing_react_components(
+      template:, close_stream_at_end: true, content_type: nil, **render_options
+    )
       require "async"
       require "async/barrier"
       require "async/limited_queue"
+      warn_on_non_html_formats_without_content_type(render_options[:formats], content_type)
 
       Sync do |parent_task|
         # Initialize async primitives for concurrent component streaming
@@ -41,20 +50,33 @@ module ReactOnRailsPro
         buffer_size = ReactOnRailsPro.configuration.concurrent_component_streaming_buffer_size
         @main_output_queue = Async::LimitedQueue.new(buffer_size)
 
-        # Render template - components will start streaming immediately
+        # Render template - components will start streaming immediately.
+        # If a shell error occurs, consumer_stream_async raises PrerenderError here
+        # (BEFORE the response is committed), enabling a proper HTTP redirect.
         template_string = render_to_string(template: template, **render_options)
         # View may contain extra newlines, chunk already contains a newline
         # Having multiple newlines between chunks causes hydration errors
         # So we strip extra newlines from the template string and add a single newline
+        # `formats: [:text]` causes render_to_string to set response.content_type
+        # to `text/plain`; override it here before the first stream write, which
+        # is when ActionController::Live commits headers. render_to_string itself
+        # never writes to response.stream, so this assignment is always safe.
+        response.content_type = content_type if content_type
         response.stream.write(template_string)
 
-        begin
-          drain_streams_concurrently(parent_task)
-          # Do not close the response stream in an ensure block.
-          # If an error occurs we may need the stream open to send diagnostic/error details
-          # (for example, ApplicationController#rescue_from in the dummy app).
-          response.stream.close if close_stream_at_end
-        end
+        drain_streams_concurrently(parent_task)
+        # Do not close the response stream in an ensure block.
+        # If an error occurs we may need the stream open to send diagnostic/error details
+        # (for example, ApplicationController#rescue_from in the dummy app).
+        response.stream.close if close_stream_at_end
+      rescue StandardError
+        # Stop all streaming tasks to prevent leaked async work.
+        # For pre-commit errors (e.g., shell error raised during render_to_string),
+        # the barrier may still have pending tasks that must be cancelled.
+        # For post-commit errors (from drain_streams_concurrently), the barrier
+        # is already stopped inside that method — stopping again is a no-op.
+        @async_barrier&.stop
+        raise
       end
     end
 
@@ -72,8 +94,6 @@ module ReactOnRailsPro
     # - Barrier is stopped to cancel all producer tasks, preventing wasted work
     # - No exception propagates to the controller for client disconnects
     def drain_streams_concurrently(parent_task)
-      client_disconnected = false
-
       writing_task = parent_task.async do
         # Drain all remaining chunks from the queue to the response stream
         while (chunk = @main_output_queue.dequeue)
@@ -81,8 +101,13 @@ module ReactOnRailsPro
         end
       rescue IOError, Errno::EPIPE => e
         # Client disconnected - stop writing gracefully
-        client_disconnected = true
         log_client_disconnect("writer", e)
+      ensure
+        # Cancel all producers when writer exits for ANY reason (normal completion,
+        # client disconnect, or unexpected error). Prevents deadlock where producers
+        # block on enqueue to a full queue that nobody is consuming.
+        # Idempotent — no-op if barrier tasks already completed.
+        @async_barrier.stop
       end
 
       # Wait for all component streaming tasks to complete
@@ -93,16 +118,22 @@ module ReactOnRailsPro
         raise e
       end
     ensure
-      # Close the queue first to unblock writing_task (it may be waiting on dequeue)
-      @main_output_queue.close
+      # Capture the primary exception (if any) BEFORE any cleanup that could raise.
+      # In an ensure block, $ERROR_INFO holds the exception currently propagating
+      # out of the method (nil if returning normally). We must snapshot it before
+      # the begin/rescue below, where $ERROR_INFO would reflect the caught exception.
+      primary_exception = $ERROR_INFO
 
-      # Wait for writing_task to ensure client_disconnected flag is set
-      # before we check it (fixes race condition where ensure runs before
-      # writing_task's rescue block sets the flag)
-      writing_task.wait
+      # Close the queue to unblock writing_task (it may be waiting on dequeue)
+      @main_output_queue.close
 
-      # If client disconnected, stop all producer tasks to avoid wasted work
-      @async_barrier.stop if client_disconnected
+      # Wait for writing_task to finish. Wrap in rescue to avoid masking a primary
+      # exception (e.g., producer error) with a secondary writing_task exception.
+      begin
+        writing_task.wait
+      rescue StandardError
+        raise unless primary_exception
+      end
     end
 
     def log_client_disconnect(context, exception)
@@ -112,5 +143,19 @@ module ReactOnRailsPro
         "[React on Rails Pro] Client disconnected during streaming (#{context}): #{exception.class}"
       end
     end
+
+    def warn_on_non_html_formats_without_content_type(formats, content_type)
+      return if content_type.present?
+
+      requested_formats = Array(formats).compact.map(&:to_sym)
+      return if requested_formats.empty? || requested_formats.all?(:html)
+
+      Rails.logger.warn(
+        "[React on Rails Pro] stream_view_containing_react_components received non-HTML formats " \
+        "#{requested_formats.inspect} without `content_type:`. Rails will commit the format-derived " \
+        "MIME type (for example `text/plain` for `:text`). Pass `content_type:` explicitly when " \
+        "streaming non-HTML responses."
+      )
+    end
   end
 end

data/lib/react_on_rails_pro/engine.rb

@@ -7,8 +7,10 @@ module ReactOnRailsPro
     LICENSE_URL = "https://www.shakacode.com/react-on-rails-pro/"
     # TODO: Remove this legacy migration warning path after 16.5.0 stable release (target: 2026-05-31).
     LEGACY_LICENSE_FILE = "config/react_on_rails_pro_license.key"
+    RSC_STREAMING_MIDDLEWARE_WARNING_TARGETS = ["Rack::Deflater"].freeze
     private_constant :LICENSE_URL
     private_constant :LEGACY_LICENSE_FILE
+    private_constant :RSC_STREAMING_MIDDLEWARE_WARNING_TARGETS
 
     initializer "react_on_rails_pro.routes" do
       ActionDispatch::Routing::Mapper.include ReactOnRailsPro::Routes
@@ -20,6 +22,10 @@ module ReactOnRailsPro
       config.after_initialize { ReactOnRailsPro::Engine.log_license_status }
     end
 
+    initializer "react_on_rails_pro.check_rsc_streaming_middleware" do
+      config.after_initialize { ReactOnRailsPro::Engine.log_rsc_streaming_middleware_warning }
+    end
+
     class << self
       def log_license_status
         status = ReactOnRailsPro::LicenseValidator.license_status
@@ -40,6 +46,24 @@ module ReactOnRailsPro
         end
       end
 
+      def log_rsc_streaming_middleware_warning
+        return unless ReactOnRailsPro.configuration.enable_rsc_support
+        return if Rails.env.test?
+
+        middleware_names = middleware_stack_names
+        problematic = RSC_STREAMING_MIDDLEWARE_WARNING_TARGETS & middleware_names
+        return if problematic.empty?
+
+        route_path = ReactOnRailsPro.configuration.rsc_payload_generation_url_path
+        Rails.logger.warn(
+          "[React on Rails Pro] React Server Components support is enabled and the middleware " \
+          "stack includes #{problematic.join(', ')}. Compression and other response-transforming " \
+          "middleware can interfere with ActionController::Live NDJSON streaming. If your " \
+          "`#{route_path}` payload route is not already exempt, consider bypassing " \
+          "#{problematic.join(', ')} for that endpoint if you see stalled or corrupted RSC payloads."
+        )
+      end
+
       private
 
       def log_valid_license
@@ -105,6 +129,40 @@ module ReactOnRailsPro
           Rails.logger.info message
         end
       end
+
+      def middleware_stack_names
+        middleware_stack = Rails.application&.middleware
+        return [] unless middleware_stack
+
+        entries =
+          if middleware_stack.respond_to?(:middlewares)
+            middleware_stack.middlewares
+          elsif middleware_stack.respond_to?(:to_a)
+            middleware_stack.to_a
+          else
+            Array(middleware_stack)
+          end
+
+        entries.filter_map { |entry| middleware_entry_name(entry) }.uniq
+      end
+
+      def middleware_entry_name(entry)
+        candidate =
+          if entry.respond_to?(:klass) && entry.klass
+            entry.klass
+          elsif entry.is_a?(Array)
+            entry.first
+          else
+            entry
+          end
+
+        case candidate
+        when Module
+          candidate.name
+        else
+          candidate.to_s.presence
+        end
+      end
     end
   end
 end

data/lib/react_on_rails_pro/request.rb

@@ -319,6 +319,16 @@ module ReactOnRailsPro
           end
 
           response = HTTPX.get(path)
+          error = response.error
+          if error
+            # Re-raise via rescue so Ruby sets error.cause for exception chaining.
+            begin
+              raise error
+            rescue StandardError
+              raise ReactOnRailsPro::Error, "Failed to fetch dev-server asset from #{path}: #{error}"
+            end
+          end
+
           response.body
         else
           Pathname.new(path)

data/lib/react_on_rails_pro/stream_request.rb

@@ -113,7 +113,7 @@ module ReactOnRailsPro
 
     def process_response_chunks(stream_response, error_body)
       loop_response_lines(stream_response) do |chunk|
-        if stream_response.is_a?(HTTPX::ErrorResponse) || stream_response.status >= 400
+        if response_has_error_status?(stream_response)
           error_body << chunk
           next
         end
@@ -123,6 +123,15 @@ module ReactOnRailsPro
       end
     end
 
+    def response_has_error_status?(response)
+      return true if response.is_a?(HTTPX::ErrorResponse)
+
+      response.status >= 400
+    rescue NoMethodError
+      # HTTPX::StreamResponse can fail to delegate #status for non-streaming errors.
+      true
+    end
+
     def handle_http_error(error, error_body, send_bundle)
       response = error.response
       case response.status

data/lib/react_on_rails_pro/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module ReactOnRailsPro
-  VERSION = "16.4.0.rc.5"
+  VERSION = "16.4.0.rc.7"
   PROTOCOL_VERSION = "2.0.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: react_on_rails_pro
 version: !ruby/object:Gem::Version
-  version: 16.4.0.rc.5
+  version: 16.4.0.rc.7
 platform: ruby
 authors:
 - Justin Gordon
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-02-26 00:00:00.000000000 Z
+date: 2026-03-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: addressable
@@ -128,14 +128,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 16.4.0.rc.5
+        version: 16.4.0.rc.7
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 16.4.0.rc.5
+        version: 16.4.0.rc.7
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -223,15 +223,12 @@ files:
 - Rakefile
 - app/controllers/react_on_rails_pro/rsc_payload_controller.rb
 - app/helpers/react_on_rails_pro_helper.rb
-- app/views/react_on_rails_pro/rsc_payload.html.erb
+- app/views/react_on_rails_pro/rsc_payload.text.erb
 - babel.config.js
 - docs/bundle-caching.md
 - docs/caching.md
 - docs/code-splitting-loadable-components.md
 - docs/configuration.md
-- docs/contributors-info/onboarding-customers.md
-- docs/contributors-info/releasing.md
-- docs/contributors-info/style.md
 - docs/home-pro.md
 - docs/installation.md
 - docs/js-memory-leaks.md

data/docs/contributors-info/onboarding-customers.md

@@ -1,7 +0,0 @@
-# Creating a github OAuth Token
-
-_[Document for ShakaCode Staff](https://docs.google.com/document/d/10snzXEWgkorcai76_OxlhjQcDae_WoxRfBCdVbmcQoU/edit)_
-
-# Customer Steps
-
-See [Installation](../installation.md).

data/docs/contributors-info/releasing.md

@@ -1,41 +0,0 @@
-# Releasing React on Rails Pro
-
-⚠️ **This documentation is outdated.**
-
-React on Rails Pro is now released together with React on Rails using a unified release script.
-
-## Current Release Process
-
-Please refer to the main release documentation:
-
-👉 **[/docs/contributor-info/releasing.md](../../../docs/contributor-info/releasing.md)**
-
-Or run from the repository root:
-
-```bash
-cd .. && rake -D release
-```
-
-## Quick Reference
-
-```bash
-# From repository root (not from react_on_rails_pro/)
-cd /path/to/react_on_rails
-
-# Release with version bump
-rake release[17.0.0]
-
-# Dry run first (recommended)
-rake release[17.0.0,true]
-
-# Test with local Verdaccio
-rake release[17.0.0,false,verdaccio]
-```
-
-This unified script releases all 5 packages together:
-
-- react-on-rails (NPM)
-- react-on-rails-pro (NPM)
-- react-on-rails-pro-node-renderer (NPM)
-- react_on_rails (RubyGem)
-- react_on_rails_pro (RubyGem)

data/docs/contributors-info/style.md

@@ -1,41 +0,0 @@
-# Code Style
-
-This document describes the coding style of [ShakaCode](http://www.shakacode.com). Yes, it's opinionated, as all style guidelines should be. We shall put as little as possible into this guide and instead rely on:
-
-- Use of linters with our standard linter configuration.
-- References to existing style guidelines that support the linter configuration.
-- Anything additional goes next.
-
-## Client Side JavaScript and React
-
-- See the [Shakacode JavaScript Style Guide](https://github.com/shakacode/style-guide-javascript)
-
-## Style Guides to Follow
-
-Follow these style guidelines per the linter configuration. Basically, lint your code and if you have questions about the suggested fixes, look here:
-
-### Ruby Coding Standards
-
-- [ShakaCode Ruby Coding Standards](https://github.com/shakacode/style-guide-ruby)
-- [Ruby Documentation](http://guides.rubyonrails.org/api_documentation_guidelines.html)
-
-### JavaScript Coding Standards
-
-- [ShakaCode Javascript](https://github.com/shakacode/style-guide-javascript)
-- Use the [eslint-config-shakacode](https://github.com/shakacode/style-guide-javascript/tree/master/packages/eslint-config-shakacode) npm package with eslint.
-- [JSDoc](http://usejsdoc.org/)
-
-### Git coding Standards
-
-- [Git Coding Standards](http://chlg.co/1GV2m9p)
-
-### Sass Coding Standards
-
-- [Sass Guidelines](http://sass-guidelin.es/) by [Hugo Giraudel](http://hugogiraudel.com/)
-- [GitHub Front End Guidelines](http://primercss.io/guidelines/)
-
-# Git Usage
-
-- Follow a github-flow model where you branch off of master for features.
-- Before merging a branch to master, rebase it on top of master, by using command like `git fetch; git checkout my-branch; git rebase -i origin/master`. Clean up your commit message at this point. Be super careful to communicate with anybody else working on this branch and do not do this when others have uncommitted changes. Ideally, your merge of your feature back to master should be one nice commit.
-- Run hosted CI and code coverage.