diff --git a/docs/oss/migrating/babel-to-swc-migration.md b/docs/oss/migrating/babel-to-swc-migration.md index 4709383890..7f746a67ee 100644 --- a/docs/oss/migrating/babel-to-swc-migration.md +++ b/docs/oss/migrating/babel-to-swc-migration.md @@ -91,16 +91,17 @@ 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: -#### ⚠️ 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 version 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..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. @@ -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)`, @@ -74,14 +82,19 @@ 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 -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)