feat(plugin-rsc): expose onClientReference callback in renderToReadableStream

Add an experimental `onClientReference` callback option to `renderToReadableStream`
that fires when a client reference is encountered during RSC rendering. The callback
provides the reference id, name, and resolved asset dependencies (JS/CSS files).

This enables use cases like:
- Tracking which client components are used in a render
- Collecting asset dependencies for preloading
- Debugging client reference resolution

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: hi-ogawa

packages/plugin-rsc/README.md

@@ -453,6 +453,45 @@ This module re-exports RSC runtime API provided by `react-server-dom/server.edge
 - `decodeAction/decodeReply/decodeFormState/loadServerAction/createTemporaryReferenceSet`
 - `encodeReply/createClientTemporaryReferenceSet`
 
+#### Vite-specific extension: `renderToReadableStream`
+
+> [!NOTE]
+> This is a Vite-specific extension to the standard React RSC API. The official `react-server-dom` does not provide this callback mechanism.
+
+The plugin extends `renderToReadableStream` with an optional third parameter for Vite-specific options:
+
+```ts
+function renderToReadableStream<T>(
+  data: T,
+  options?: object, // standard react-server-dom options
+  extraOptions?: {
+    onClientReference?: (metadata: {
+      id: string
+      name: string
+      deps: { js: string[]; css: string[] }
+    }) => void
+  },
+): ReadableStream<Uint8Array>
+```
+
+The `onClientReference` callback is invoked whenever a client reference is encountered during RSC serialization. This enables use cases such as:
+
+- Tracking which client components are used in a render
+- Collecting asset dependencies for preloading or analytics
+- Debugging client reference resolution
+
+```tsx
+import { renderToReadableStream } from '@vitejs/plugin-rsc/rsc'
+
+const clientRefs: string[] = []
+const stream = renderToReadableStream(root, options, {
+  onClientReference({ id, name, deps }) {
+    clientRefs.push(`${id}#${name}`)
+    // deps.js and deps.css contain the resolved asset paths
+  },
+})
+```
+
 ### `@vitejs/plugin-rsc/ssr`
 
 This module re-exports RSC runtime API provided by `react-server-dom/client.edge`

packages/plugin-rsc/e2e/basic.test.ts

@@ -237,6 +237,24 @@ function defineTest(f: Fixture) {
     expect(f.proc().stderr()).toBe('')
   })
 
+  test('onClientReference callback', async ({ page }) => {
+    const response = await page.request.get(f.url('__test_onClientReference'))
+    expect(response.ok()).toBe(true)
+    const data = await response.json()
+    expect(data).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          id: expect.any(String),
+          name: expect.any(String),
+          deps: expect.objectContaining({
+            js: expect.any(Array),
+            css: expect.any(Array),
+          }),
+        }),
+      ]),
+    )
+  })
+
   test('client component', async ({ page }) => {
     await page.goto(f.url())
     await waitForHydration(page)

packages/plugin-rsc/examples/basic/src/framework/entry.rsc.tsx

@@ -79,7 +79,18 @@ async function handleRequest({
 
   const rscPayload: RscPayload = { root: getRoot(), formState, returnValue }
   const rscOptions = { temporaryReferences }
-  const rscStream = renderToReadableStream<RscPayload>(rscPayload, rscOptions)
+  const debugClientReferences: unknown[] = []
+  const rscStream = renderToReadableStream<RscPayload>(rscPayload, rscOptions, {
+    onClientReference(metadata) {
+      debugClientReferences.push(metadata)
+    },
+  })
+
+  // test `onClientReference` callback
+  if (renderRequest.url.pathname === '/__test_onClientReference') {
+    await rscStream.pipeTo(new WritableStream({ write() {} }))
+    return Response.json(debugClientReferences)
+  }
 
   // Respond RSC stream without HTML rendering as decided by `RenderRequest`
   if (renderRequest.isRsc) {

packages/plugin-rsc/src/core/rsc.ts

@@ -116,7 +116,12 @@ export function createServerDecodeClientManifest(): ModuleMap {
   )
 }
 
-export function createClientManifest(): BundlerConfig {
+export function createClientManifest(options?: {
+  /**
+   * @internal
+   */
+  onClientReference?: (metadata: { id: string; name: string }) => void
+}): BundlerConfig {
   const cacheTag = import.meta.env.DEV ? createReferenceCacheTag() : ''
 
   return new Proxy(
@@ -127,6 +132,7 @@ export function createClientManifest(): BundlerConfig {
         let [id, name] = $$id.split('#')
         tinyassert(id)
         tinyassert(name)
+        options?.onClientReference?.({ id, name })
         return {
           id: id + cacheTag,
           name,

packages/plugin-rsc/src/react/rsc.ts

@@ -14,10 +14,18 @@ export { loadServerAction, setRequireModule } from '../core/rsc'
 export function renderToReadableStream<T>(
   data: T,
   options?: object,
+  extraOptions?: {
+    /**
+     * @internal
+     */
+    onClientReference?: (metadata: { id: string; name: string }) => void
+  },
 ): ReadableStream<Uint8Array> {
   return ReactServer.renderToReadableStream(
     data,
-    createClientManifest(),
+    createClientManifest({
+      onClientReference: extraOptions?.onClientReference,
+    }),
     options,
   )
 }

packages/plugin-rsc/src/rsc.tsx

@@ -1,6 +1,9 @@
+import assetsManifest from 'virtual:vite-rsc/assets-manifest'
 import serverReferences from 'virtual:vite-rsc/server-references'
 import { setRequireModule } from './core/rsc'
+import type { ResolvedAssetDeps } from './plugin'
 import { toReferenceValidationVirtual } from './plugins/shared'
+import { renderToReadableStream as originalRenderToReadableStream } from './react/rsc'
 
 export {
   createClientManifest,
@@ -36,3 +39,32 @@ function initialize(): void {
     },
   })
 }
+
+export function renderToReadableStream<T>(
+  data: T,
+  options?: object,
+  extraOptions?: {
+    /**
+     * @experimental
+     */
+    onClientReference?: (metadata: {
+      id: string
+      name: string
+      deps: ResolvedAssetDeps
+    }) => void
+  },
+): ReadableStream<Uint8Array> {
+  return originalRenderToReadableStream(data, options, {
+    onClientReference(metadata) {
+      const deps = assetsManifest.clientReferenceDeps[metadata.id] ?? {
+        js: [],
+        css: [],
+      }
+      extraOptions?.onClientReference?.({
+        id: metadata.id,
+        name: metadata.name,
+        deps,
+      })
+    },
+  })
+}