feat: support React Router 8 compatibility

.changeset/react-router-8-default-template.md

@@ -0,0 +1,10 @@
+---
+'rsbuild-plugin-react-router': minor
+---
+
+Add React Router 8 compatibility while preserving React Router 7 behavior.
+The plugin now supports stable React Router 8 config fields, resolves
+prerender data requests for the installed React Router major version, supports
+React Router RSC mode, analyzes transformed MDX route modules for manifest
+generation, and includes React Router 8/RSC examples plus framework integration
+coverage.

.changeset/stream-server-first-route-css.md

@@ -0,0 +1,11 @@
+---
+'rsbuild-plugin-react-router': patch
+---
+
+Stream server-first route CSS during RSC render. CSS imported in the RSC
+layer never flows through the client manifest's `<Links>`, so it was
+previously dropped. Modules exporting server components are now marked with
+the `'use server-entry'` directive so rspack's RSC runtime records
+`entryCssFiles`, which the server route entry wrapper streams as
+precedence-tagged stylesheet links, fixing missing styles and
+flash-of-unstyled-content for server-component routes.

.codex/skills/react-router-upstream-tests/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: react-router-upstream-tests
+description: Audit upstream React Router framework test changes and manually select tests to adapt into this repository without overwriting the checked-in Rsbuild corpus.
+---
+
+# React Router Upstream Tests
+
+Use this skill when checking for new or changed upstream React Router framework
+tests, reviewing the corpus checkpoint, or manually importing test coverage.
+
+## Source of truth
+
+- `tests/react-router-framework/UPSTREAM.json` records the upstream repository,
+  last reviewed commit, review time, and relevant source directories.
+- `tests/react-router-framework/` is repository-owned and authoritative. It is
+  intentionally adapted for Rsbuild and must never be overwritten wholesale.
+- `scripts/check-react-router-framework-upstream.mjs` is a read-only audit. It
+  reports upstream changes but never copies files or updates the checkpoint.
+
+## Workflow
+
+1. Inspect the current checkpoint and confirm the local React Router clone:
+
+   ```sh
+   cat tests/react-router-framework/UPSTREAM.json
+   git -C /path/to/react-router status --short --branch
+   ```
+
+2. Compare the reviewed commit with the desired upstream target:
+
+   ```sh
+   pnpm check:react-router-framework-upstream -- \
+     --source=/path/to/react-router \
+     --target=HEAD
+   ```
+
+3. Review every reported directory containing added files and every added,
+   modified, deleted, or renamed file. Select only tests that add relevant
+   compatibility coverage.
+
+4. Copy selected tests manually and adapt them to the existing Rsbuild harness:
+
+   - use `rsbuild.config.ts`, not Vite configuration;
+   - reuse helpers under `tests/react-router-framework/integration/helpers`;
+   - preserve intentional Rsbuild/Rspack divergences;
+   - do not add inert Vite dependencies, fixtures, or skipped suites;
+   - keep resource-guard and process-cleanup behavior intact.
+
+5. Run the narrow imported tests first, then the relevant framework gate:
+
+   ```sh
+   pnpm build
+   RR_FRAMEWORK_MAX_WORKERS=2 pnpm exec playwright test \
+     --config tests/react-router-framework/integration/playwright.config.ts \
+     path/to/imported-test.ts --workers=2 --max-failures=1 --retries=0
+   pnpm test:react-router-framework:failfast
+   ```
+
+6. After review and validation, update `lastReviewedRef` and `reviewedAt` in
+   `UPSTREAM.json` in the same commit as the selected test adaptations.
+
+## Guardrails
+
+- Never add an automatic sync, overlay restoration, or corpus rewrite step.
+- Never update the checkpoint merely because the audit command ran.
+- Never claim the corpus matches upstream; record only the revision reviewed.
+- Do not copy upstream package manifests without adapting workspace/catalog
+  dependencies to this repository deliberately.
+- Keep the working tree reviewable and commit only selected tests, adaptations,
+  checkpoint metadata, and directly related documentation.

.github/workflows/e2e-tests.yml

@@ -6,6 +6,9 @@ on:
   pull_request:
     branches: [main]
 
+permissions:
+  contents: read
+
 jobs:
   build-test:
     runs-on: ubuntu-latest
@@ -52,6 +55,13 @@ jobs:
 
       - name: Install Playwright browsers
         run: pnpm exec playwright install --with-deps chromium
+        env:
+          PLAYWRIGHT_BROWSERS_PATH: ${{ github.workspace }}/node_modules/.cache/ms-playwright
+
+      - name: Run React Router ecosystem tests
+        run: pnpm test:react-router-framework:failfast:no-build
 
       - name: Run E2E tests
-        run: pnpm e2e
+        run: pnpm e2e:no-build
+        env:
+          PLAYWRIGHT_BROWSERS_PATH: ${{ github.workspace }}/node_modules/.cache/ms-playwright

.gitignore

@@ -24,6 +24,8 @@ tests/react-router-framework/.tmp/
 playwright-report/
 test-results/
 
-# Nested Playwright artifacts (examples, fixtures)
+# Playwright fixture scratch and reports (framework test corpus)
+tests/react-router-framework/.tmp/
+tests/.tmp-dev-runtime/
 **/test-results/
 **/playwright-report/

CHANGELOG.md

@@ -62,7 +62,7 @@
 
 ### Minor Changes
 
-- 3c6d368: Bring Rsbuild plugin behavior closer to React Router's official Vite plugin.
+- 3c6d368: Bring Rsbuild plugin behavior closer to React Router framework behavior.
   - Add React Router config resolution + validations/warnings for closer framework parity
   - Add split route modules (route chunk entrypoints) including enforce mode validation
   - Improve `.client` module stubbing on the server (including `export *` re-exports)

README.md

@@ -111,10 +111,11 @@ export default {
 ```
 
 Use `ReactRouterRsbuildConfig` for Rsbuild projects so plugin-supported
-configuration such as `splitRouteModules` stays typed. The underlying route
-and config types come from `@react-router/dev`, which framework-mode apps
-already install for `routes.ts` helpers and typegen; it is declared as an
-optional peer dependency.
+configuration such as `splitRouteModules` stays typed across React Router 7
+and 8 releases. The underlying route and config types come from
+`@react-router/dev`, which framework-mode apps already install for
+`routes.ts` helpers and typegen; it is declared as an optional peer
+dependency.
 
 Commonly used options:
 
@@ -168,7 +169,7 @@ a better fit.
 
 ### SPA Mode (`ssr: false`)
 
-React Router's SPA Mode still requires a build-time server render of the root route to generate a hydratable `index.html` (this is how the official React Router Vite plugin works).
+React Router's SPA Mode still requires a build-time server render of the root route to generate a hydratable `index.html` (this is how this Rsbuild integration mirrors React Router framework behavior).
 
 When `ssr: false`:
 
@@ -688,14 +689,13 @@ inconclusive comparison before treating it as a performance result.
 ## React Router Framework Mode
 
 React Router "Framework Mode" wraps Data Mode using a Vite plugin. This Rsbuild
-plugin aims to match the important behaviors without depending on Vite:
+plugin aims to match the important framework behaviors on Rsbuild:
 
 - Typegen + Route Module API types (`./+types/*`)
 - Route module splitting (`splitRouteModules`)
 - SPA mode (`ssr: false`), SSR mode, and static prerendering (`prerender`)
 
-Some Vite-specific integrations (for example Vite's environment API + critical
-CSS endpoint) are not supported 1:1.
+Some upstream framework integrations are not supported 1:1.
 
 ## Examples
 
@@ -709,6 +709,7 @@ The repository includes several examples demonstrating different use cases:
 | [custom-node-server](./examples/custom-node-server)                     | Custom Express server with SSR          | 3003 | `pnpm dev` |
 | [cloudflare](./examples/cloudflare)                                     | Cloudflare Workers deployment           | 3004 | `pnpm dev` |
 | [client-only](./examples/client-only)                                   | `.client` modules with SSR hydration    | 3010 | `pnpm dev` |
+| [react-router-8](./examples/react-router-8)                             | React Router 8 framework-mode SSR       | 3020 | `pnpm dev` |
 | [epic-stack](./examples/epic-stack)                                     | Full-featured Epic Stack example        | 3005 | `pnpm dev` |
 | [federation/epic-stack](./examples/federation/epic-stack)               | Module Federation host                  | 3006 | `pnpm dev` |
 | [federation/epic-stack-remote](./examples/federation/epic-stack-remote) | Module Federation remote                | 3007 | `pnpm dev` |

benchmarks/synthetic-web-bundler-benchmark/app/root.tsx

@@ -1,24 +1,18 @@
-import type { LinksFunction, MetaFunction } from "react-router";
-import {
-  Links,
-  Meta,
-  Outlet,
-  Scripts,
-  ScrollRestoration,
-} from "react-router";
-import { IntlProvider } from "react-intl";
-import globalStyles from "./styles/global.css?url";
+import type { LinksFunction, MetaFunction } from 'react-router';
+import { Links, Meta, Outlet, Scripts, ScrollRestoration } from 'react-router';
+import { IntlProvider } from 'react-intl';
+import globalStyles from './styles/global.css?url';
 
 export const meta: MetaFunction = () => [
-  { title: "Synthetic Web Bundler Benchmark" },
+  { title: 'Synthetic Web Bundler Benchmark' },
   {
-    name: "description",
-    content: "A deterministic, non-product Vite and Rsbuild benchmark.",
+    name: 'description',
+    content: 'A deterministic, non-product Vite and Rsbuild benchmark.',
   },
 ];
 
 export const links: LinksFunction = () => [
-  { rel: "stylesheet", href: globalStyles },
+  { rel: 'stylesheet', href: globalStyles },
 ];
 
 export function Layout({ children }: { children: React.ReactNode }) {

examples/client-only/package.json

@@ -26,7 +26,6 @@
     "@types/react": "^19.2.10",
     "@types/react-dom": "^19.2.3",
     "rsbuild-plugin-react-router": "workspace:*",
-    "typescript": "^5.9.3",
-    "vite": "^7.3.1"
+    "typescript": "^5.9.3"
   }
 }

examples/client-only/tsconfig.json

@@ -7,7 +7,7 @@
   ],
   "compilerOptions": {
     "lib": ["DOM", "DOM.Iterable", "ES2022"],
-    "types": ["node", "vite/client"],
+    "types": ["node"],
     "target": "ES2022",
     "module": "ES2022",
     "moduleResolution": "bundler",

examples/cloudflare/tsconfig.node.json

@@ -1,6 +1,6 @@
 {
   "extends": "./tsconfig.json",
-  "include": ["tailwind.config.ts", "vite.config.ts"],
+  "include": ["tailwind.config.ts", "rsbuild.config.ts"],
   "compilerOptions": {
     "composite": true,
     "strict": true,

examples/custom-node-server/tsconfig.json

@@ -10,7 +10,7 @@
     "strict": true,
     "checkJs": true,
     "lib": ["DOM", "DOM.Iterable", "ES2022"],
-    "types": ["@rsbuild/core/types", "node"],
+    "types": ["node"],
     "target": "ES2022",
     "module": "ES2022",
     "moduleResolution": "bundler",

examples/default-template/package.json

@@ -37,8 +37,6 @@
     "string-replace-loader": "^3.3.0",
     "tailwindcss": "^4.1.18",
     "text-encoder-lite": "^2.0.0",
-    "typescript": "^5.9.3",
-    "vite": "^7.3.1",
-    "vite-tsconfig-paths": "^6.0.5"
+    "typescript": "^5.9.3"
   }
 }

examples/default-template/tests/e2e/dev-route-watch.test.ts

@@ -11,10 +11,7 @@ import { fileURLToPath } from 'node:url';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const appDirectory = join(__dirname, '../../app');
-const restartMarkerPath = join(
-  __dirname,
-  '../../build/client/.react-router/route-watch'
-);
+const restartMarkerPath = join(appDirectory, '..', '.react-router/route-watch');
 const devRoutesConfigPath = join(appDirectory, 'dev-routes.ts');
 const addedRoutePath = join(appDirectory, 'routes/dev-added-route.tsx');
 const addedRouteUrl = '/dev-added-route';

examples/default-template/tsconfig.json

@@ -6,16 +6,27 @@
     ".react-router/types/**/*"
   ],
   "compilerOptions": {
-    "lib": ["DOM", "DOM.Iterable", "ES2022"],
-    "types": ["node", "vite/client"],
+    "lib": [
+      "DOM",
+      "DOM.Iterable",
+      "ES2022"
+    ],
+    "types": [
+      "node"
+    ],
     "target": "ES2022",
     "module": "ES2022",
     "moduleResolution": "bundler",
     "jsx": "react-jsx",
-    "rootDirs": [".", "./.react-router/types"],
+    "rootDirs": [
+      ".",
+      "./.react-router/types"
+    ],
     "baseUrl": ".",
     "paths": {
-      "~/*": ["./app/*"]
+      "~/*": [
+        "./app/*"
+      ]
     },
     "esModuleInterop": true,
     "verbatimModuleSyntax": true,