fix(plugin-rsc): expose encodeFormAction option type and re-export encodeReply and createTemporaryReferenceSet from ssr (#1280)

Co-authored-by: Hiroshi Ogawa <4232207+hi-ogawa@users.noreply.github.com>
Co-authored-by: OpenCode <noreply@opencode.ai>
Co-authored-by: Hiroshi Ogawa <hi.ogawa.zz@gmail.com>

Author: 3 people

packages/plugin-rsc/README.md

@@ -496,17 +496,21 @@ function renderToReadableStream<T>(
 
 ### `@vitejs/plugin-rsc/ssr`
 
-This module re-exports RSC runtime API provided by `react-server-dom/client.edge`
+This module re-exports RSC runtime APIs provided by `react-server-dom/client.edge`:
 
-- `createFromReadableStream`: RSC deserialization (RSC stream -> React VDOM)
+- `createFromReadableStream`: Deserializes an RSC stream into a React VDOM
+- `encodeReply`: Serializes server function arguments
+- `createTemporaryReferenceSet`: Creates a temporary reference set shared by deserialization and reply serialization
 
 ### `@vitejs/plugin-rsc/browser`
 
-This module re-exports RSC runtime API provided by `react-server-dom/client.browser`
+This module re-exports RSC runtime APIs 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...
+- `createFromReadableStream`: Deserializes an RSC stream into a React VDOM
+- `createFromFetch`: Deserializes an RSC response from a fetch promise
+- `encodeReply`: Serializes server function arguments
+- `createTemporaryReferenceSet`: Creates a temporary reference set shared by deserialization and reply serialization
+- `setServerCallback`: Configures how server functions are called
 
 ## Tips
 

packages/plugin-rsc/e2e/ssr-encode-form-action.test.ts

@@ -0,0 +1,36 @@
+import { expect, test } from '@playwright/test'
+import { type Fixture, useFixture } from './fixture'
+import { testNoJs } from './helper'
+
+test.describe('dev', () => {
+  const f = useFixture({
+    root: 'examples/ssr-encode-form-action',
+    mode: 'dev',
+  })
+  defineTests(f)
+})
+
+test.describe('build', () => {
+  const f = useFixture({
+    root: 'examples/ssr-encode-form-action',
+    mode: 'build',
+  })
+  defineTests(f)
+})
+
+function defineTests(f: Fixture) {
+  testNoJs('custom form action encoding', async ({ page }) => {
+    await page.goto(f.url())
+
+    await expect(page.getByTestId('result')).toHaveText('initial')
+    const form = page.getByTestId('server-action-form')
+    await expect(form).toHaveAttribute('action', '/?custom-action=1')
+    await expect(
+      form.locator('input[name="$ACTION_REF_custom_prefix"]'),
+    ).toHaveCount(1)
+
+    await page.getByRole('button', { name: 'test-action' }).click()
+    await expect(page).toHaveURL(/\?custom-action=1$/)
+    await expect(page.getByTestId('result')).toHaveText('bound:form')
+  })
+}

packages/plugin-rsc/examples/ssr-encode-form-action/README.md

@@ -0,0 +1,92 @@
+# SSR `encodeFormAction`
+
+This example exercises the React Flight client APIs exposed by `@vitejs/plugin-rsc/ssr` for custom progressive-enhancement form encoding:
+
+- `createFromReadableStream`
+- `encodeReply`
+
+It renders one bound server-action form and submits it without JavaScript.
+
+## Background
+
+During SSR, `createFromReadableStream` deserializes an RSC stream and reconstructs its server references. React attaches a default `$$FORM_ACTION` implementation to those references so that a server function can be rendered as a native HTML form action.
+
+For an unbound server reference, React's default encoder emits an `$ACTION_ID_*` field. For a bound reference, it serializes `{ id, bound }` with the Flight reply serializer and emits `$ACTION_REF_*` plus the associated `$ACTION_*` multipart fields. A server can later pass that form data to `decodeAction` to reconstruct and invoke the action.
+
+Frameworks can replace this behavior through the `encodeFormAction` option accepted by the SSR Flight client. The callback may customize the form's action URL, method, encoding, field name, and additional form data.
+
+The callback replaces React's default encoder rather than decorating its result. A framework that wants to change only the action URL while preserving compatibility with `decodeAction` must therefore recreate React's default multipart field layout. Calling `encodeReply({ id, bound })` from the same Flight client instance provides the matching serializer without importing the vendored runtime directly.
+
+## Upstream Design
+
+React introduced `encodeFormAction` in [React PR #27563, "[Flight] Allow custom encoding of the form action"](https://github.com/react/react/pull/27563). The PR describes server-action endpoints and their protocols as meta-framework responsibilities. React provides `callServer` for browser-initiated calls and summarizes the new hook as:
+
+> `encodeFormAction` is to the SSR what `callServer` is to the Browser.
+
+React's default current-page POST and `$ACTION_*` multipart protocol are therefore defaults rather than requirements. An SSR framework may replace the form action URL and encoded fields through `encodeFormAction`. The browser Flight client does not accept this option because native progressive-enhancement metadata is generated during SSR.
+
+The upstream implementation wires the callback into server references as `$$FORM_ACTION`, which React DOM reads while rendering forms. React has lower-level tests for custom `$$FORM_ACTION` metadata, but it does not have an end-to-end test that passes `encodeFormAction` through Flight deserialization and then submits the resulting form. This example covers that integration path.
+
+## Waku Motivation
+
+[Waku PR #2191](https://github.com/wakujs/waku/pull/2191) directly motivates exposing these APIs from `@vitejs/plugin-rsc/ssr`. Both ordinary HTML forms and React server-action forms submitted without JavaScript can use `multipart/form-data`, but React's `$ACTION_*` discriminator is inside the single-read request body. Waku cannot inspect that body to classify the request and still pass an untouched request to an ordinary form handler.
+
+Waku supplies `encodeFormAction` during SSR to add a marker to the form's action URL. It can classify the request from the URL before consuming the body, while `encodeReply({ id, bound })` lets it preserve React's default multipart field layout for `decodeAction`.
+
+This requirement falls between React's two supported modes. React can provide its complete default protocol, or a framework can replace it with `encodeFormAction`, but the callback cannot obtain and modify the default `ReactCustomFormAction`. Waku wants to retain the default protocol and change only the action URL, so it must reproduce React's `{ id, bound }` serialization, `$ACTION_REF_*` naming, field prefixing, and suspension behavior.
+
+The callback also receives no stable server-reference identity, which makes it difficult to distinguish the same action when it is used both unbound and bound on the client. Waku handles this with a promise-identity heuristic and documents the remaining ambiguity.
+
+`useActionState` exposes another gap. When a permalink is provided, React applies it after `encodeFormAction` and replaces the encoder's action URL. Waku must currently require the permalink itself to contain the marker. A complete upstream solution would let a framework transform the final action URL after permalink resolution while retaining React's default encoding, or otherwise provide a context-bound default encoder that can be composed safely.
+
+## Next.js Comparison
+
+Next.js takes a different approach. It does not customize `encodeFormAction` or add an action URL marker for progressive-enhancement forms. Forms submitted without JavaScript use React's default `$ACTION_ID_*` or `$ACTION_REF_*` fields, and Next treats a multipart `POST` as a possible action request before calling `decodeAction`. This works because the App Router owns the request path and does not need to preserve the body for an ordinary form handler. Hydrated server-action calls use a separate `Next-Action` request header.
+
+Next.js does use the Flight client's `encodeReply` and `createTemporaryReferenceSet` in a server runtime for `"use cache"` key serialization, but not for its Flight-to-HTML form-rendering path. `@vitejs/plugin-rsc` follows the same pattern through its `/rsc/client` entry point, which exposes `encodeReply` and `createClientTemporaryReferenceSet` for client-protocol work inside the RSC environment.
+
+## Plugin Scope
+
+The `/ssr` exports expose corresponding Flight client-protocol capabilities in the separate Flight-to-HTML environment. This is a low-level unblock rather than the ideal framework API: the plugin re-exports capabilities already provided by its vendored `react-server-dom/client.edge` runtime so frameworks can implement today's workaround without deep imports or protocol-version mismatches.
+
+The plugin does not make React's experimental `$ACTION_*` protocol stable, nor does it solve the missing default-encoding composition or final-URL transformation hooks. Those ergonomic improvements belong in an upstream React feature request.
+
+## Example Flow
+
+The example performs this complete round trip:
+
+```text
+RSC render
+  -> SSR createFromReadableStream({ encodeFormAction })
+  -> encodeReply({ id, bound })
+  -> custom action URL and $ACTION_REF_* fields
+  -> native multipart POST without JavaScript
+  -> decodeAction
+  -> bound server action execution
+```
+
+The rendered form binds the value `"bound"` to its server action and submits an input containing `"form"`. After `decodeAction` reconstructs and invokes the action, the response displays `bound:form`.
+
+## Structure
+
+- `src/framework/entry.rsc.tsx` handles requests, calls `decodeAction` for form submissions, renders the RSC payload, and delegates HTML rendering to the SSR environment.
+- `src/framework/entry.ssr.tsx` recreates React's default bound-action encoding with a custom action URL, wires it into deserialization, and renders the payload with React DOM.
+- `src/action.ts` contains the server action.
+- `src/root.tsx` renders the form and action result.
+- `src/state.ts` stores the result across the POST and subsequent render.
+
+## Scope
+
+The encoder is intentionally limited to one bound action. It uses a fixed field prefix and caches serialization by the bound-arguments promise so React can suspend and retry SSR while `encodeReply` completes.
+
+A production framework must generate unique field prefixes and handle unbound references, multiple forms, retries, errors, and any framework-specific request classification. The custom query parameter in this example only proves that React applies the returned action URL; the request handler does not depend on that marker for classification.
+
+## Running
+
+```bash
+pnpm dev
+pnpm build
+pnpm preview
+```
+
+The corresponding Playwright coverage is in `../../e2e/ssr-encode-form-action.test.ts` and runs the no-JavaScript submission in both development and production-build modes.

packages/plugin-rsc/examples/ssr-encode-form-action/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@vitejs/plugin-rsc-examples-ssr-encode-form-action",
+  "version": "0.0.0",
+  "private": true,
+  "license": "MIT",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-rsc": "latest",
+    "vite": "^8.1.4"
+  }
+}

packages/plugin-rsc/examples/ssr-encode-form-action/src/action.ts

@@ -0,0 +1,7 @@
+'use server'
+
+import { setServerState } from './state'
+
+export async function testAction(boundValue: string, formData: FormData) {
+  setServerState(`${boundValue}:${formData.get('value')}`)
+}

packages/plugin-rsc/examples/ssr-encode-form-action/src/framework/entry.browser.ts

@@ -0,0 +1 @@
+// This example only tests progressive enhancement without JavaScript.

packages/plugin-rsc/examples/ssr-encode-form-action/src/framework/entry.rsc.tsx

@@ -0,0 +1,20 @@
+import { decodeAction, renderToReadableStream } from '@vitejs/plugin-rsc/rsc'
+import { Root } from '../root'
+
+async function handler(request: Request): Promise<Response> {
+  if (request.method === 'POST') {
+    const action = await decodeAction(await request.formData())
+    await action()
+  }
+
+  const rscStream = renderToReadableStream({ root: <Root /> })
+  const ssr = await import.meta.viteRsc.loadModule<
+    typeof import('./entry.ssr')
+  >('ssr', 'index')
+  const htmlStream = await ssr.renderHtml(rscStream)
+  return new Response(htmlStream, {
+    headers: { 'content-type': 'text/html;charset=utf-8' },
+  })
+}
+
+export default { fetch: handler }

packages/plugin-rsc/examples/ssr-encode-form-action/src/framework/entry.ssr.tsx

@@ -0,0 +1,110 @@
+import {
+  createFromReadableStream,
+  encodeReply,
+  type EncodeFormActionCallback,
+} from '@vitejs/plugin-rsc/ssr'
+import React from 'react'
+import { renderToReadableStream } from 'react-dom/server.edge'
+
+type RscPayload = { root: React.ReactNode }
+
+export async function renderHtml(
+  rscStream: ReadableStream<Uint8Array>,
+): Promise<ReadableStream<Uint8Array>> {
+  let payload: Promise<RscPayload> | undefined
+  function SsrRoot() {
+    payload ??= createFromReadableStream<RscPayload>(rscStream, {
+      encodeFormAction: customEncodeFormAction,
+    })
+    return React.use(payload).root
+  }
+
+  return renderToReadableStream(<SsrRoot />)
+}
+
+// Preserve React's default form metadata, but post to a custom URL.
+const customEncodeFormAction: EncodeFormActionCallback = (id, bound) => {
+  const defaultResult = defaultEncodeFormAction(id, bound)
+  return {
+    ...defaultResult,
+    action: '/?custom-action=1',
+  }
+}
+
+// Recreates React's default bound-action encoding:
+// https://github.com/react/react/blob/8d48183291870898ec42ac1f84482d9d26789424/packages/react-client/src/ReactFlightReplyClient.js#L462-L508
+
+// React supplies this internally, but encodeFormAction does not receive it.
+const identifierPrefix = 'custom_prefix'
+
+type FormDataThenable = Promise<FormData> & {
+  status?: 'pending' | 'fulfilled' | 'rejected'
+  value?: FormData
+  reason?: unknown
+}
+
+// React caches by its internal server-reference object. The callback only exposes
+// the bound promise, so this example uses that promise as the cache identity.
+const boundCache = new WeakMap<Promise<unknown[]>, FormDataThenable>()
+
+const defaultEncodeFormAction: EncodeFormActionCallback = (id, bound) => {
+  let data: null | FormData = null
+  let name
+  // React's custom callback always receives a promise, so it cannot distinguish
+  // an unbound reference from one bound with no arguments. This example is bound.
+  const boundPromise = bound
+  if (boundPromise !== null) {
+    const reference = { id, bound }
+    let thenable = boundCache.get(boundPromise)
+    if (!thenable) {
+      thenable = encodeFormData(reference)
+      boundCache.set(boundPromise, thenable)
+    }
+    if (thenable.status === 'rejected') {
+      throw thenable.reason
+    } else if (thenable.status !== 'fulfilled') {
+      throw thenable
+    }
+    const encodedFormData = thenable.value!
+    const prefixedData = new FormData()
+    encodedFormData.forEach((value, key) => {
+      prefixedData.append('$ACTION_' + identifierPrefix + ':' + key, value)
+    })
+    data = prefixedData
+    name = '$ACTION_REF_' + identifierPrefix
+  }
+
+  return {
+    name: name,
+    method: 'POST',
+    encType: 'multipart/form-data',
+    data: data,
+  }
+}
+
+function encodeFormData(reference: {
+  id: string
+  bound: Promise<unknown[]>
+}): FormDataThenable {
+  // Unlike React's internal processReply, the public encodeReply returns a
+  // regular promise, so instrument it with the status React's renderer expects.
+  const thenable = encodeReply(reference as never).then(
+    (body) => {
+      if (typeof body === 'string') {
+        const data = new FormData()
+        data.append('0', body)
+        body = data
+      }
+      thenable.status = 'fulfilled'
+      thenable.value = body
+      return body
+    },
+    (reason) => {
+      thenable.status = 'rejected'
+      thenable.reason = reason
+      throw reason
+    },
+  ) as FormDataThenable
+  thenable.status = 'pending'
+  return thenable
+}

packages/plugin-rsc/examples/ssr-encode-form-action/src/root.tsx

@@ -0,0 +1,19 @@
+import { testAction } from './action'
+import { getServerState } from './state'
+
+export function Root() {
+  return (
+    <html>
+      <body>
+        <form
+          data-testid="server-action-form"
+          action={testAction.bind(null, 'bound')}
+        >
+          <input name="value" defaultValue="form" />
+          <button type="submit">test-action</button>
+        </form>
+        <output data-testid="result">{getServerState()}</output>
+      </body>
+    </html>
+  )
+}

packages/plugin-rsc/examples/ssr-encode-form-action/src/state.ts

@@ -0,0 +1,9 @@
+let result = 'initial'
+
+export function getServerState() {
+  return result
+}
+
+export function setServerState(value: string) {
+  result = value
+}