shakacode/react_on_rails v17.0.0.rc.0

on GitHub

Breaking Changes

• [Pro] Node Renderer now requires Ruby 3.3+ for the async-http transport: The react-on-rails-pro gem now requires Ruby >= 3.3 (raised from >= 3.0) because async-http depends on Ruby 3.3 features. Upgrade Ruby before moving to this release. See docs/pro/updating.md for the full upgrade guide. PR 3320 by AbanoubGhadban.
• [Pro] Async Rails server deployments need to stay on the HTTPX renderer until support is added: Falcon and async-rails deployments are not currently supported with the new async-http renderer client because calling the renderer from inside an existing Async reactor without an Async::Task.current? context can create a nested reactor. Keep those deployments on the previous HTTPX renderer client until support is explicitly added. See docs/pro/updating.md for the full upgrade guide. PR 3320 by AbanoubGhadban.
• [Pro] config.renderer_http_pool_size now limits per-request HTTP/2 streams: Existing numeric values now cap concurrent HTTP/2 streams for each request-scoped renderer client instead of sizing a persistent process-wide connection pool. Setting a non-default value emits a warning so the changed meaning is visible during upgrades; setting nil keeps the default stream limit and does not make the request-scoped client unlimited. Persistent connection reuse is tracked in Issue 3283. See docs/pro/updating.md for the full upgrade guide. PR 3320 by AbanoubGhadban.

Added

• [Pro] unstable_cache for React Server Component fragment caching: New experimental unstable_cache(fn, options) wrapper memoizes a server component's serialized RSC payload — replaying the stored bytes on a cache hit and tee-ing output to both the response and the cache store on a miss. Ships with a CacheHandler interface and a default in-memory LRU handler (register custom backends via registerCacheHandler), plus tag-based invalidation through unstable_revalidateTag(tag) that broadcasts across all Node Renderer workers via a new POST /cache/revalidate-tag endpoint and a Ruby-side ReactOnRailsPro::RSCCache.revalidate_tag(tag). Closes Issue 3324. PR 3325 by AbanoubGhadban.
• [Pro] Node Renderer integration API now exposes lifecycle hooks: react-on-rails-pro-node-renderer/integrations/api now exports the tracing reset, provider-state, Fastify lifecycle, and worker shutdown hooks needed by integrations such as OpenTelemetry, keeping integrations inside the supported public boundary. Fixes Issue 3419. PR 3456 by justin808.
• [Pro] Built-in HTTP rolling-deploy adapter (scaffold): New ReactOnRailsPro::RollingDeployAdapters::Http adapter pairs with a mountable ReactOnRailsPro::RollingDeploy::BundlesController so the currently-deployed Rails server can directly serve previously-deployed bundles to the next deploy's build CI — no S3 bucket, IAM, or extra gem required. The controller exposes authenticated GET /manifest and GET /bundles/:hash endpoints using bearer-token auth (constant-time compare, 32-byte minimum), and the adapter pulls bundle tarballs (stdlib-only gzip/tar compose-extract with path-traversal proofing, regular-files-only guards, and a 200 MB zip-bomb cap). Configure via config.rolling_deploy_adapter = ReactOnRailsPro::RollingDeployAdapters::Http, config.rolling_deploy_token, and config.rolling_deploy_previous_url. See docs/pro/rolling-deploy-adapters.md for setup. This is part 1 of a multi-PR series — a hard HTTPS gate, streaming download, and additional hardening land in follow-ups. PR 3379 by justin808.
• [Pro] OpenTelemetry integration for the Node Renderer: New optional integration at react-on-rails-pro-node-renderer/integrations/opentelemetry that adds distributed tracing via standard OpenTelemetry. Users enable it by installing the @opentelemetry/* and @fastify/otel packages (optional peer deps) and calling init({ fastify: true, tracing: true }) from their renderer entrypoint, before reactOnRailsProNodeRenderer(). Provides auto-instrumented HTTP and Fastify spans, an SSR root span (ror.ssr.request), and render-path sub-spans (ror.bundle.build_execution_context, ror.bundle.upload, ror.vm.execute, ror.result.prepare, ror.incremental.stream, ror.incremental.process_chunk). Configuration follows standard OpenTelemetry env-var conventions (OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_SERVICE_NAME, OTEL_RESOURCE_ATTRIBUTES, etc.); defaults to BatchSpanProcessor in production and SimpleSpanProcessor otherwise. The integration is fully optional — users who do not enable it pay zero runtime cost, and the renderer has no direct dependency on OpenTelemetry. Closes Issue 2156. PR 3382 by justin808.
• [Pro] Richer Node Renderer span attributes: ror.bundle.upload now records bytes.total (sum of bundle + asset upload source sizes); ror.vm.execute records bundle.timestamp; ror.result.prepare records response.bytes (UTF-8 byte length of the rendered response, omitted for streamed responses). Only byte counts and identifiers are recorded — request payloads and rendered HTML are never written into span attributes. The subSpan API now passes a SubSpanController to the wrapped function so integrations can attach attributes computed during the work; existing implementations must call fn(controller) (a no-op controller is fine when no span is created). Closes Issue 3390. PR 3422 by justin808.
• react-on-rails/webpackHelpers subpath export with reactDomClientWarning: New webpack helper export so React 16/17 consumers can suppress the harmless Module not found: Can't resolve 'react-dom/client' warning with a one-liner instead of remembering a regex. The require inside reactApis is guarded by a runtime React-version check, so this warning never reflects a real failure, but webpack still emits it at build time because the static require('react-dom/client') cannot be tree-shaken without breaking React 18+. Pass reactDomClientWarning to ignoreWarnings (Webpack 5 / Shakapacker) or stats.warningsFilter (Webpack 4 / Webpacker 5). Fixes Issue 3137. PR 3358 by justin808.
• bin/dev deterministic port allocation via REACT_ON_RAILS_BASE_PORT (and CONDUCTOR_PORT): bin/dev now derives Rails / webpack-dev-server / node-renderer ports from a single base port when REACT_ON_RAILS_BASE_PORT (or CONDUCTOR_PORT, for Conductor.build workspaces) is set: Rails = base + 0, webpack = base + 1, renderer = base + 2. This makes parallel worktrees and coding-agent sandboxes collision-free without per-service env vars. The priority chain is base port → explicit per-service env vars (PORT, SHAKAPACKER_DEV_SERVER_PORT) → auto-detection. Behavior note: when base-port mode is active, any pre-set PORT, SHAKAPACKER_DEV_SERVER_PORT, RENDERER_PORT, or non-matching REACT_RENDERER_URL (and the legacy RENDERER_URL, when already set) is unconditionally overwritten with the derived value (a warning is printed before each override). This applies in all bin/dev modes including bin/dev prod, where SHAKAPACKER_DEV_SERVER_PORT is also derived/overwritten for tooling consistency even though the production-like mode does not run webpack-dev-server. Sub-process env preservation: to keep these derived values consistent across spawned processes, bin/dev now also preserves RENDERER_PORT, REACT_RENDERER_URL, and SHAKAPACKER_SKIP_PRECOMPILE_HOOK across Bundler's env reset (previously only PORT and SHAKAPACKER_DEV_SERVER_PORT were preserved); this prevents nested shakapacker commands from silently re-running the precompile hook or losing the renderer URL. PR 3142 by justin808.
• [Pro] bin/dev auto-derives REACT_RENDERER_URL from RENDERER_PORT: When only RENDERER_PORT is set, bin/dev now sets REACT_RENDERER_URL=http://localhost:RENDERER_PORT so Rails reaches the right port by default. Users running a remote or non-localhost node renderer (Docker service, remote host) should set REACT_RENDERER_URL explicitly so it is not replaced with the localhost default. PR 3142 by justin808.
• [Pro] Pre-seed renderer cache for Docker builds: New react_on_rails_pro:pre_seed_renderer_cache rake task copies compiled server bundles into the Node Renderer's bundle-hash cache directory structure during Docker image builds, eliminating the 410→retry cold-start latency (200ms–1s+) on the first SSR request after deployment. Supports RENDERER_SERVER_BUNDLE_CACHE_PATH, RSC bundles, and rolling-deploy guidance centered on current and previous bundle hashes. The legacy pre_stage_bundle_for_node_renderer task now stages the same cache layout via symlinks for same-filesystem workflows. Note: RENDERER_BUNDLE_PATH is now deprecated in favor of RENDERER_SERVER_BUNDLE_CACHE_PATH across both tasks. Existing users with RENDERER_BUNDLE_PATH set will see a deprecation warning on stderr. PR 3124 by justin808.
• [Pro] Rolling-deploy adapter protocol: New config.rolling_deploy_adapter pluggable module (protocol: previous_bundle_hashes, fetch, upload) that seeds previously-deployed bundle hashes into the Node Renderer cache, preventing 410→retry for draining-version requests during rolling deploys. assets:precompile auto-calls upload in production-like environments so the next deploy can fetch the just-built bundle. PREVIOUS_BUNDLE_HASHES env var overrides discovery for CI. react_on_rails:doctor probes the adapter and reports protocol conformance, discovery latency, and resolved cache dir. Each seeded hash carries its own loadable-stats.json / RSC manifests so client-side hydration stays consistent with the deployed asset pipeline for that hash. See docs/pro/rolling-deploy-adapters.md for the full protocol spec and reference implementations (S3, Control Plane, Filesystem). PR 3173 by justin808.
• [Pro] Async props with incremental React Server Component rendering: Added the stream_react_component_with_async_props and rsc_payload_react_component_with_async_props view helpers, which accept a block to declare props that are fetched concurrently and streamed to the rendering component as each value becomes available. The React component renders its shell immediately (with <Suspense> fallbacks) and progressively re-renders as async prop promises resolve, dramatically improving Time to First Byte for pages with slow data fetches. Components access async props through the getReactOnRailsAsyncProp function injected into props (typed via the new WithAsyncProps TypeScript helper). Requires config.enable_rsc_support = true. This is an additive feature — existing stream_react_component and rsc_payload_react_component calls are unaffected. PR 2903 by AbanoubGhadban.

Changed

• [Pro] RollingDeployCacheStager now rejects bundle hashes that start with a hyphen: The shared ReactOnRailsPro::RollingDeploy::SAFE_HASH_PATTERN constant (also used by the new HTTP rolling-deploy adapter) tightens the cache stager's old local pattern by additionally rejecting leading hyphens. Webpack content hashes never start with - in practice, so this is a no-op for default toolchains, but operators running a custom rolling-deploy adapter that emits hyphen-prefixed hashes will now see those hashes silently dropped from the staged set. If you depend on hyphen-prefixed hashes, rename them to start with an alphanumeric character or _. PR 3379 by justin808.

• Upgrade contributor pnpm tooling to 10.33.4: The monorepo now pins pnpm 10.33.4 with Corepack's hash-qualified packageManager format, keeps the install-generator CI fallback on the same pnpm version, and relies on the root workspace pin instead of duplicate workspace packageManager declarations. PR 3400 by alexeyr-ci2.

• Allow trusted pnpm 10 build scripts in contributor installs: The root workspace now allowlists required native dependency postinstall checks for @swc/core and unrs-resolver, so pnpm install under pnpm 10 no longer skips those trusted build hooks. PR 3421 by justin808.

• Release publishing now checks origin/main CI status before shipping: rake release now inspects GitHub Checks for origin/main before publishing, blocking stable releases on any visible failing or missing checks and prereleases on required checks, with an explicit override path for maintainers. PR 3407 by justin808.

• [Pro] Updated Pino in the Node Renderer: Raised the react-on-rails-pro-node-renderer pino dependency range to ^9.14.0 || ^10.1.0, aligning with the current Fastify dependency. PR 3401 by alexeyr-ci2.

• [Pro] Per-scheduler persistent HTTP connections for Node Renderer: RendererHttpClient now reuses HTTP/2 connections across requests within the same Fiber scheduler (Falcon, async Puma), eliminating per-request TCP+TLS+HTTP/2 handshake overhead. Standalone requests (no outer scheduler) continue using ephemeral connections with guaranteed cleanup. The internal connection pool automatically recovers from broken connections without manual eviction. PR 3428 by AbanoubGhadban.

• [Pro] Migrated Node Renderer HTTP transport from HTTPX to async-http: React on Rails Pro now uses async-http (~> 0.95) with io-endpoint (~> 0.17) for all Rails→Node Renderer requests (render, streaming render, asset upload), replacing the previous HTTPX adapter and the custom httpx_stream_bidi_patch.rb. The new RendererHttpClient is a request-scoped client (one client per Rails request — no persistent process-wide pool) and integrates with the length-prefixed wire protocol introduced in PR 2903. HTTP/2 bidirectional streaming for async props is now provided by post_bidi on the new adapter. Action required for upgraders:

  • config.ssr_timeout is now a per-read socket timeout applied to each renderer socket read, rather than a task-level timeout wrapping the entire request.
  • config.renderer_http_pool_timeout is now the TCP connect timeout; post-connect reads are bounded by ssr_timeout.
  • No implicit transport retry for connection drops: drops surface immediately as ReactOnRailsPro::Error/connection failures. HTTPX previously performed one implicit transport retry; the new adapter uses retries: 0 and leaves retry policy to the existing bundle-upload retry loop.

  See docs/pro/updating.md for the full upgrade guide. PR 3320 by AbanoubGhadban.

• [Pro] PreSeedRendererCache and PrepareNodeRenderBundles now auto-stage loadable-stats.json: ReactOnRailsPro::RendererCacheHelpers.collect_assets now appends loadable-stats.json whenever the file exists on disk, so every caller (rolling-deploy seeding, pre_seed_renderer_cache, pre_stage_bundle_for_node_renderer) stages it automatically. Action required for upgraders: if your assets_to_copy config explicitly listed loadable-stats.json, remove that entry — otherwise you'll see a "Duplicate asset basenames in assets_to_copy" warning on every stage. The duplicate is harmless (stage_assets keeps the last entry per basename), but the warning is noise. PR 3173 by justin808.

• [Pro] Unified renderer cache staging: ReactOnRailsPro::PreSeedRendererCache.call(mode: :copy | :symlink) is now the single entry point for staging the Node Renderer cache. Both modes produce the same <cache>/<bundleHash>/<bundleHash>.js layout. The react_on_rails_pro:pre_seed_renderer_cache rake task accepts MODE=copy (default; Docker/image builds) or MODE=symlink (same-filesystem). The auto-invocation at the end of assets:precompile defaults to :symlink (preserving prior behavior) and now honors ASSETS_PRECOMPILE_RENDERER_CACHE_MODE=copy|symlink so Docker builds that run rake assets:precompile as the final asset step can opt into copy mode without invoking the rake task separately. MODE=copy raises a clear error when neither RENDERER_SERVER_BUNDLE_CACHE_PATH nor RENDERER_BUNDLE_PATH is set in non-dev/test environments, because the Node renderer's default lookup can differ from the Ruby side and would silently drop pre-seeded bundles in the wrong directory. The legacy react_on_rails_pro:pre_stage_bundle_for_node_renderer task and ReactOnRailsPro::PrepareNodeRenderBundles class remain as deprecated shims that emit a once-per-process warning and delegate to mode: :symlink. react_on_rails:doctor flags deploy scripts that still reference the deprecated task. Heads-up for custom scripts: the previous flat layout wrote $RENDERER_BUNDLE_PATH/<renderer_bundle_file_name>; any external scripts (health checks, renderer launchers) that read that path directly must now read $RENDERER_SERVER_BUNDLE_CACHE_PATH/<bundleHash>/<bundleHash>.js instead. PR 3124 by justin808.

• [Pro] Pro generator now creates the Node Renderer at renderer/node-renderer.js: The canonical location for the Node Renderer entry point is now a dedicated top-level renderer/ directory instead of client/, making it straightforward to exclude from production Docker builds that strip JS sources after bundling. Docs and Pro spec/dummy now use the new path consistently. Existing apps are unaffected — the generator skips files that already exist (including a legacy client/node-renderer.js). Fixes Issue 3073. PR 3165 by justin808.

• [Pro] Documentation standardized on REACT_RENDERER_URL env var name: The configuration example in docs/oss/configuration/configuration-pro.md now shows ENV["REACT_RENDERER_URL"] instead of the older ENV["RENDERER_URL"], aligning with the rest of the docs and the generator template. Existing apps that read ENV["RENDERER_URL"] in their initializer continue to work — the Pro renderer_url config is whichever env var the user reads in their initializer; no gem code reads either name directly. Rename the env var in your infrastructure configs (and update the initializer to match) if you want to align with the new convention. bin/dev now also warns when RENDERER_URL is set without REACT_RENDERER_URL so the rename doesn't silently fall back to the default renderer URL. PR 3142 by justin808.

• Length-prefixed streaming wire protocol: The internal protocol between the Rails gems and the Node renderer (and the in-process bundle for the OSS non-streaming path) now uses a length-prefixed framing — <metadata JSON>\t<content byte length hex>\n<raw content bytes> — instead of wrapping every HTML chunk in a JSON envelope, eliminating ~30% serialize/escape overhead on streamed HTML and correctly handling multibyte content and chunk boundaries. This is an internal transport detail: React on Rails always ships the react_on_rails/react_on_rails_pro gems, the react-on-rails/react-on-rails-pro npm packages, and the react-on-rails-pro-node-renderer as a matched version set, and the Ruby parser also auto-detects the legacy JSON format, so no application action is required when upgrading all artifacts together. PR 2903 by AbanoubGhadban.

• react_on_rails:doctor renderer-cache scan covers CI/CD manifests: The deprecated-task scan that flags react_on_rails_pro:pre_stage_bundle_for_node_renderer now also checks .circleci/config.yml, .gitlab-ci.yml, bitbucket-pipelines.yml, every .github/workflows/*.yml/.yaml, and every config/deploy/*.rb stage file, on top of the existing Procfile/Dockerfile/Compose/Kamal/Capistrano/bin/*/scripts/deploy.sh paths. The scan stays bounded: per-file size cap, no ** globs, a per-glob match cap, per-file rescue, and a separate per-glob rescue so a single unreadable workflow or stage file cannot abort the rest of the scan. Fixes Issue 3247. PR 3329 by justin808.

• Rspack install scaffolding now targets Rspack v2: react_on_rails:install --rspack and bin/switch-bundler now generate the Rspack v2 package line (@rspack/core@^2.0.0-0, @rspack/cli@^2.0.0-0, @rspack/plugin-react-refresh@^2.0.0) while keeping rspack-manifest-plugin@^5.0.0, which is already compatible. Closes Issue 3082. PR 3084 by justin808.

Improved

• Resolved Shakapacker config path warnings now show the expanded path: Missing SHAKAPACKER_CONFIG warnings now include the Rails-root-resolved path that was checked, making relative-path typos easier to diagnose. PR 3444 by justin808.

Fixed

• [Pro] RSC client-hook runtime errors now explain the missing client boundary: React on Rails Pro now rewrites RSC runtime hook failures such as useState is not a function with a diagnostic that names the registered component, points to the likely missing "use client"; directive, and clarifies that .client/.server suffixes only control bundle placement. Fixes Issue 3184. PR 3461 by justin808.
• Test asset compiler output is now bundler-neutral: Test asset compilation now prints "Building assets..." and "Completed building assets." instead of Webpack-specific wording, and failure guidance tells users to rerun their configured build_test_command instead of naming Shakapacker. Fixes Issue 3455. PR 3462 by justin808.
• [Pro] RSC stream failures now surface original diagnostics: RSC payload stream metadata now preserves the original RSC bundle exception message, stack, component name, and module path where available across server-bundle rendering, Rails PrerenderError, and browser fetch paths. Fixes Issue 3182. PR 3463 by justin808.
• [Pro] react_on_rails:doctor renderer-cache scan now covers Jenkinsfile: The deprecated-task scan that flags react_on_rails_pro:pre_stage_bundle_for_node_renderer now also checks Jenkinsfile, alongside the existing CI/CD manifests and deploy scripts. Fixes Issue 3269. PR 3442 by justin808.
• Client-only Vite setups no longer fail Rails boot on Shakapacker's packageManager guard: React on Rails now installs an engine initializer that runs before shakapacker.manager_checker and no-ops Shakapacker's error_unless_package_manager_is_obvious! when the host app has no Shakapacker config (config/shakapacker.yml or SHAKAPACKER_CONFIG). This unblocks apps that use the react-on-rails/client npm package from an existing Vite entrypoint and do not use the Ruby render helpers. The Ruby helpers that resolve bundle paths still require Shakapacker configuration. Apps with Shakapacker config keep Shakapacker's guard unchanged. Fixes Issue 3145. PR 3365 by justin808.
• [Pro] HTTP rolling-deploy bundle responses now include stronger no-cache headers: The built-in rolling-deploy manifest and bundle endpoints now send Pragma: no-cache and X-Content-Type-Options: nosniff alongside Cache-Control: no-store, reducing the risk of legacy caching or MIME-sniffing mishandling authenticated bundle payloads. PR 3439 by justin808.
• [Pro] OpenTelemetry shutdown timeout warning never logged: shutdownProviderWithTimeout in the Node Renderer's OpenTelemetry integration was missing a log.warn( call, leaving a bare string literal that produced no diagnostic when provider.shutdown() exceeded its timeout (and broke the source file's compilation). The timeout message now logs correctly. Follow-up to PR 3382. PR 3420 by justin808.
• [Pro] Streaming server-render responses now raise ReactOnRailsPro::Error when the stream response status is unavailable or the renderer delivers a readable HTTP error status as a streaming body, instead of silently returning no chunks. This is a user-visible behavior change for callers that do not already rescue ReactOnRailsPro::Error from each_chunk. PR 3383.
• [Pro] TanStack Router hydration now supports the current router stores API: react-on-rails-pro/tanstack-router client hydration now uses TanStack Router's current router.stores.setMatches() API when router.__store.setState() is unavailable, so SSR hydration works with newer @tanstack/react-router releases without app-level compatibility shims. Fixes Issue 3375. PR 3376 by justin808.
• [Pro] TanStack Router hydration no longer double-calls loadRouteChunk under React 18 StrictMode: React 18's StrictMode double-renders components with fresh hook state on each pass, so the routerRef.current === null guard in clientHydrate.ts fired twice when options.createRouter returned the same router instance, re-running loadRouteChunk, __store.setState, and the user-defined hydrate callback. The render-phase init is now memoized via a module-level WeakMap keyed on the router instance, dedup'ing per-router side effects across mount cycles. Production behavior is unchanged because each mount creates a fresh router. Fixes Issue 3405. PR 3410 by justin808.
• [Pro] Benchmark CI starts the production dummy app on the expected port: react_on_rails_pro/spec/dummy/bin/prod now sets PORT=3001 by default before launching Foreman, preventing Foreman's default PORT=5000 from making the Rails server miss the benchmark workflow readiness check on localhost:3001. Both react_on_rails/spec/dummy/bin/prod and react_on_rails_pro/spec/dummy/bin/prod respect PORT when it's set. PR 3403 by alexeyr-ci2.
• CI fails on stale lockfiles outside minimum-dependency jobs: GitHub Actions now runs Bundler with frozen lockfiles for standard integration, Pro, Playwright, lint, and precompile jobs, and no longer mutates lockfiles with bundle lock --add-platform. pnpm install is also frozen in Playwright. The intentionally mutable minimum-dependency jobs still use non-frozen installs after script/convert. PR 3404, PR 3430 by alexeyr-ci2.
• [Pro] Generated bin/dev Procfiles now start the Node Renderer: Pro setup now appends a node-renderer process to Procfile.dev, Procfile.dev-static-assets, and Procfile.dev-prod-assets when those files exist, so SSR pages work in bin/dev, bin/dev static, and bin/dev prod. react_on_rails:doctor now warns when a Pro NodeRenderer app's launcher Procfiles can serve Rails pages but do not start a renderer on RENDERER_PORT. Fixes Issue 3372. PR 3381 by justin808.
• Prerelease changelog auto-versioning now warns for cross-channel reuse: bundle exec rake update_changelog[rc] and [beta] now correctly warn when an active prerelease base exists only in a different prerelease channel, helping maintainers catch accidental channel switches before stamping a release header. PR 3417 by justin808.
• Release pipeline verifies published npm packages and blocks workspace: dependency leaks: rake release:npm now polls npm view after each pnpm publish and aborts when the published version is missing, mismatched, or when any install-time dependencies/optionalDependencies/peerDependencies still contains a workspace: protocol entry. Before publishing, package manifests are temporarily rewritten to replace workspace: ranges with publishable semver and restored afterward. The broken 16.7.0-rc.1 npm publish shipped react-on-rails-pro@16.7.0-rc.1 with react-on-rails: "workspace:*" in its dependency metadata, which Yarn v1 cannot install from the registry; this safeguard prevents future releases from leaking the same protocol. PR 3387 by justin808.
• Install generator preserves explicit version pins when package-manager install fails: The install generator's add_packages path now writes versioned name@version specs directly into package.json (under dependencies or devDependencies) as a last-resort fallback when neither the primary nor fallback package manager install succeeds, so users can rerun their package manager manually without losing the pins. Specs without an explicit version are not written. PR 3387 by justin808.
• [Pro] RSC client manifest restored when only registerServerComponent/client is in the pack graph: wrapServerComponentRenderer/client now directly imports react-on-rails-rsc/client.browser as a side-effect import. Previously the client runtime was only reachable through a three-level transitive chain (wrapServerComponentRenderer/client → getReactServerComponent.client → react-on-rails-rsc/client.browser). Tooling that severed any link in that chain (tree-shaking, transpiler quirks, custom NormalModuleReplacement, externals) caused RSCWebpackPlugin to emit Client runtime at react-on-rails-rsc/client was not found. React Server Components module map file react-client-manifest.json was not created. and silently skip the manifest, breaking RSC hydration on the Pro Node Renderer. The direct import keeps the runtime resource in the module graph so the plugin always emits react-client-manifest.json. Fixes #3366. PR 3368 by justin808.
• [Pro] Updated Fastify in the Node Renderer for CVE-2026-33806: Raised the direct fastify dependency to 5.8.5 so user-provided Fastify server options, including trustProxy, pick up the upstream security fix. PR 3152 by dependabot[bot].
• [Pro] TanStack Router hydration no longer bails to a full client re-render: TanStack Router SSR pages no longer discard server-rendered HTML during hydration because the client tree now renders RouterProvider with the same shape as the server output. Post-hydration navigation still waits for matched lazy route chunks before router.load(). PR 3213 by Seifeldin7.
• [Pro] Widened ruby-jwt support to jwt >= 2.7: React on Rails Pro relaxes the previous ~> 2.7 cap to jwt >= 2.7, so applications can resolve the patched ruby-jwt 3.2.0+ release for the empty-key HMAC advisory while apps still on jwt 2.x remain compatible. PR 3322, PR 3344 by ihabadham.
• [Pro] Pro migration generator rewrites all base-package references and preserves Gemfile pins: rails generate react_on_rails:pro now rewrites Jest/Vitest mock helpers (jest.mock, vi.mock, requireActual/importActual, and the rest) and TypeScript declare module 'react-on-rails' blocks alongside its existing import/require/dynamic-import handling, and the Gemfile swap now preserves the user's existing version pin (and other gem options) instead of overwriting them with the running gem's version. react_on_rails:doctor is widened to match: it also flags stale side-effect imports (import 'react-on-rails';), Jest/Vitest mock helpers, and declare module blocks, and the new side-effect-import pattern keeps the doctor a superset of the rewriter so anything the rewriter doesn't reach gets surfaced. Closes Issue 3104. PR 3232 by justin808.
• [Pro] Pro migration scans TypeScript 4.7 .mts and .cts modules: react_on_rails:doctor and the Pro migration rewriter now include .mts/.cts source files (and their .d.mts/.d.cts declaration counterparts) when looking for stale react-on-rails references, matching the existing .mjs/.cjs coverage. Fixes Issue 3250. PR 3334 by justin808.
• Doctor now honors nested JavaScript package roots: react_on_rails:doctor now checks package-manager lockfiles, package.json, and installed React from the configured node_modules_location, reducing false diagnostics for legacy apps that keep dependencies under client/. The Vite migration guide now documents the supported thin-wrapper pattern for those layouts. Note: a missing package.json at the configured node_modules_location now emits a warning instead of being silently skipped, so apps misconfigured against a nonexistent path will see new diagnostics on upgrade. Fixes Issue 3205. PR 3220 by justin808.
• Generated pack regeneration is now serialized: generate_packs_if_stale now uses a Rails tmp/ lock file, re-checks staleness after waiting, and avoids concurrent cleanup/regeneration races when multiple processes trigger auto-bundling at the same time. Fixes Issue 1627. PR 3231 by justin808.
• Install generator validates the selected JavaScript package manager: The install generator now checks the manager selected from REACT_ON_RAILS_PACKAGE_MANAGER, the packageManager field in package.json, or a lockfile on disk — instead of passing when any JavaScript package manager is installed. When the selected command is missing, the error names the selected manager, the source that selected it, and the available alternatives. The generator also warns when REACT_ON_RAILS_PACKAGE_MANAGER is set to a value outside the supported set (npm, pnpm, yarn, bun). Addresses package manager validation from Issue 1958. PR 3229 by justin808.
• Server-render error wrapping preserves original causes: When server rendering catches a non-Error thrown value, React on Rails now wraps it with the original value attached as cause, making downstream debugging preserve more context. Fixes Issue 1746. PR 3230 by justin808.
• bin/dev now cleans copied runtime files before startup: When you duplicate an app directory to run another local dev stack, bin/dev now removes copied stale Overmind sockets and stale tmp/pids/server.pid files that point to a Puma process running from another app directory. This prevents false startup failures in copied workspaces while still preserving active local sockets and pid files for the current app. PR 3142 by justin808.
• bin/dev kill is more thorough and Pro-aware under base-port mode: ServerManager.kill_processes no longer short-circuits after the first successful step — pattern-based kills, port-based kills, and socket/pid cleanup all run unconditionally so a stale renderer port-binding or socket file cannot survive a bin/dev kill. In base-port mode, the derived renderer port (base+2) is now always included in port-based killing when react_on_rails_pro is loaded, even if RENDERER_PORT / REACT_RENDERER_URL are unset in the current shell (an informational message is printed so the wider scan is not silent). ProcessManager also now preserves the legacy RENDERER_URL env var alongside REACT_RENDERER_URL across Bundler's env reset so mid-migration users keep a consistent renderer URL in spawned subprocesses. PR 3274 by justin808.
• CI change detection handles shallow clones with long-lived branches: script/ci-changes-detector and script/check-docs-sidebar now resolve an actual merge base before diffing, deepening shallow origin/main and current-branch history as needed. ci-changes-detector now fails visibly when it cannot compute a safe diff instead of treating git failures as no changes. Fixes Issue 3108. PR 3224 by justin808.
• [Pro] RSC setup now scopes client-reference discovery to app source: Generated RSC webpack configs now pass clientReferences based on Shakapacker's source_path, avoiding CI failures where the plugin could scan vendored gem templates under vendor/bundle. Fixes Issue 3201. PR 3219 by justin808.
• [Pro] Node renderer now exposes performance when supportModules: true: React 19's development build of React.lazy calls performance.now(), which previously threw ReferenceError: performance is not defined inside the node renderer's VM context unless users manually added performance via additionalContext. performance is now included in the default globals alongside Buffer, process, etc. Fixes Issue 3154. PR 3158 by justin808.
• Scaffolded CI workflow pins a pnpm version when packageManager is absent: The generated .github/workflows/ci.yml now emits with: version: for pnpm/action-setup@v4 when pnpm is detected from pnpm-lock.yaml alone, preventing the setup step from failing before dependency install. When packageManager is declared in package.json, the version key is omitted so the action reads the pin from there. Note: GeneratorMessages.detect_package_manager(package_json: nil) now treats nil as "caller cached that the file is absent" and skips disk fallback, instead of re-reading package.json; the previous fallthrough behavior is now the default (omit the keyword) and is documented on read_package_json. Fixes Issue 3172. PR 3174 by justin808.
• Client startup now recovers if initialization begins during interactive after DOMContentLoaded already fired: React on Rails now still initializes the page when the client bundle starts in the browser timing window after DOMContentLoaded but before the document reaches complete. Fixes Issue 3150. PR 3151 by ihabadham.
• Doctor accepts TypeScript server bundle entrypoints: react_on_rails:doctor now resolves common source entrypoint suffixes (.js, .jsx, .ts, .tsx, .mjs, .cjs) before warning that the server bundle is missing, preventing false positives when apps use server-bundle.ts. PR 3111 by justin808.
• Doctor no longer fails custom projects for a missing generated bin/dev: react_on_rails:doctor now downgrades a missing official React on Rails bin/dev launcher from an error to a warning and adds explicit guidance when a custom ./dev script is detected, so custom projects can pass diagnostics when their development setup is intentional. Fixes Issue 3103. PR 3117 by justin808.
• [Pro] Reduced react-on-rails-pro-node-renderer published package size: added a files whitelist to package.json so pnpm pack no longer includes src/, tests/ fixtures, *.map, and lib/tsconfig.tsbuildinfo — matching the convention used by the sibling packages. Also marked react_on_rails_pro/spec/dummy as private so it can never be accidentally published. PR 3304 by alexeyr-ci2.
• [Pro] HTTPX bidirectional streaming reliability: Fixed streaming request timeouts when using HTTPX with both the :stream and :stream_bidi plugins. The request now uses the build_request pattern with an explicit request.close so the HTTP/2 END_STREAM flag is sent, and a temporary monkey-patch (httpx_stream_bidi_patch.rb) works around an upstream :stream_bidi retry bug that left stale body callbacks registered and crashed retried requests with protocol_error. The patch is scoped and will be removed once fixed upstream. PR 2903 by AbanoubGhadban.
• [Pro] Progressive RSC streaming flush granularity: RSC streaming now flushes on React's per-render-cycle flush() signal instead of setTimeout(flush, 0), so the shell and each resolved <Suspense> boundary stream as separate chunks rather than being merged into one large first message. This restores progressive streaming (and fixes worse-than-SSR First Contentful Paint) on pages with fast queries, and eliminates partial-HTML-tag chunks. Fixes Issue 3194. PR 2903 by AbanoubGhadban.
• [Pro] Node renderer graceful shutdown after stream timeouts: Fixed workers taking 30+ seconds to shut down after a StreamChunkTimeoutError during streaming. handleGracefulShutdown now also decrements the active-request count on onRequestAbort/onTimeout, the PassThrough wrapper is destroyed when the source render stream errors, and the HTTP response is closed on chunk timeout so connections to Rails no longer hang. Fixes Issue 2270 and Issue 2308. PR 2903 by AbanoubGhadban.

Deprecated

• [Pro] config.renderer_http_keep_alive_timeout is deprecated: The setting now has no effect because async-http renderer clients are scoped to individual requests. Setting it emits a deprecation warning; remove the configuration during upgrade. See docs/pro/updating.md for the full upgrade guide. PR 3320 by AbanoubGhadban.

Removed

• [Pro] Removed HTTPX transport gem dependencies from the Node Renderer: React on Rails Pro no longer depends on httpx, http-2, or connection_pool after migrating to async-http. Applications that directly pin or require those gems for renderer integration should remove that coupling or add their own explicit dependency. PR 3320 by AbanoubGhadban.
• [Pro] Removed the --rsc-pro install generator flag: --rsc already implies Pro, so the separate mode was unnecessary. Behaviors previously gated on --rsc-pro (Pro verification checklist, prerelease install note, exact Pro gem pin on prereleases) now fire on --rsc installs. See also Issue 3104, which tracks unrelated silent-failure bugs in the Pro upgrade automation. PR 3105 by ihabadham.

Security

• [Pro] Hardened Node Renderer password lifecycle: The protocol-mismatch (412) response no longer echoes the request body verbatim — only non-sensitive field names are returned, so a mismatched password is never reflected back. The Pro install generator now provisions a random 64-hex-character renderer password instead of the publicly-known devPassword default, and production startup now logs a non-blocking warning for known-weak or short (< 16 character) renderer passwords. Fixes Issue 3397. PR 3399 by AbanoubGhadban.