Skip to main content
Edit

React on Rails 17.0.0 Release Notes

Upgrading from 16.x to 17.0.0​

Update your gem and npm package versions:

# Gemfile
gem "react_on_rails", "17.0.0"
// package.json
{
  "dependencies": {
    "react-on-rails": "17.0.0"
  }
}

Pro users: Use react-on-rails-pro instead of react-on-rails in package.json, and react_on_rails_pro instead of react_on_rails in your Gemfile. See the Pro upgrade guide for details.

Then run bundle install and your package manager's install command.

Important: Read the Upgrading to v17 guide for detailed migration steps.

Highlights​

This is a major release with significant new features for both open-source and Pro users, alongside breaking changes that require attention during upgrade. See the CHANGELOG for the full list of changes.

Breaking Changes​

  1. Ruby 3.3+ is required. The open-source gem now requires Ruby >= 3.3.0, aligning it with React on Rails Pro, create-react-on-rails-app, and the CI minimum matrix. React on Rails v16 remains the upgrade path for applications that must stay on Ruby 3.2 or older. PR 3500.

  2. Four configuration options were removed. Three were deprecated in v16, while config.server_render_method was inert. All four are gone in v17. Setting any of them now raises NoMethodError at boot. Run bin/rake react_on_rails:doctor to detect any that remain in your initializer.

    • config.generated_assets_dirs — delete the line
    • config.skip_display_none — delete the line
    • config.defer_generated_component_packs — replace with config.generated_component_packs_loading_strategy
    • config.server_render_method — delete the line See the upgrade guide for full migration details. PR 4423, PR 4432.

  3. [Pro] Removed the undocumented ReactOnRailsPro::Cache.fetch_react_component class API. Pro apps should use the supported cached helper APIs (cached_react_component, cached_react_component_hash, and related helpers) instead of calling the low-level cache class directly. PR 4541.

  4. [Pro] React Server Components now require the stable React 19.2.x RSC line. Pro RSC apps on v17 require react-on-rails-rsc >= 19.2.1 < 19.3, React >= 19.2.7, and matching React DOM. Non-RSC Pro apps retain React 18 support. PR 4490, PR 4670.

  5. Removed the RenderRequest / JsCodeBuilder / RenderingStrategy rendering layer. These internal classes were built for a strategy-pattern refactor that was never wired in. Remove any application references. PR 4437.

  6. Removed undocumented ReactOnRails::Utils helpers. server_rendering_is_enabled? and rails_version_less_than are gone. Remove any application calls. PR 4431.

  7. [Pro] Node Renderer now requires Ruby 3.3+ for the async-http transport. The react-on-rails-pro gem requires Ruby >= 3.3 (raised from >= 3.0) because async-http depends on Ruby 3.3 features. PR 3320.

  8. [Pro] config.renderer_http_pool_size semantics changed. Existing numeric values now cap concurrent async-http connections for each renderer client instead of sizing a persistent process-wide connection pool. nil keeps the default and does not make the client unlimited. PR 3320.

  9. Breaking (types only): RenderFunction no longer accepts the legacy 3-argument renderer shape. Use RendererFunction for 3-argument renderers. ReactComponentOrRenderFunction still includes RendererFunction. PR 4096.

New Features​

  • hydrate_on scheduling: react_component now accepts hydrate_on: to defer client hydration — :immediate (default), :visible (IntersectionObserver), or :idle (requestIdleCallback). Deferred roots are cleaned up on Turbo navigation and re-scheduled if detached and reattached. See Hydration Scheduling. PR 4037.
  • Font optimization helper: New react_on_rails_font_face view helper — React on Rails' equivalent of Next.js next/font/local. Generates <head> markup with preload, @font-face, and optional metric-matched fallback for zero-CLS font swaps. See Font Optimization. PR 3923.
  • useRailsForm hook + render_model_errors: An Inertia useForm-style bridge to Rails controllers. data/setData, per-field errors, submit verbs, automatic CSRF attachment, and a FormResponders concern for ActiveModel validation rendering. See Forms and Mutations. PR 3942.
  • Generated TypeScript response contracts: rake react_on_rails:generate_response_types emits importable .d.ts declarations plus a RailsResponseTypes lookup map for TanStack Query clients. See Generated Rails Response Types. PR 4259.
  • createRailsAction for TanStack Query mutations: The react-on-rails/railsAction subpath export provides a same-origin JSON caller with Rails CSRF headers and typed responses. PR 4260.
  • React 19 root error callbacks: ReactOnRails.setOptions({ rootErrorHandlers: { onRecoverableError, onCaughtError, onUncaughtError } }) registers React's root error callbacks globally. See Debugging Hydration Mismatches. PR 3933.
  • Owner Stacks in development error reports: React on Rails enriches development error reporting with React 19.1+'s captureOwnerStack — the chain of components that rendered the failing one. Requires React >= 19.1 development build. PR 4089.
  • react_on_rails_preload_links: Emit preload/modulepreload tags for auto-bundled component packs from the Shakapacker manifest. PR 3935.
  • Machine-readable doctor output: FORMAT=json emits a stable, versioned JSON report for coding agents and tooling. PR 3948.
  • Tailwind CSS v4 generator option: --tailwind installs Tailwind CSS v4 with extracted component CSS support. PR 3937.
  • Consumer-facing AI-agent guidance: The install generator writes AGENTS.md, CLAUDE.md, .cursor/rules/react-on-rails.mdc, and .github/copilot-instructions.md so AI coding agents understand the project. Controlled by --agent-files/--no-agent-files (default on). See Generator Details. PR 3924.
  • install_rsc_agent_guardrails rake task: rake react_on_rails:install_rsc_agent_guardrails installs an rsc-app-safety Claude Code skill and advisory hook into the app's .claude/ directory. The skill helps AI agents understand RSC boundaries and the advisory hook warns before risky RSC changes. Re-running after an upgrade is safe. Also runs automatically from the RSC generator.
  • Version-matched agent skills in gem/npm: Four skills — install-and-upgrade, rsc-adoption, streaming-debug, doctor-fix-loop — ship inside the react_on_rails gem and react-on-rails npm package, and generated AGENTS.md files point at them. PR 4809.
  • bin/dev clean: Clears generated bundles and caches — stops development processes, removes Shakapacker output and cache paths, and cleans common Rails/JS/renderer caches. PR 4218.
  • bin/dev deterministic port allocation: Set REACT_ON_RAILS_BASE_PORT (or CONDUCTOR_PORT) and bin/dev derives Rails/webpack/renderer ports automatically: base+0, base+1, base+2. See Process Managers. PR 3142.
  • Stable SmartError codes: Error messages include ROR### codes with canonical documentation URLs. See Error Reference. PR 3936.
  • react-on-rails/webpackHelpers subpath export: Provides reactDomClientWarning to suppress the harmless Module not found: Can't resolve 'react-dom/client' warning on React 16/17. PR 3358.

Pro Features​

  • React 18 support for non-RSC streaming SSR: stream_react_component with synchronous props now works on React 18 as well as React 19. Async props and RSC remain React 19-only. PR 4658.
  • Buffered RSC rendering: buffered_stream_react_component and cached_buffered_stream_react_component render through the Pro streaming/RSC renderer while returning complete HTML to Rails, so static/cacheable pages can avoid ActionController::Live. PR 4268.
  • cached_static_rsc_component: Caches stripped static RSC HTML for public pages that skip the generated page pack. PR 4386.
  • RSC stream observability: Opt-in browser performance marks for stream completion, Flight payload chunks, hydration start, and first interactive effects. Plus Server-Timing header with ror_stream_shell metric. PR 4222, PR 4251.
  • Bidirectional async props (pull mode): stream_react_component_with_async_props can let React request lazy props during incremental rendering, complementing the existing push model. See Streaming SSR. PR 4048.
  • Tag-based cache revalidation: Fragment-caching helpers accept cache_tags: and ReactOnRailsPro.revalidate_tag(tag) deletes entries via a tag→key index. Includes Revalidates ActiveRecord concern. See Fragment Caching. PR 3964.
  • prefetchServerComponent: Client-router loaders can warm a prefetch store that RSCProvider adopts on the next RSCRoute render. PR 4489.
  • async_react_component / cached_async_react_component: Render components asynchronously for deferred page insertion, with optional fragment caching.
  • Node renderer /health and /ready endpoints: First-class liveness and readiness probes, enabled with enableHealthEndpoints config or RENDERER_ENABLE_HEALTH_ENDPOINTS=true. See Health Checks. PR 3939.
  • Source-mapped stack traces: SSR errors now point at original TypeScript/JavaScript positions instead of bundled positions. Uses Node's built-in module.SourceMap. PR 3940.
  • OpenTelemetry integration: Optional integration at react-on-rails-pro-node-renderer/integrations/opentelemetry with distributed tracing, SSR root spans, and render-path sub-spans. PR 3382.
  • HTTP rolling-deploy adapter + auto-mount: ReactOnRailsPro::RollingDeployAdapters::Http serves previously-deployed bundles directly from the Rails server — no S3 required. Auto-mounts at config.rolling_deploy_mount_path. See Rolling Deploy Adapters. PR 3379, PR 3504.
  • <RSCRoute> imperative refetch: ref exposes refetch() via RSCRouteHandle; useCurrentRSCRoute() hook for client components inside the RSC subtree. PR 3552.
  • <RSCRoute ssr={false}>: Defers initial RSC payload generation — the server streams the Suspense fallback and the client fetches the payload. PR 3318.
  • unstable_cache for RSC: Experimental fragment caching with CacheHandler interface, in-memory LRU default, RedisCacheHandler for L2, TieredCacheHandler for L1/L2, and unstable_revalidateTag across workers. PR 3325, PR 3705.
  • RSC manifest client reference discovery: Generated RSC configs run RSCReferenceDiscoveryPlugin during precompile to emit rsc-client-references.json. PR 3556.

Changes​

  • Generator defaults to Rspack for fresh installs (significantly faster builds via SWC). Pass --no-rspack or --webpack for Webpack. PR 3484.
  • create-react-on-rails-app defaults to Pro: Running without flags now generates the recommended Pro scaffold. Add --standard for OSS-only. PR 4217.
  • Redux hidden from install generator: --redux is no longer shown in help text. The runtime Redux APIs remain available. PR 4277.
  • Node Renderer HTTP transport migrated from HTTPX to async-http: ssr_timeout is now a per-read socket timeout; renderer_http_pool_timeout is now the TCP connect timeout. See Pro Upgrade Guide. PR 3320.
  • Node Renderer entry point moved to renderer/node-renderer.js: New canonical location, separate from client/. Existing apps with client/node-renderer.js are unaffected. PR 3165.
  • Docs standardized on REACT_RENDERER_URL env var: The older RENDERER_URL is still supported. bin/dev warns when RENDERER_URL is set without REACT_RENDERER_URL. PR 3142.
  • renderer_http_keep_alive_timeout is deprecated: The async-http adapter manages connection lifecycle automatically. Remove the line from your configure block. PR 3320.

Bug Fixes​

Numerous bug fixes for RSC streaming, payload caching, error boundaries, hydration scheduling, and more. See the CHANGELOG for the complete list.