From e6a0d43145a8b8f834061c06ea6244f0da1f61ab Mon Sep 17 00:00:00 2001 From: Justin Gordon Date: Sun, 31 May 2026 21:26:08 -1000 Subject: [PATCH 1/2] docs: reframe RSC transpiler/bundler support to accurate status Update RSC docs to replace the blanket "experimental/unstable" framing with what is actually true today. babel-to-swc-migration.md: - Babel is the tested/reference transpiler for RSC (the Pro dummy app builds RSC with Babel, so it has the most coverage). - Clarify the 'use client'/'use server' boundary transform is performed by the react-on-rails-rsc WebpackLoader, before babel/swc in the chain, so RSC directive handling is independent of transpiler choice. - SWC-based RSC builds are wired to work but not yet verified end-to-end; the React Compiler SWC plugin remains experimental (and is independent of RSC). rspack-compatibility.md: - Add a current-status note: the RSC bundle compiles and server-renders under Rspack, but the RSC manifest files are not yet emitted; an in-progress fix is tracked in PR #3385 / issue #1828. - Clarify React on Rails uses the react-server-dom-webpack path via Rspack's webpack compatibility layer, not Rspack's native react-server-dom-rspack RSC system. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/oss/migrating/babel-to-swc-migration.md | 15 ++++++------- .../rspack-compatibility.md | 21 ++++++++++++++++--- 2 files changed, 26 insertions(+), 10 deletions(-) diff --git a/docs/oss/migrating/babel-to-swc-migration.md b/docs/oss/migrating/babel-to-swc-migration.md index 4709383890..f6894132a0 100644 --- a/docs/oss/migrating/babel-to-swc-migration.md +++ b/docs/oss/migrating/babel-to-swc-migration.md @@ -95,12 +95,13 @@ bundle exec rspec Based on research and testing, here are the key findings regarding SWC and React Server Components compatibility: -#### ⚠️ Experimental Status +#### ⚠️ SWC and RSC: Babel is the tested path -- **SWC support for React Server Components is EXPERIMENTAL and UNSTABLE** -- The React Compiler's SWC plugin is still experimental as of 2025 -- SWC plugins in general do not follow semver for compatibility -- Next.js recommends version 15.3.1+ for optimal SWC-based build performance with RSC +- **Babel is the tested, reference transpiler for RSC in React on Rails.** The React on Rails Pro dummy app builds RSC with Babel, so it has the most coverage. +- The **`'use client'` / `'use server'` boundary transform is performed by the `react-on-rails-rsc` WebpackLoader**, which runs _before_ babel/swc in the loader chain. RSC directive handling does not depend on your transpiler choice — SWC (or Babel) only does ordinary JS/TS transpilation of the RSC, server, and client bundles. +- Using `swc-loader` to build an RSC app is wired to work (the generated `rscWebpackConfig.js` extracts and chains either `babel-loader` or `swc-loader`) but is not yet verified end-to-end in React on Rails. +- The **React Compiler's SWC plugin is still experimental**, and SWC plugins in general do not follow semver for compatibility. (React Compiler is optional and independent of RSC.) +- Next.js recommends SWC 15.3.1+ for optimal SWC-based build performance with RSC. #### Known Issues @@ -122,7 +123,7 @@ Based on research and testing, here are the key findings regarding SWC and React #### For React Server Components -- ⚠️ **Use with caution** - RSC support in SWC is experimental +- ⚠️ **Use with caution** - SWC-based RSC builds are not yet the verified path in React on Rails - 📝 **Document your configuration** carefully if using RSC with SWC - 🧪 **Extensive testing required** before production deployment - 🔄 **Monitor updates** to SWC and React Compiler for stability improvements @@ -262,7 +263,7 @@ Test coverage includes: The standard React on Rails dummy app (`react_on_rails/spec/dummy`) successfully uses SWC, demonstrating its compatibility with core React on Rails features. -**For projects using React Server Components**: ⚠️ **Stay with Babel for now** - The React on Rails Pro dummy app continues using Babel due to RSC's experimental status with SWC. Consider staying with Babel until SWC RSC support stabilizes, or conduct extensive testing before production deployment. +**For projects using React Server Components**: ⚠️ **Stay with Babel for now** - The React on Rails Pro dummy app builds RSC with Babel, which is the tested transpiler path. SWC-based RSC builds are wired to work but are not yet verified end-to-end, and the React Compiler's SWC plugin remains experimental. Stay with Babel, or conduct extensive testing before production deployment. ## References diff --git a/docs/pro/react-server-components/rspack-compatibility.md b/docs/pro/react-server-components/rspack-compatibility.md index 396f272708..fa55e0a721 100644 --- a/docs/pro/react-server-components/rspack-compatibility.md +++ b/docs/pro/react-server-components/rspack-compatibility.md @@ -53,6 +53,14 @@ compatibility. The [Rspack team has confirmed](https://github.com/shakacode/reac that Rspack supports RSC with the JavaScript API. However, runtime verification with the specific `react-on-rails-rsc` plugin is still needed. +> [!NOTE] +> **Current status (open):** Building a real app under Rspack confirms the RSC bundle +> compiles and server-renders, but the RSC manifest files (`react-client-manifest.json` +> and `react-server-client-manifest.json`) are not yet emitted under Rspack. An +> in-progress fix generates these manifests without the webpack plugin — see +> [PR #3385](https://github.com/shakacode/react_on_rails/pull/3385) and +> [issue #1828](https://github.com/shakacode/react_on_rails/issues/1828). + ## How the RSC Bundle Avoids the Plugin The RSC bundle config (`rscWebpackConfig.js`) calls `serverWebpackConfig(true)`, @@ -79,9 +87,14 @@ To test RSC with Rspack in your project: ## Known Limitations -1. **No `react-server-dom-rspack` package**: React does not ship a dedicated Rspack - variant of the RSC wire protocol. The `react-server-dom-webpack` package is used, - relying on Rspack's webpack compatibility layer. +1. **React on Rails uses the `react-server-dom-webpack` path, not Rspack's native RSC**: + As of Rspack v2, Rspack ships its own [`react-server-dom-rspack` package with built-in + RSC support](https://v2.rspack.rs/guide/tech/rsc) (driven by `builtin:swc-loader` and + `rspackExperiments.reactServerComponents`). React on Rails Pro does **not** use that + native path — its RSC integration is built on the `react-on-rails-rsc` package, which + wraps React's `react-server-dom-webpack` loader and plugin. Running it under Rspack + therefore relies on Rspack's webpack compatibility layer rather than Rspack's native + RSC system. 2. **Plugin `require('webpack')` call**: The `react-server-dom-webpack/plugin` internally calls `require('webpack')`, which loads webpack even in Rspack projects. @@ -95,6 +108,8 @@ To test RSC with Rspack in your project: ## Related Resources - [Issue #1828: Rspack support for RSC](https://github.com/shakacode/react_on_rails/issues/1828) +- [PR #3385: Fix Pro RSC manifests for Rspack builds](https://github.com/shakacode/react_on_rails/pull/3385) - [Rspack RSC support PR](https://github.com/web-infra-dev/rspack/pull/5824) +- [Rspack v2 React Server Components guide](https://v2.rspack.rs/guide/tech/rsc) - [Three-bundle architecture](./how-react-server-components-work.md) - [Upgrading an existing Pro app to RSC](./upgrading-existing-pro-app.md) From b0cdb52e6ba2ac64b51ffabbb6207db87935a7d2 Mon Sep 17 00:00:00 2001 From: Justin Gordon Date: Sun, 31 May 2026 22:00:49 -1000 Subject: [PATCH 2/2] docs: fix RSC manifest filename and Next.js version wording Address PR review feedback on the RSC docs reframe: - babel-to-swc-migration.md: restore "Next.js recommends version 15.3.1+" (was misedited to "SWC 15.3.1+"; 15.3.1 is a Next.js version, not SWC). - babel-to-swc-migration.md: refresh stale "Current Status (2025)" heading to 2026. - rspack-compatibility.md: replace the legacy react-ssr-manifest.json with the canonical react-server-client-manifest.json (lines 47 and 85), making the file internally consistent and matching the rest of the repo and code. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/oss/migrating/babel-to-swc-migration.md | 4 ++-- docs/pro/react-server-components/rspack-compatibility.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/oss/migrating/babel-to-swc-migration.md b/docs/oss/migrating/babel-to-swc-migration.md index f6894132a0..7f746a67ee 100644 --- a/docs/oss/migrating/babel-to-swc-migration.md +++ b/docs/oss/migrating/babel-to-swc-migration.md @@ -91,7 +91,7 @@ bundle exec rspec ## React Server Components (RSC) Compatibility -### Current Status (2025) +### Current Status (2026) Based on research and testing, here are the key findings regarding SWC and React Server Components compatibility: @@ -101,7 +101,7 @@ Based on research and testing, here are the key findings regarding SWC and React - The **`'use client'` / `'use server'` boundary transform is performed by the `react-on-rails-rsc` WebpackLoader**, which runs _before_ babel/swc in the loader chain. RSC directive handling does not depend on your transpiler choice — SWC (or Babel) only does ordinary JS/TS transpilation of the RSC, server, and client bundles. - Using `swc-loader` to build an RSC app is wired to work (the generated `rscWebpackConfig.js` extracts and chains either `babel-loader` or `swc-loader`) but is not yet verified end-to-end in React on Rails. - The **React Compiler's SWC plugin is still experimental**, and SWC plugins in general do not follow semver for compatibility. (React Compiler is optional and independent of RSC.) -- Next.js recommends SWC 15.3.1+ for optimal SWC-based build performance with RSC. +- Next.js recommends version 15.3.1+ for optimal SWC-based build performance with RSC. #### Known Issues diff --git a/docs/pro/react-server-components/rspack-compatibility.md b/docs/pro/react-server-components/rspack-compatibility.md index fa55e0a721..6db5c42160 100644 --- a/docs/pro/react-server-components/rspack-compatibility.md +++ b/docs/pro/react-server-components/rspack-compatibility.md @@ -44,7 +44,7 @@ The `RSCWebpackPlugin` is the critical compatibility question. It wraps React's - `compilation.chunkGraph` — chunk/module graph traversal **Why this matters**: The plugin generates `react-client-manifest.json` and -`react-ssr-manifest.json`, which map client component file paths to their chunk +`react-server-client-manifest.json`, which map client component file paths to their chunk IDs and bundle filenames. Without these manifests, the RSC runtime cannot resolve `'use client'` component references during streaming. @@ -82,7 +82,7 @@ To test RSC with Rspack in your project: 3. Verify configs are in `config/rspack/` 4. Build all three bundles and check for: - `rsc-bundle.js` in the output - - `react-client-manifest.json` and `react-ssr-manifest.json` (from the plugin) + - `react-client-manifest.json` and `react-server-client-manifest.json` (from the plugin) - No webpack/Rspack compilation errors ## Known Limitations