Merge remote-tracking branch 'upstream/main' into chore-rsc-nightly

github-actions[bot] · github-actions[bot] · commit 677ca1d789d8 · 2025-08-17T00:14:28.000Z
diff --git a/packages/plugin-rsc/README.md b/packages/plugin-rsc/README.md
@@ -4,10 +4,10 @@ This package provides [React Server Components](https://react.dev/reference/rsc/
 
 ## Features
 
-- **Framework-less RSC experience**: The plugin implements [RSC conventions](https://react.dev/reference/rsc/server-components) and provides low level `react-server-dom` runtime API without framework-specific abstractions.
-- **CSS support**: CSS is automatically code-split both at client and server components and they are injected upon rendering.
+- **Framework-agnostic**: The plugin implements [RSC bundler features](https://react.dev/reference/rsc/server-components) and provides low level RSC runtime (`react-server-dom`) API without framework-specific abstractions.
+- **Runtime-agnostic**: Built on [Vite environment API](https://vite.dev/guide/api-environment.html) and works with other runtimes (e.g., [`@cloudflare/vite-plugin`](https://github.com/cloudflare/workers-sdk/tree/main/packages/vite-plugin-cloudflare)).
 - **HMR support**: Enables editing both client and server components without full page reloads.
-- **Runtime agnostic**: Built on [Vite environment API](https://vite.dev/guide/api-environment.html) and works with other runtimes (e.g., [`@cloudflare/vite-plugin`](https://github.com/cloudflare/workers-sdk/tree/main/packages/vite-plugin-cloudflare)).
+- **CSS support**: CSS is automatically code-split both at client and server components and they are injected upon rendering.
 
 ## Getting Started
 
@@ -19,14 +19,17 @@ npx degit vitejs/vite-plugin-react/packages/plugin-rsc/examples/starter my-app
 
 ## Examples
 
-- [`./examples/starter`](./examples/starter)
-  - This example provides an in-depth overview of API with inline comments to explain how they function within RSC-powered React application.
-- [`./examples/react-router`](./examples/react-router)
-  - This demonstrates how to integrate [experimental React Router RSC API](https://remix.run/blog/rsc-preview). React Router now provides [official RSC support](https://reactrouter.com/how-to/react-server-components), so it's recommended to follow React Router's official documentation for the latest integration.
-- [`./examples/basic`](./examples/basic)
-  - This is mainly used for e2e testing and include various advanced RSC usages (e.g. `"use cache"` example).
-- [`./examples/ssg`](./examples/ssg)
-  - Static site generation (SSG) example with MDX and client components for interactivity.
+**Start here:** [`./examples/starter`](./examples/starter) - Recommended for understanding the plugin
+
+- Provides an in-depth overview of API with inline comments to explain how they function within RSC-powered React application.
+
+**Integration examples:**
+
+- [`./examples/basic`](./examples/basic) - Advanced RSC features and testing
+  - This is mainly used for e2e testing and includes various advanced RSC usages (e.g. `"use cache"` example).
+- [`./examples/ssg`](./examples/ssg) - Static site generation with MDX and client components for interactivity.
+- [`./examples/react-router`](./examples/react-router) - React Router RSC integration
+  - Demonstrates how to integrate [experimental React Router RSC API](https://remix.run/blog/rsc-preview). React Router now provides [official RSC support](https://reactrouter.com/how-to/react-server-components), so it's recommended to follow React Router's official documentation for the latest integration.
 
 ## Basic Concepts
 
@@ -132,7 +135,7 @@ import * as ReactServer from '@vitejs/plugin-rsc/rsc' // re-export of react-serv
 
 // the plugin assumes `rsc` entry having default export of request handler
 export default async function handler(request: Request): Promise<Response> {
-  // serialization React VDOM to RSC stream
+  // serialize React VDOM to RSC stream
   const root = (
     <html>
       <body>
@@ -193,51 +196,26 @@ export async function handleSsr(rscStream: ReadableStream) {
 - [`entry.browser.tsx`](./examples/starter/src/framework/entry.browser.tsx)
 
 ```tsx
-import * as ReactClient from "@vitejs/plugin-rsc/browser"; // re-export of react-server-dom/client.browser
-import * as ReactDOMClient from "react-dom/client";
+import * as ReactClient from '@vitejs/plugin-rsc/browser' // re-export of react-server-dom/client.browser
+import * as ReactDOMClient from 'react-dom/client'
 
 async function main() {
   // fetch and deserialize RSC stream back to React VDOM
-  const rscResponse = await fetch(window.location.href + ".rsc);
-  const root = await ReactClient.createFromReadableStream(rscResponse.body);
+  const rscResponse = await fetch(window.location.href + '.rsc')
+  const root = await ReactClient.createFromReadableStream(rscResponse.body)
 
   // hydration (traditional CSR)
-  ReactDOMClient.hydrateRoot(document, root);
+  ReactDOMClient.hydrateRoot(document, root)
 }
 
-main();
+main()
 ```
 
-## `react-server-dom` API
-
-### `@vitejs/plugin-rsc/rsc`
-
-This module re-exports RSC runtime API provided by `react-server-dom/server.edge` and `react-server-dom/client.edge` such as:
-
-- `renderToReadableStream`: RSC serialization (React VDOM -> RSC stream)
-- `createFromReadableStream`: RSC deserialization (RSC stream -> React VDOM). This is also available on rsc environment itself. For example, it allows saving serailized RSC and deserializing it for later use.
-- `decodeAction/decodeReply/decodeFormState/loadServerAction/createTemporaryReferenceSet`
-- `encodeReply/createClientTemporaryReferenceSet`
-
-### `@vitejs/plugin-rsc/ssr`
-
-This module re-exports RSC runtime API provided by `react-server-dom/client.edge`
-
-- `createFromReadableStream`: RSC deserialization (RSC stream -> React VDOM)
-
-### `@vitejs/plugin-rsc/browser`
-
-This module re-exports RSC runtime API provided by `react-server-dom/client.browser`
-
-- `createFromReadableStream`: RSC deserialization (RSC stream -> React VDOM)
-- `createFromFetch`: a robust way of `createFromReadableStream((await fetch("...")).body)`
-- `encodeReply/setServerCallback`: server function related...
-
 ## Environment helper API
 
 The plugin provides an additional helper for multi environment interaction.
 
-### available on `rsc` or `ssr` environment
+### Available on `rsc` or `ssr` environment
 
 #### `import.meta.viteRsc.loadModule`
 
@@ -260,7 +238,7 @@ ssrModule.renderHTML(...);
 export function renderHTML(...) {}
 ```
 
-### available on `rsc` environment
+### Available on `rsc` environment
 
 #### `import.meta.viteRsc.loadCss`
 
@@ -287,7 +265,7 @@ export function ServerPage() {
 }
 ```
 
-Where specifying `loadCss(<id>)`, it will collect css through the server module resolved by `<id>`.
+When specifying `loadCss(<id>)`, it will collect css through the server module resolved by `<id>`.
 
 ```tsx
 // virtual:my-framework-helper
@@ -324,7 +302,7 @@ export function Page(props) {
   return <div>...</div>
 }
 
-// my-route.css?vite-rsc-css-export=Page
+// my-route.tsx?vite-rsc-css-export=Page
 function Page(props) {
   return <div>...</div>
 }
@@ -341,14 +319,13 @@ function __Page(props) {
 export { __Page as Page }
 ```
 
-### available on `ssr` environment
+### Available on `ssr` environment
 
 #### `import.meta.viteRsc.loadBootstrapScriptContent("index")`
 
 This provides a raw js code to execute a browser entry file specified by `environments.client.build.rollupOptions.input.index`. This is intended to be used with React DOM SSR API, such as [`renderToReadableStream`](https://react.dev/reference/react-dom/server/renderToReadableStream)
 
 ```js
-import bootstrapScriptContent from 'virtual:vite-rsc/bootstrap-script-content'
 import { renderToReadableStream } from 'react-dom/server.edge'
 
 const bootstrapScriptContent =
@@ -358,7 +335,7 @@ const htmlStream = await renderToReadableStream(reactNode, {
 })
 ```
 
-### available on `client` environment
+### Available on `client` environment
 
 #### `rsc:update` event
 
@@ -420,6 +397,31 @@ export default defineConfig({
 })
 ```
 
+## RSC runtime (react-server-dom) API
+
+### `@vitejs/plugin-rsc/rsc`
+
+This module re-exports RSC runtime API provided by `react-server-dom/server.edge` and `react-server-dom/client.edge` such as:
+
+- `renderToReadableStream`: RSC serialization (React VDOM -> RSC stream)
+- `createFromReadableStream`: RSC deserialization (RSC stream -> React VDOM). This is also available on rsc environment itself. For example, it allows saving serialized RSC and deserializing it for later use.
+- `decodeAction/decodeReply/decodeFormState/loadServerAction/createTemporaryReferenceSet`
+- `encodeReply/createClientTemporaryReferenceSet`
+
+### `@vitejs/plugin-rsc/ssr`
+
+This module re-exports RSC runtime API provided by `react-server-dom/client.edge`
+
+- `createFromReadableStream`: RSC deserialization (RSC stream -> React VDOM)
+
+### `@vitejs/plugin-rsc/browser`
+
+This module re-exports RSC runtime API provided by `react-server-dom/client.browser`
+
+- `createFromReadableStream`: RSC deserialization (RSC stream -> React VDOM)
+- `createFromFetch`: a robust way of `createFromReadableStream((await fetch("...")).body)`
+- `encodeReply/setServerCallback`: server function related...
+
 ## High level API
 
 > [!NOTE]
@@ -473,6 +475,10 @@ export function Page() {
 }
 ```
 
+## Canary and Experimental channel releases
+
+See https://github.com/vitejs/vite-plugin-react/pull/524 for how to install the package for React [canary](https://react.dev/community/versioning-policy#canary-channel) and [experimental](https://react.dev/community/versioning-policy#all-release-channels) usages.
+
 ## Credits
 
 This project builds on fundamental techniques and insights from pioneering Vite RSC implementations.
diff --git a/packages/plugin-rsc/examples/basic/package.json b/packages/plugin-rsc/examples/basic/package.json
@@ -33,5 +33,9 @@
     "vite": "^7.1.1",
     "vite-plugin-inspect": "^11.3.2",
     "wrangler": "^4.28.1"
+  },
+  "stackblitz": {
+    "installDependencies": false,
+    "startCommand": "pnpm i && pnpm dev"
   }
 }
diff --git a/packages/plugin-rsc/examples/basic/src/routes/import-meta-glob/dep.tsx b/packages/plugin-rsc/examples/basic/src/routes/import-meta-glob/dep.tsx
@@ -0,0 +1,3 @@
+export default function Dep() {
+  return <>test-import-meta-glob</>
+}
diff --git a/packages/plugin-rsc/examples/basic/src/routes/import-meta-glob/server.tsx b/packages/plugin-rsc/examples/basic/src/routes/import-meta-glob/server.tsx
@@ -0,0 +1,4 @@
+export async function TestImportMetaGlob() {
+  const mod: any = await Object.values(import.meta.glob('./dep.tsx'))[0]()
+  return <mod.default />
+}
diff --git a/packages/plugin-rsc/examples/basic/src/routes/react-cache/server.tsx b/packages/plugin-rsc/examples/basic/src/routes/react-cache/server.tsx
@@ -6,14 +6,12 @@ import React from 'react'
 
 export async function TestReactCache(props: { url: URL }) {
   if (props.url.searchParams.has('test-react-cache')) {
-    await Promise.all([
-      testCacheFn('test1'),
-      testCacheFn('test2'),
-      testCacheFn('test1'),
-      testNonCacheFn('test1'),
-      testNonCacheFn('test2'),
-      testNonCacheFn('test1'),
-    ])
+    await testCacheFn('test1')
+    await testCacheFn('test2')
+    await testCacheFn('test1')
+    await testNonCacheFn('test1')
+    await testNonCacheFn('test2')
+    await testNonCacheFn('test1')
   } else {
     cacheFnCount = 0
     nonCacheFnCount = 0
diff --git a/packages/plugin-rsc/examples/basic/src/routes/root.tsx b/packages/plugin-rsc/examples/basic/src/routes/root.tsx
@@ -36,6 +36,7 @@ import { TestHmrSharedServer } from './hmr-shared/server'
 import { TestHmrSharedClient } from './hmr-shared/client'
 import { TestHmrSharedAtomic } from './hmr-shared/atomic/server'
 import { TestCssQueries } from './css-queries/server'
+import { TestImportMetaGlob } from './import-meta-glob/server'
 
 export function Root(props: { url: URL }) {
   return (
@@ -85,6 +86,7 @@ export function Root(props: { url: URL }) {
         <TestUseCache />
         <TestReactCache url={props.url} />
         <TestCssQueries />
+        <TestImportMetaGlob />
       </body>
     </html>
   )
diff --git a/packages/plugin-rsc/examples/basic/vite.config.ts b/packages/plugin-rsc/examples/basic/vite.config.ts
@@ -131,6 +131,7 @@ export default { fetch: handler };
         }
       },
     },
+    testScanPlugin(),
   ],
   build: {
     minify: false,
@@ -158,6 +159,38 @@ export default { fetch: handler };
   },
 }) as any
 
+function testScanPlugin(): Plugin[] {
+  const moduleIds: { name: string; ids: string[] }[] = []
+  return [
+    {
+      name: 'test-scan',
+      apply: 'build',
+      buildEnd() {
+        moduleIds.push({
+          name: this.environment.name,
+          ids: [...this.getModuleIds()],
+        })
+      },
+      buildApp: {
+        order: 'post',
+        async handler() {
+          // client scan build discovers additional modules for server references.
+          const [m1, m2] = moduleIds.filter((m) => m.name === 'rsc')
+          const diff = m2.ids.filter((id) => !m1.ids.includes(id))
+          assert(diff.length > 0)
+
+          // but make sure it's not due to import.meta.glob
+          // https://github.com/vitejs/rolldown-vite/issues/373
+          assert.equal(
+            diff.find((id) => id.includes('import-meta-glob/dep.tsx')),
+            undefined,
+          )
+        },
+      },
+    },
+  ]
+}
+
 function vitePluginUseCache(): Plugin[] {
   return [
     {
diff --git a/packages/plugin-rsc/src/plugin.ts b/packages/plugin-rsc/src/plugin.ts
@@ -40,6 +40,7 @@ import {
 import { cjsModuleRunnerPlugin } from './plugins/cjs'
 import { evalValue, parseIdQuery } from './plugins/utils'
 import { createDebug } from '@hiogawa/utils'
+import { transformScanBuildStrip } from './plugins/scan'
 
 // state for build orchestration
 let serverReferences: Record<string, string> = {}
@@ -901,19 +902,16 @@ globalThis.AsyncLocalStorage = __viteRscAyncHooks.AsyncLocalStorage;
   ]
 }
 
+// During scan build, we strip all code but imports to
+// traverse module graph faster and just discover client/server references.
 function scanBuildStripPlugin(): Plugin {
   return {
     name: 'rsc:scan-strip',
     apply: 'build',
     enforce: 'post',
-    transform(code, _id, _options) {
+    async transform(code, _id, _options) {
       if (!isScanBuild) return
-      // During server scan, we strip all code but imports to only discover client/server references.
-      const [imports] = esModuleLexer.parse(code)
-      const output = imports
-        .map((e) => e.n && `import ${JSON.stringify(e.n)};\n`)
-        .filter(Boolean)
-        .join('')
+      const output = await transformScanBuildStrip(code)
       return { code: output, map: { mappings: '' } }
     },
   }
diff --git a/packages/plugin-rsc/src/plugins/scan.test.ts b/packages/plugin-rsc/src/plugins/scan.test.ts
@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'vitest'
+import { transformScanBuildStrip } from './scan'
+
+describe(transformScanBuildStrip, () => {
+  it('basic', async () => {
+    const input = `\
+import { a } from "a";
+import "b";
+import(String("c"))
+import.meta.glob("d", {
+  query: "?e",
+})
+import.meta.globee("d", { query: "?e" })
+export default "foo";
+`
+    expect(await transformScanBuildStrip(input)).toMatchInlineSnapshot(`
+      "import "a";
+      import "b";
+      console.log(import.meta.glob("d", {
+        query: "?e",
+      }));
+      "
+    `)
+  })
+})
diff --git a/packages/plugin-rsc/src/plugins/scan.ts b/packages/plugin-rsc/src/plugins/scan.ts

Original file line number	Diff line number	Diff line change
`@@ -33,5 +33,9 @@`
`33`	`33`	`"vite": "^7.1.1",`
`34`	`34`	`"vite-plugin-inspect": "^11.3.2",`
`35`	`35`	`"wrangler": "^4.28.1"`
	`36`	`+ },`
	`37`	`+ "stackblitz": {`
	`38`	`+ "installDependencies": false,`
	`39`	`+ "startCommand": "pnpm i && pnpm dev"`
`36`	`40`	`}`
`37`	`41`	`}`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+export default function Dep() {`
	`2`	`+ return <>test-import-meta-glob</>`
	`3`	`+}`